secure-code-agent 0.2.0__tar.gz → 0.4.0__tar.gz

{secure_code_agent-0.2.0 → secure_code_agent-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.2.0
+Version: 0.4.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -21,15 +21,27 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Provides-Extra: required-scanners
+Requires-Dist: bandit==1.9.4; extra == "required-scanners"
+Requires-Dist: pip-audit==2.10.1; extra == "required-scanners"
+Requires-Dist: njsscan==1.0.0; extra == "required-scanners"
+Provides-Extra: python-scanners
+Requires-Dist: secure-code-agent[required-scanners]; extra == "python-scanners"
+Requires-Dist: semgrep<2,>=1.172; extra == "python-scanners"
+Requires-Dist: checkov<4,>=3.3; extra == "python-scanners"
 Provides-Extra: dev
+Requires-Dist: secure-code-agent[required-scanners]; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: ruff==0.16.2; extra == "dev"
 Dynamic: license-file
 
 # secure-code-agent
@@ -38,7 +50,7 @@ Dynamic: license-file
 > Anchored to NIST SSDF · OWASP ASVS · OWASP Top 10 · MITRE CWE Top 25 · OpenSSF Scorecard · SARIF 2.1.0.
 
 ```bash
-pip install secure-code-agent
+pip install 'secure-code-agent[required-scanners]'
 
 secure-code-agent --fail-on-gate \
     --output secure-code-report.md \
@@ -115,18 +127,21 @@ Hand the prompt to Claude Code, Codex, Cursor, Copilot, or any agent. The agent
 
 ## Standards anchored, not invented
 
-Every finding maps to five public standards. Operators see *which standard is failing*, not just *which scanner shouted*.
+Known rules map to fields from five public standards. Unmapped and scanner-control
+findings retain null standards fields rather than receiving invented mappings.
 
 | Source                                       | What we use it for                                       |
 |----------------------------------------------|----------------------------------------------------------|
 | [NIST SSDF SP 800-218](https://csrc.nist.gov/pubs/sp/800/218/final) | Process practice id (e.g. `PW.5.1`) |
 | [OWASP Top 10 (2021)](https://owasp.org/Top10/2021/) | Risk bucket (e.g. `A03:2021-Injection`) |
 | [OWASP ASVS 5.0](https://github.com/OWASP/ASVS) | Verification requirement (e.g. `V5.3`) |
-| [MITRE CWE Top 25 (2025)](https://cwe.mitre.org/top25/) | Canonical weakness id — the dedupe key |
+| [MITRE CWE Top 25 (2025)](https://cwe.mitre.org/top25/) | Canonical weakness id used in stable fingerprints |
 | [OpenSSF Scorecard](https://openssf.org/projects/scorecard/) | Repo + supply-chain hygiene |
 | [SARIF 2.1.0](https://www.oasis-open.org/standard/sarif-v2-1-0/) | Output format (and external scanner ingest) |
 
-When Semgrep, CodeQL, and Bandit fire on the same SQL-injection sink with three different rule ids, they all map to `CWE-89` and the scorer counts **one** underlying weakness. Not three.
+When scanners map a finding to `CWE-89`, the canonical CWE participates in its
+stable fingerprint and baseline identity. Cross-scanner findings are not yet
+collapsed before scoring; reports preserve the original scanner evidence.
 
 ## Architecture (orchestrator, not engine)
 
@@ -159,7 +174,9 @@ When Semgrep, CodeQL, and Bandit fire on the same SQL-injection sink with three
         ├── Hadolint          (Dockerfile lint)
         ├── OSV-Scanner       (multi-ecosystem SCA via osv.dev)
         ├── OpenSSF Scorecard (repo hygiene + supply chain)
-        ├── eslint-plugin-security  (JS/TS SAST)                     [v0.3]
+        ├── njsscan           (JS/TS SAST, offline, no Node needed)
+        ├── RuboCop           (Ruby security cops, --only Security)
+        ├── gosec             (Go SAST — opt-in; needs the Go toolchain)
         ├── CodeQL SARIF      (ingest GitHub-hosted analysis)
         └── Built-in regex rules (high-confidence, low-FP)
 ```
@@ -203,7 +220,67 @@ Scoring math + worked examples in [`docs/scoring.md`](docs/scoring.md).
 
 Any tripped gate is a nonzero exit. Compose freely.
 
-## Suppressions you can't game
+`require_scanners` is a coverage gate, not a vulnerability gate. A required
+scanner must resolve and complete successfully. Missing executables, timeouts,
+invalid output, unsupported inputs, or excluding the scanner with CLI filters
+fail coverage. Optional scanner failures produce `PARTIAL` coverage without
+turning a clean finding set into a false comprehensive result. Markdown and
+JSON reports record each scanner's outcome, resolved command, and version.
+When `require_scanners` is present it must name at least one scanner; an empty
+list is rejected instead of silently removing the structural coverage gate.
+
+External scanners are not bundled, and the agent never installs one for you —
+a gate that fetches and runs binaries to satisfy its own coverage requirement
+is the supply-chain risk it is supposed to catch. Resolution order is an
+explicit `scanners.<name>.command`, the active `PATH`, then `python -m <module>`
+for supported Python scanners. Relative executable paths resolve from the scan
+target and are executed with `shell=False`.
+
+`secure-code-agent --preflight` reports which enabled scanners resolve on this
+host, with versions and the install command for anything missing, and exits
+nonzero when a required scanner is unavailable — so a missing toolchain costs a
+second instead of a full audit. Bandit and pip-audit install as
+`secure-code-agent[required-scanners]`; Semgrep and Checkov add
+`[python-scanners]`. The remaining scanners are standalone binaries that cannot
+come from PyPI: install them with your package manager, or run their pinned
+upstream CI action and feed us the SARIF, which counts as coverage:
+
+```bash
+secure-code-agent --fail-on-gate --sarif-import trivy.sarif
+```
+
+An import satisfies `require_scanners` for the tool that produced it. An
+unreadable, malformed, or run-less import fails the gate rather than ingesting
+nothing quietly, an import reporting its own `executionSuccessful: false` is
+recorded as failed, and when a scanner reports both locally and by import the
+worse outcome wins. See [`docs/scanners.md`](docs/scanners.md) for the full
+install matrix.
+
+```json
+{
+  "scanners": {
+    "bandit": {
+      "enabled": true,
+      "command": [".audit-tools/bin/python", "-m", "bandit"]
+    },
+    "pip_audit": {
+      "enabled": true,
+      "command": [".audit-tools/bin/python", "-m", "pip_audit"],
+      "mode": "project",
+      "inputs": ["engine/pyproject.toml"]
+    }
+  }
+}
+```
+
+The tool never downloads a scanner during an audit. Install and pin scanner
+versions in the audit environment or CI image.
+
+This repository's own CI audits `requirements-audit.txt`, which pins the
+minimum supported runtime dependency version. Project mode remains available
+for repositories whose `pyproject.toml` is their authoritative audit input.
+
+## Time-bounded suppressions
 
 `.scignore.yaml` — every suppression requires a `reason` AND an `expires` date (max 365 days). Past-expiry suppressions become CRITICAL findings on their own. You can't ship `reason: "we'll fix it later"` forever.
 
@@ -213,6 +290,10 @@ Any tripped gate is a nonzero exit. Compose freely.
   reason:  "Slated for rewrite Q3 2026 — gated by initiative INV-44."
   expires: "2026-09-30"
 
+  fingerprint: 0aaa689f8a967d8c   # optional: pin to ONE finding (16 hex, from the report)
+
+  line: 18                          # optional: with fingerprint, pins the exact location
+
 - rule_id: "B101"
   paths:   ["tests/"]
   reason:  "assert statements are legitimate in test code."
@@ -228,15 +309,19 @@ Wildcard rule (`rule_id: "*"`) requires a `file` or `paths` scope — you cannot
 - Findings present in baseline → **acknowledged**; don't trip `fail_on_new`.
 - Findings missing from baseline → **new**; trip the gate.
 
-Bumping a CRITICAL or HIGH finding into the baseline requires `--bump-baseline --i-acknowledge-risk`. The bump records the operator's git `user.email` per fingerprint so PR review can see who acknowledged what.
+`--bump-baseline` rewrites the baseline from the current findings. The file is
+plain JSON and must be reviewed like any other security-policy change. This
+release does not implement an interactive acknowledgment. Baseline entries
+record the best-effort local Git email, while repository review policy remains
+the approval boundary.
 
 This lets legacy repos adopt the gate without a 200-finding day-one cleanup.
 
 ## Quickstart
 
 ```bash
-# Install
-pip install secure-code-agent
+# Install the orchestrator with its pinned default Bandit + pip-audit toolchain
+pip install 'secure-code-agent[required-scanners]'
 
 # Initialize agent standards files for your AI coding tools
 secure-code-agent --init-agent-standards \
@@ -251,14 +336,18 @@ secure-code-agent --config secure-code-agent.json \
     --comment-output secure-code-pr-comment.md \
     --prompt-output secure-code-remediation-prompt.md
 
-# Audit only changed files since main
-secure-code-agent --changed-only main...HEAD --fail-on-new
-
 # Ingest external scanner SARIF (CodeQL, Snyk, Trivy, etc.)
 secure-code-agent --sarif-import codeql-results.sarif \
                    --sarif-import snyk-results.sarif
 ```
 
+`--changed-only` is reserved but not yet safely implemented. Passing it fails
+with exit code 2 so a caller cannot accidentally treat an unscoped audit as a
+changed-file audit.
+
+The current orchestrator accepts one repository root per invocation. Multiple
+positional roots fail with exit code 2 instead of silently ignoring coverage.
+
 ## Invokable skill / slash command
 
 For agents that support invokable skills, this repo ships a portable skill under [`skills/secure-code-agent/`](skills/secure-code-agent/). The `SKILL.md` body is the source of truth; per-host adapters live under `agents/` and `copilot/`.
@@ -272,14 +361,19 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.1.0
+- uses: marshallguillory86/secure-code-agent@v0.3.0
   with:
     config: secure-code-agent.json
-    changed-only: main...HEAD
     fail-on-gate: true
 ```
 
-The action uploads SARIF to GitHub Code Scanning by default. See [`action.yml`](action.yml) and [`examples/github-actions/`](examples/github-actions/) for full workflows.
+The action installs the exact source bundled with the referenced action plus
+the pinned `required-scanners` extra (Bandit and pip-audit),
+emits Markdown, JSON, SARIF, PR-comment, and remediation artifacts, and uploads
+SARIF by default. The calling workflow must grant `security-events: write` for
+SARIF upload. Pin production usage to a full commit SHA; the version tag above
+is shown for readability. See [`action.yml`](action.yml) and
+[`examples/github-actions/`](examples/github-actions/) for full workflows.
 
 ## What this is NOT
 
@@ -294,7 +388,7 @@ The action uploads SARIF to GitHub Code Scanning by default. See [`action.yml`](
 1. **Deterministic first, AI optional.** The audit never calls an LLM by default. The remediation prompt is a generated artifact you choose to hand to an agent.
 2. **Bounded scope.** The remediation prompt explicitly forbids touching crypto, auth, validation, logging, and tests.
 3. **Standards-anchored.** Five public standards (NIST / OWASP-x3 / CWE) — no invented taxonomy.
-4. **CWE-deduped scoring.** One underlying weakness = one finding, regardless of how many scanners found it.
+4. **Stable finding identity.** CWE, normalized path, and normalized evidence form the baseline fingerprint. Cross-scanner score deduplication remains future work.
 5. **No vendor lock-in.** Markdown, JSON, SARIF, plain files. Pipe anywhere.
 6. **CI-first, local-first.** Same binary in pre-commit, local CI, GitHub Actions, GitLab, Buildkite.
 
@@ -302,7 +396,11 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 
 ## Documentation
 
+- [`docs/product-intent.md`](docs/product-intent.md) — Why this exists, who it serves, what it refuses to become
+- [`docs/decisions.md`](docs/decisions.md)        — Decision register: rulings the code alone cannot answer
 - [`docs/design.md`](docs/design.md)              — Architecture + non-goals + scanner protocol
+- [`docs/architecture.md`](docs/architecture.md)  — Audit of the system as built + remediation sequence
+- [`docs/release-blockers.md`](docs/release-blockers.md) — Open v0.3.0 release blockers (do not tag until closed)
 - [`docs/standards.md`](docs/standards.md)        — NIST SSDF / OWASP / CWE / Scorecard / SARIF citations
 - [`docs/scoring.md`](docs/scoring.md)            — Weighting model + worked examples
 - [`docs/scanners.md`](docs/scanners.md)          — Per-scanner integrations + caveats
@@ -312,7 +410,8 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 ## Versioning
 
 - **Semver.** v0.x is pre-1.0 — the config schema may evolve. v1.0 locks it.
-- **SARIF 2.1.0** output is pinned and validated against the OASIS schema in CI.
+- **SARIF 2.1.0-shaped** output is structurally unit-tested and round-tripped;
+  full OASIS schema validation is not yet part of CI.
 
 ## Get in touch
 

secure_code_agent-0.2.0/src/secure_code_agent.egg-info/PKG-INFO → secure_code_agent-0.4.0/README.md

@@ -1,44 +1,10 @@
-Metadata-Version: 2.4
-Name: secure-code-agent
-Version: 0.2.0
-Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
-Author: Marshall Guillory
-License: MIT
-Project-URL: Homepage, https://github.com/marshallguillory86/secure-code-agent
-Project-URL: Repository, https://github.com/marshallguillory86/secure-code-agent
-Project-URL: Documentation, https://github.com/marshallguillory86/secure-code-agent/tree/main/docs
-Project-URL: Issues, https://github.com/marshallguillory86/secure-code-agent/issues
-Project-URL: Changelog, https://github.com/marshallguillory86/secure-code-agent/blob/main/CHANGELOG.md
-Keywords: security,appsec,sast,sca,secret-scanning,owasp,asvs,cwe,nist-ssdf,sarif,ai-code-review,ai-guardrail,remediation-prompt,ci,audit
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
-Dynamic: license-file
-
 # secure-code-agent
 
 > **Deterministic security gate + bounded AI remediation prompts for repos with AI coding agents in the loop.**
 > Anchored to NIST SSDF · OWASP ASVS · OWASP Top 10 · MITRE CWE Top 25 · OpenSSF Scorecard · SARIF 2.1.0.
 
 ```bash
-pip install secure-code-agent
+pip install 'secure-code-agent[required-scanners]'
 
 secure-code-agent --fail-on-gate \
     --output secure-code-report.md \
@@ -115,18 +81,21 @@ Hand the prompt to Claude Code, Codex, Cursor, Copilot, or any agent. The agent
 
 ## Standards anchored, not invented
 
-Every finding maps to five public standards. Operators see *which standard is failing*, not just *which scanner shouted*.
+Known rules map to fields from five public standards. Unmapped and scanner-control
+findings retain null standards fields rather than receiving invented mappings.
 
 | Source                                       | What we use it for                                       |
 |----------------------------------------------|----------------------------------------------------------|
 | [NIST SSDF SP 800-218](https://csrc.nist.gov/pubs/sp/800/218/final) | Process practice id (e.g. `PW.5.1`) |
 | [OWASP Top 10 (2021)](https://owasp.org/Top10/2021/) | Risk bucket (e.g. `A03:2021-Injection`) |
 | [OWASP ASVS 5.0](https://github.com/OWASP/ASVS) | Verification requirement (e.g. `V5.3`) |
-| [MITRE CWE Top 25 (2025)](https://cwe.mitre.org/top25/) | Canonical weakness id — the dedupe key |
+| [MITRE CWE Top 25 (2025)](https://cwe.mitre.org/top25/) | Canonical weakness id used in stable fingerprints |
 | [OpenSSF Scorecard](https://openssf.org/projects/scorecard/) | Repo + supply-chain hygiene |
 | [SARIF 2.1.0](https://www.oasis-open.org/standard/sarif-v2-1-0/) | Output format (and external scanner ingest) |
 
-When Semgrep, CodeQL, and Bandit fire on the same SQL-injection sink with three different rule ids, they all map to `CWE-89` and the scorer counts **one** underlying weakness. Not three.
+When scanners map a finding to `CWE-89`, the canonical CWE participates in its
+stable fingerprint and baseline identity. Cross-scanner findings are not yet
+collapsed before scoring; reports preserve the original scanner evidence.
 
 ## Architecture (orchestrator, not engine)
 
@@ -159,7 +128,9 @@ When Semgrep, CodeQL, and Bandit fire on the same SQL-injection sink with three
         ├── Hadolint          (Dockerfile lint)
         ├── OSV-Scanner       (multi-ecosystem SCA via osv.dev)
         ├── OpenSSF Scorecard (repo hygiene + supply chain)
-        ├── eslint-plugin-security  (JS/TS SAST)                     [v0.3]
+        ├── njsscan           (JS/TS SAST, offline, no Node needed)
+        ├── RuboCop           (Ruby security cops, --only Security)
+        ├── gosec             (Go SAST — opt-in; needs the Go toolchain)
         ├── CodeQL SARIF      (ingest GitHub-hosted analysis)
         └── Built-in regex rules (high-confidence, low-FP)
 ```
@@ -203,7 +174,67 @@ Scoring math + worked examples in [`docs/scoring.md`](docs/scoring.md).
 
 Any tripped gate is a nonzero exit. Compose freely.
 
-## Suppressions you can't game
+`require_scanners` is a coverage gate, not a vulnerability gate. A required
+scanner must resolve and complete successfully. Missing executables, timeouts,
+invalid output, unsupported inputs, or excluding the scanner with CLI filters
+fail coverage. Optional scanner failures produce `PARTIAL` coverage without
+turning a clean finding set into a false comprehensive result. Markdown and
+JSON reports record each scanner's outcome, resolved command, and version.
+When `require_scanners` is present it must name at least one scanner; an empty
+list is rejected instead of silently removing the structural coverage gate.
+
+External scanners are not bundled, and the agent never installs one for you —
+a gate that fetches and runs binaries to satisfy its own coverage requirement
+is the supply-chain risk it is supposed to catch. Resolution order is an
+explicit `scanners.<name>.command`, the active `PATH`, then `python -m <module>`
+for supported Python scanners. Relative executable paths resolve from the scan
+target and are executed with `shell=False`.
+
+`secure-code-agent --preflight` reports which enabled scanners resolve on this
+host, with versions and the install command for anything missing, and exits
+nonzero when a required scanner is unavailable — so a missing toolchain costs a
+second instead of a full audit. Bandit and pip-audit install as
+`secure-code-agent[required-scanners]`; Semgrep and Checkov add
+`[python-scanners]`. The remaining scanners are standalone binaries that cannot
+come from PyPI: install them with your package manager, or run their pinned
+upstream CI action and feed us the SARIF, which counts as coverage:
+
+```bash
+secure-code-agent --fail-on-gate --sarif-import trivy.sarif
+```
+
+An import satisfies `require_scanners` for the tool that produced it. An
+unreadable, malformed, or run-less import fails the gate rather than ingesting
+nothing quietly, an import reporting its own `executionSuccessful: false` is
+recorded as failed, and when a scanner reports both locally and by import the
+worse outcome wins. See [`docs/scanners.md`](docs/scanners.md) for the full
+install matrix.
+
+```json
+{
+  "scanners": {
+    "bandit": {
+      "enabled": true,
+      "command": [".audit-tools/bin/python", "-m", "bandit"]
+    },
+    "pip_audit": {
+      "enabled": true,
+      "command": [".audit-tools/bin/python", "-m", "pip_audit"],
+      "mode": "project",
+      "inputs": ["engine/pyproject.toml"]
+    }
+  }
+}
+```
+
+The tool never downloads a scanner during an audit. Install and pin scanner
+versions in the audit environment or CI image.
+
+This repository's own CI audits `requirements-audit.txt`, which pins the
+minimum supported runtime dependency version. Project mode remains available
+for repositories whose `pyproject.toml` is their authoritative audit input.
+
+## Time-bounded suppressions
 
 `.scignore.yaml` — every suppression requires a `reason` AND an `expires` date (max 365 days). Past-expiry suppressions become CRITICAL findings on their own. You can't ship `reason: "we'll fix it later"` forever.
 
@@ -213,6 +244,10 @@ Any tripped gate is a nonzero exit. Compose freely.
   reason:  "Slated for rewrite Q3 2026 — gated by initiative INV-44."
   expires: "2026-09-30"
 
+  fingerprint: 0aaa689f8a967d8c   # optional: pin to ONE finding (16 hex, from the report)
+
+  line: 18                          # optional: with fingerprint, pins the exact location
+
 - rule_id: "B101"
   paths:   ["tests/"]
   reason:  "assert statements are legitimate in test code."
@@ -228,15 +263,19 @@ Wildcard rule (`rule_id: "*"`) requires a `file` or `paths` scope — you cannot
 - Findings present in baseline → **acknowledged**; don't trip `fail_on_new`.
 - Findings missing from baseline → **new**; trip the gate.
 
-Bumping a CRITICAL or HIGH finding into the baseline requires `--bump-baseline --i-acknowledge-risk`. The bump records the operator's git `user.email` per fingerprint so PR review can see who acknowledged what.
+`--bump-baseline` rewrites the baseline from the current findings. The file is
+plain JSON and must be reviewed like any other security-policy change. This
+release does not implement an interactive acknowledgment. Baseline entries
+record the best-effort local Git email, while repository review policy remains
+the approval boundary.
 
 This lets legacy repos adopt the gate without a 200-finding day-one cleanup.
 
 ## Quickstart
 
 ```bash
-# Install
-pip install secure-code-agent
+# Install the orchestrator with its pinned default Bandit + pip-audit toolchain
+pip install 'secure-code-agent[required-scanners]'
 
 # Initialize agent standards files for your AI coding tools
 secure-code-agent --init-agent-standards \
@@ -251,14 +290,18 @@ secure-code-agent --config secure-code-agent.json \
     --comment-output secure-code-pr-comment.md \
     --prompt-output secure-code-remediation-prompt.md
 
-# Audit only changed files since main
-secure-code-agent --changed-only main...HEAD --fail-on-new
-
 # Ingest external scanner SARIF (CodeQL, Snyk, Trivy, etc.)
 secure-code-agent --sarif-import codeql-results.sarif \
                    --sarif-import snyk-results.sarif
 ```
 
+`--changed-only` is reserved but not yet safely implemented. Passing it fails
+with exit code 2 so a caller cannot accidentally treat an unscoped audit as a
+changed-file audit.
+
+The current orchestrator accepts one repository root per invocation. Multiple
+positional roots fail with exit code 2 instead of silently ignoring coverage.
+
 ## Invokable skill / slash command
 
 For agents that support invokable skills, this repo ships a portable skill under [`skills/secure-code-agent/`](skills/secure-code-agent/). The `SKILL.md` body is the source of truth; per-host adapters live under `agents/` and `copilot/`.
@@ -272,14 +315,19 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.1.0
+- uses: marshallguillory86/secure-code-agent@v0.3.0
   with:
     config: secure-code-agent.json
-    changed-only: main...HEAD
     fail-on-gate: true
 ```
 
-The action uploads SARIF to GitHub Code Scanning by default. See [`action.yml`](action.yml) and [`examples/github-actions/`](examples/github-actions/) for full workflows.
+The action installs the exact source bundled with the referenced action plus
+the pinned `required-scanners` extra (Bandit and pip-audit),
+emits Markdown, JSON, SARIF, PR-comment, and remediation artifacts, and uploads
+SARIF by default. The calling workflow must grant `security-events: write` for
+SARIF upload. Pin production usage to a full commit SHA; the version tag above
+is shown for readability. See [`action.yml`](action.yml) and
+[`examples/github-actions/`](examples/github-actions/) for full workflows.
 
 ## What this is NOT
 
@@ -294,7 +342,7 @@ The action uploads SARIF to GitHub Code Scanning by default. See [`action.yml`](
 1. **Deterministic first, AI optional.** The audit never calls an LLM by default. The remediation prompt is a generated artifact you choose to hand to an agent.
 2. **Bounded scope.** The remediation prompt explicitly forbids touching crypto, auth, validation, logging, and tests.
 3. **Standards-anchored.** Five public standards (NIST / OWASP-x3 / CWE) — no invented taxonomy.
-4. **CWE-deduped scoring.** One underlying weakness = one finding, regardless of how many scanners found it.
+4. **Stable finding identity.** CWE, normalized path, and normalized evidence form the baseline fingerprint. Cross-scanner score deduplication remains future work.
 5. **No vendor lock-in.** Markdown, JSON, SARIF, plain files. Pipe anywhere.
 6. **CI-first, local-first.** Same binary in pre-commit, local CI, GitHub Actions, GitLab, Buildkite.
 
@@ -302,7 +350,11 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 
 ## Documentation
 
+- [`docs/product-intent.md`](docs/product-intent.md) — Why this exists, who it serves, what it refuses to become
+- [`docs/decisions.md`](docs/decisions.md)        — Decision register: rulings the code alone cannot answer
 - [`docs/design.md`](docs/design.md)              — Architecture + non-goals + scanner protocol
+- [`docs/architecture.md`](docs/architecture.md)  — Audit of the system as built + remediation sequence
+- [`docs/release-blockers.md`](docs/release-blockers.md) — Open v0.3.0 release blockers (do not tag until closed)
 - [`docs/standards.md`](docs/standards.md)        — NIST SSDF / OWASP / CWE / Scorecard / SARIF citations
 - [`docs/scoring.md`](docs/scoring.md)            — Weighting model + worked examples
 - [`docs/scanners.md`](docs/scanners.md)          — Per-scanner integrations + caveats
@@ -312,7 +364,8 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 ## Versioning
 
 - **Semver.** v0.x is pre-1.0 — the config schema may evolve. v1.0 locks it.
-- **SARIF 2.1.0** output is pinned and validated against the OASIS schema in CI.
+- **SARIF 2.1.0-shaped** output is structurally unit-tested and round-tripped;
+  full OASIS schema validation is not yet part of CI.
 
 ## Get in touch
 

{secure_code_agent-0.2.0 → secure_code_agent-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "secure-code-agent"
-version = "0.2.0"
+version = "0.4.0"
 description = "Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,19 +30,49 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Security",
   "Topic :: Software Development :: Quality Assurance",
 ]
 dependencies = [
-  # Stdlib-only at runtime. Scanners are invoked as subprocesses so
-  # the tool has no hard dependency on their Python packages.
+  "PyYAML>=6.0.2,<7",
+  # Scanner packages remain external subprocess dependencies.
 ]
 
 [project.optional-dependencies]
+# Scanners the default configuration lists in gates.require_scanners. Pinned
+# exactly: a gate asserting "bandit completed" should mean a known Bandit
+# completed, not whatever Bandit resolved that day.
+required-scanners = [
+  "bandit==1.9.4",
+  "pip-audit==2.10.1",
+  # njsscan is in the floor (D12) and is a Python package carrying its own
+  # rules, so a JavaScript repository can be scanned on a host with no Node.
+  # Pinned for the same reason as the rest: the floor is a claim about what
+  # ran, and an unpinned ruleset makes that claim unreproducible.
+  "njsscan==1.0.0",
+]
+# The remaining Python-packaged scanners. Bounded rather than pinned because
+# they are optional; the coverage gate does not require them by default.
+# Scanners distributed as standalone binaries or through another language's
+# package manager (gitleaks, gosec, hadolint, npm, osv-scanner, rubocop,
+# scorecard, trivy, trufflehog) cannot be installed from PyPI — see
+# docs/scanners.md for their install commands and the SARIF-import route.
+python-scanners = [
+  "secure-code-agent[required-scanners]",
+  "semgrep>=1.172,<2",
+  "checkov>=3.3,<4",
+]
+# Includes required-scanners so a fresh checkout can run its own audit.
+# Ruff is pinned exactly: `ruff format --check` is a CI gate, and an
+# unpinned formatter turns every upstream release into a possible red build
+# with no change in this repository. Same reasoning as required-scanners.
 dev = [
+  "secure-code-agent[required-scanners]",
   "pytest>=8.0",
   "pytest-cov>=4.0",
-  "ruff>=0.5",
+  "ruff==0.16.2",
 ]
 
 [project.scripts]
@@ -65,6 +95,15 @@ secure_code_audit = ["data/*.json", "data/*.yaml"]
 [tool.ruff]
 line-length = 100
 target-version = "py310"
+# Ruff 0.16 formats Python blocks embedded in Markdown. Our docs use those
+# blocks illustratively — excerpted statements, aligned-comment schemas — and
+# reformatting them damages the documentation without improving any code.
+extend-exclude = [
+  "**/*.md",
+  # Scanner fixtures are deliberately vulnerable sample code. Linting them
+  # would demand we fix the very patterns the rules exist to detect.
+  "tests/fixtures/**",
+]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "SIM", "C4"]