torusguard 0.9.2

package/.torusguard/workflows/report.md

@@ -0,0 +1,95 @@
+---
+description: Executive posture reporting, cluster analysis, signed compliance audit, and OASIS SARIF v2.1.0 structured export.
+tools: Read, Grep, Glob, Bash, Write
+version: 0.9.2
+agent: reviewer
+lifecycle-phase: Phase 7 (Reporting & SARIF Export)
+required-skills:
+  - torusguard-report
+scripts-binding:
+  - .torusguard/scripts/sarif_exporter.py
+  - .torusguard/scripts/run_manager.py
+---
+
+# /torusguard report — Unified Security Posture Report & SARIF Export
+
+$ARGUMENTS
+
+---
+
+## Objective
+Executive posture reporting, cluster analysis, signed compliance audit, and SARIF v2.1.0 export.
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Inspect run records and reporting parameters before generating release artifacts:
+1. **Active Run Records:** Ensure target run folder contains `findings.json` or `findings.md`.
+2. **SARIF v2.1.0 Schema:** Validate output structure against official OASIS SARIF standard.
+3. **Multi-Analysis Category:** Tag static findings under category `torusguard/static` to prevent CI collision.
+4. **Secret Masking:** Ensure zero unredacted authorization tokens or API keys appear in report.
+5. **Role Boundary:** Enforce reviewer agent sign-off before archiving run results.
+
+---
+
+## When to Use /torusguard report
+
+| Trigger Scenario | Recommended Action |
+| :--- | :--- |
+| Concluding a security review cycle or audit milestone | Run `/torusguard report` |
+| Exporting SARIF v2.1.0 logs for GitHub Code Scanning | Run `/torusguard report` |
+| Sharing executive posture summaries with stakeholders | Run `/torusguard report` |
+| Applying code modifications | Run `/torusguard apply` |
+| Re-checking modified files | Run `/torusguard recheck` |
+
+---
+
+## Execution Steps
+
+1. **Aggregate Lifecycle Data:** Load all finding cards, verification traces, and recheck logs.
+2. **Export OASIS SARIF v2.1.0:**
+   ```bash
+   python .torusguard/scripts/sarif_exporter.py --run <run_dir> --output <run_dir>/results.sarif
+   ```
+3. **Compile Executive Markdown Report:** Generate `report.md` with executive summary, posture score, and metrics.
+4. **Sign Off Run Manifest:** Update `.torusguard/runs/<run_id>/manifest.json` with final status counts.
+5. **Archive Results:** Confirm artifacts (`report.md`, `results.sarif`, `summary.md`) are saved on disk.
+
+---
+
+## Failure Recovery
+
+- **SARIF Schema Error:** Re-run `sarif_exporter.py` with schema validation flag to locate invalid properties.
+- **Empty Findings List:** Emit valid clean report indicating zero security vulnerabilities detected.
+- **Missing Run Folder:** Point script to latest valid timestamped run in `.torusguard/runs/`.
+- **Halt Trigger:** Abort if unredacted private secrets are detected in output text.
+
+---
+
+## Hallucination Guard
+
+- ❌ Never invent vulnerability counts not backed by actual findings in the run ledger.
+- ❌ Never generate invalid SARIF JSON with missing physical location URIs.
+- ✅ Always export standard-compliant SARIF v2.1.0 with AST line fingerprints.
+
+---
+
+## Output Card Format
+
+```markdown
+### 📊 TorusGuard Security Posture Report
+- **Run ID:** `run-YYYYMMDD-HHMMSS`
+- **Total Findings:** [Count] ([Fixed] Fixed, [Open] Open)
+- **Security Posture Score:** [Score]/100
+- **SARIF v2.1.0 Export:** `.torusguard/runs/<run_id>/results.sarif`
+- **Executive Report:** `.torusguard/runs/<run_id>/report.md`
+- **Status:** COMPLETE — report published
+```
+
+---
+
+## Next Steps
+
+1. Upload `results.sarif` to GitHub Code Scanning via `.github/workflows/`.
+2. Share `report.md` with engineering stakeholders and project maintainers.

package/.torusguard/workflows/status.md

@@ -0,0 +1,95 @@
+---
+description: Read-only diagnostic overview of workspace security posture, active configuration, rules catalog, and run history.
+tools: Read, Grep, Glob, Bash
+version: 0.9.2
+agent: reviewer
+lifecycle-phase: System / Diagnostics
+required-skills:
+  - torusguard-status
+scripts-binding:
+  - .torusguard/scripts/run_manager.py
+---
+
+# /torusguard status — Workspace Security Posture & Diagnostic Overview
+
+$ARGUMENTS
+
+---
+
+## Objective
+Read-only diagnostic overview of workspace security posture, active configuration, and run history.
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Inspect workspace state and configuration records prior to status display:
+1. **Config State (`.torusguard/config/torusguard.json`):** Confirm workspace initialization and read detected stack.
+2. **Active Rules Directory (`.torusguard/rules/active/`):** Count active rule files.
+3. **Run Folder Ledger (`.torusguard/runs/`):** Check run history and locate latest `manifest.json`.
+4. **Scope Record (`.torusguard/config/scope.json`):** Check whether runtime authorization TTL is active or expired.
+5. **Read-Only Invariant:** Ensure command performs zero file modifications or disk mutations.
+
+---
+
+## When to Use /torusguard status
+
+| Trigger Scenario | Recommended Action |
+| :--- | :--- |
+| Checking workspace configuration and active security posture | Run `/torusguard status` |
+| Reviewing recent audit runs and finding counts | Run `/torusguard status` |
+| Checking active legal scope authorization TTL | Run `/torusguard status` |
+| Initializing workspace for the first time | Run `/torusguard init` |
+| Executing full security scan | Run `/torusguard audit` |
+
+---
+
+## Execution Steps
+
+1. **Read Configuration:** Load `.torusguard/config/torusguard.json`; extract stack, version, and enabled rule count.
+2. **Enumerate Active Rules:** Count rule files physically present in `.torusguard/rules/active/`.
+3. **Inspect Run History:**
+   ```bash
+   python .torusguard/scripts/run_manager.py list
+   ```
+4. **Evaluate Scope Expiry:** Parse `.torusguard/config/scope.json`; report if TTL is valid or expired.
+5. **Print Status Overview:** Render complete workspace diagnostic overview card.
+
+---
+
+## Failure Recovery
+
+- **Uninitialized Workspace:** If config is missing, prompt user to execute `/torusguard init`.
+- **Zero Runs Found:** Display clean status card noting no historical audit runs exist yet.
+- **Corrupt Config File:** Report parsing error and recommend re-running `/torusguard init`.
+- **Halt Trigger:** Abort command if read access to `.torusguard/` is denied.
+
+---
+
+## Hallucination Guard
+
+- ❌ Never display fabricated finding counts not substantiated by run manifests.
+- ❌ Never execute modifying shell commands or edit source code during status inspection.
+- ✅ Always report factual file counts from `.torusguard/rules/active/` and `.torusguard/runs/`.
+
+---
+
+## Output Card Format
+
+```markdown
+### 🛡️ TorusGuard Workspace Status
+- **Version:** v0.9.2
+- **Framework Detected:** [Stack or None]
+- **Active Rules:** [Count] rules active in `.torusguard/rules/active/`
+- **Total Runs:** [Count] historical runs recorded
+- **Latest Run:** `run-YYYYMMDD-HHMMSS` ([Findings Count] findings)
+- **Scope Status:** [Authorized (TTL Active) / Expired / Unconfigured]
+- **Health Posture:** [GOOD / ACTION NEEDED]
+```
+
+---
+
+## Next Steps
+
+1. Run `/torusguard audit` to scan codebase for security vulnerabilities.
+2. Run `/torusguard authorize` to configure or refresh live target scope.

package/.torusguard/workflows/verify.md

@@ -0,0 +1,95 @@
+---
+description: Evidence sufficiency verification, live disk line match audit, and finding score refinement.
+tools: Read, Grep, Glob, Bash, Write
+version: 0.9.2
+agent: validator
+lifecycle-phase: Phase 3a (Evidence Verification)
+required-skills:
+  - torusguard-verify
+scripts-binding:
+  - .torusguard/scripts/finding_scorer.py
+---
+
+# /torusguard verify — Evidence Verification & Score Refinement
+
+$ARGUMENTS
+
+---
+
+## Objective
+Evidence sufficiency verification, live disk line match audit, and finding score refinement.
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Inspect finding records and evidence integrity before verification:
+1. **Latest Run Records (`.torusguard/runs/`):** Locate most recent audit run directory.
+2. **Finding Files:** Confirm `findings.md` or `findings.json` exists in the target run folder.
+3. **Live File Drift:** Assert cited source files have not been edited or relocated on disk.
+4. **Scoring Model Calibration:** Ensure `finding_scorer.py` evaluates all 5 rubric dimensions.
+5. **Role Boundary:** Enforce validator role; do not apply code modifications during verification.
+
+---
+
+## When to Use /torusguard verify
+
+| Trigger Scenario | Recommended Action |
+| :--- | :--- |
+| Auditing whether static findings are valid code flaws | Run `/torusguard verify` |
+| Upgrading Medium confidence finding to Confirmed | Run `/torusguard verify` |
+| No audit run executed yet | Run `/torusguard audit` first |
+| Running live network requests against endpoints | Run `/torusguard web-validate` |
+| Generating patch after verification | Run `/torusguard harden` |
+
+---
+
+## Execution Steps
+
+1. **Locate Target Findings:** Load active findings from latest run directory.
+2. **Live Disk Line Match:** Read current code at cited line ranges; verify AST snippet matches.
+3. **Audit Evidence Sufficiency:** Assess whether taint path is unbroken and caller context is exposed.
+4. **Refine Confidence Scores:**
+   ```bash
+   python .torusguard/scripts/finding_scorer.py --run <run_dir> --verify
+   ```
+5. **Classify Status:** Assign verified state (`Confirmed`, `Plausible`, or `False Positive / Disputed`).
+6. **Emit Verification Ledger:** Write `verified-evidence.md` into the active run folder.
+
+---
+
+## Failure Recovery
+
+- **Missing Run Folder:** Run `/torusguard audit` first to produce a valid run baseline.
+- **Line Drift Detected:** Flag line mismatch; scan nearby lines (±25) for relocated AST sink.
+- **Malformed Finding JSON:** Repair JSON structure using finding schema before scoring.
+- **Halt Trigger:** Abort if cited files are completely deleted from disk.
+
+---
+
+## Hallucination Guard
+
+- ❌ Never confirm a finding if the cited sink has already been sanitized by middleware.
+- ❌ Never bump confidence score without documenting unbroken taint source-to-sink flow.
+- ✅ Always anchor line matches to live disk reads using `view_file`.
+
+---
+
+## Output Card Format
+
+```markdown
+### 🧪 TorusGuard Evidence Verification
+- **Run ID:** `run-YYYYMMDD-HHMMSS-audit`
+- **Findings Evaluated:** [Count] findings
+- **Confirmed Real:** [Count] verified flaws
+- **Downgraded / False Positives:** [Count] filtered out
+- **Refined Mean Score:** [Score]/100
+- **Ledger:** `.torusguard/runs/<run_id>/verified-evidence.md`
+```
+
+---
+
+## Next Steps
+
+1. Run `/torusguard web-validate` if live endpoint probing is required.
+2. Run `/torusguard harden` to build surgical patch bundles for verified flaws.

package/.torusguard/workflows/web-validate.md

@@ -0,0 +1,95 @@
+---
+description: Authorized HTTP probing, token redaction, transparent audit header injection, and replay trace capture.
+tools: Read, Grep, Glob, Bash, Write
+version: 0.9.2
+agent: validator
+lifecycle-phase: Phase 3b (Runtime Web Validation)
+required-skills:
+  - torusguard-web-validate
+scripts-binding:
+  - .torusguard/scripts/safety_gate.py
+---
+
+# /torusguard web-validate — Bounded HTTP Probing & Session Capture
+
+$ARGUMENTS
+
+---
+
+## Objective
+Authorized HTTP probing, token redaction, transparent audit header injection, and replay capture.
+
+---
+
+## Mandatory Pre-Flight Context Inspection
+
+Inspect authorization parameters and safety limits before sending HTTP requests:
+1. **Active Scope (`.torusguard/config/scope.json`):** Assert target host and path are authorized with valid TTL.
+2. **Safety Gate Classification:** Test proposed endpoint against `.torusguard/scripts/safety_gate.py`.
+3. **Sensitive Route Guard:** Ensure destructive endpoints (`DELETE`, account drops) are never called automatically.
+4. **Token Redaction Pipeline:** Ensure bearer tokens and session cookies are masked (`Bearer [REDACTED]`).
+5. **Request Budget:** Enforce maximum cap of 50 requests per validation session.
+
+---
+
+## When to Use /torusguard web-validate
+
+| Trigger Scenario | Recommended Action |
+| :--- | :--- |
+| Testing live route accessibility and security headers | Run `/torusguard web-validate` |
+| Verifying cookie security flags (`HttpOnly`, `Secure`, `SameSite`) | Run `/torusguard web-validate` |
+| Checking CORS headers and authentication barriers | Run `/torusguard web-validate` |
+| Pure static source code analysis | Run `/torusguard audit` |
+| Confirming exploitable attack vectors | Run `/torusguard exploit-check` |
+
+---
+
+## Execution Steps
+
+1. **Verify Legal Scope:** Check target URL against `.torusguard/config/scope.json`.
+2. **Invoke Safety Gate:**
+   ```bash
+   python .torusguard/scripts/safety_gate.py check --url <target_url> --method GET
+   ```
+3. **Dispatch Non-Destructive Probe:** Send bounded HTTP request with audit header `X-TorusGuard-AuthID`.
+4. **Redact Sensitive Headers:** Sanitize auth tokens and credentials in request and response objects.
+5. **Write Replay Artifacts:**
+   Record sanitized trace in `.torusguard/runs/<run_id>/requests.json` and emit `web-validation.md`.
+
+---
+
+## Failure Recovery
+
+- **Target Offline:** Verify local dev server is active and accessible on designated host port.
+- **Safety Gate Rejection (Manual Only):** Halt probe immediately; report endpoint requires human manual test.
+- **Rate Limit / 429:** Back off exponentially (1s, 2s, 4s); stop session if 429 persists.
+- **Halt Trigger:** Abort if target domain deviates from authorized allowlist in `scope.json`.
+
+---
+
+## Hallucination Guard
+
+- ❌ Never dispatch HTTP requests outside domains explicitly listed in `.torusguard/config/scope.json`.
+- ❌ Never write raw Authorization headers or plaintext secrets to disk.
+- ✅ Always include transparent audit headers (`X-TorusGuard-AuthID`).
+
+---
+
+## Output Card Format
+
+```markdown
+### 🌐 TorusGuard Web Validation
+- **Target Host:** [Host URL]
+- **Endpoints Probed:** [Count] routes tested
+- **Security Headers:** [CSP / HSTS / CORS status]
+- **Cookie Security:** [HttpOnly / Secure / SameSite status]
+- **Replay Trace:** `.torusguard/runs/<run_id>/replay.json`
+- **Status:** COMPLETED — non-destructive probe finished
+```
+
+---
+
+## Next Steps
+
+1. Run `/torusguard exploit-check` to confirm if reachable flaws constitute verified exploits.
+2. Run `/torusguard harden` to build surgical remediation diffs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jenish Lad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.