secure-code-agent 0.11.0__tar.gz → 0.12.0__tar.gz

{secure_code_agent-0.11.0/src/secure_code_agent.egg-info → secure_code_agent-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.11.0
+Version: 0.12.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -29,6 +29,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML<7,>=6.0.2
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
 Provides-Extra: required-scanners
 Requires-Dist: bandit==1.9.4; extra == "required-scanners"
 Requires-Dist: pip-audit==2.10.1; extra == "required-scanners"
@@ -90,6 +92,43 @@ A pure-Python repository requires six of the ten floor scanners; the Ruby,
 JavaScript and container tools are *not applicable* rather than missing, so a
 single-language project is never permanently incomplete.
 
+## In your editor or an agent, not just a terminal
+
+```bash
+pip install 'secure-code-agent[mcp]'
+secure-code-agent-mcp
+```
+
+Exposes `audit_repository`, `preflight` and `agent_info`. It never audits
+unasked — `audit_repository` without `action="run"` returns the question — and
+it hands back the **work order first**, because the score is second class.
+
+## Auditing a pull request
+
+```bash
+secure-code-agent . --changed-only origin/main
+```
+
+The whole tree is still scanned; the *report* is scoped to what changed. **No
+grade is issued** for a scoped run, because a run that looks at less must not
+score better.
+
+## Proving the agent stayed inside the order
+
+```bash
+secure-code-agent . --verify-against before.json
+```
+
+Reports what was fixed, what is still open, what was **silenced rather than
+fixed** — and the blast radius: which changed files the work order never
+cited.
+
+```
+work order verification  ·  improved: 1 fixed
+  fixed      sca.python.subprocess.shell_true   bad.py:3
+  scope: EXCEEDED — 1 of 2 changed file(s) were never cited: src/other.py
+```
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -470,7 +509,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.11.0
+- uses: marshallguillory86/secure-code-agent@v0.12.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/README.md

@@ -44,6 +44,43 @@ A pure-Python repository requires six of the ten floor scanners; the Ruby,
 JavaScript and container tools are *not applicable* rather than missing, so a
 single-language project is never permanently incomplete.
 
+## In your editor or an agent, not just a terminal
+
+```bash
+pip install 'secure-code-agent[mcp]'
+secure-code-agent-mcp
+```
+
+Exposes `audit_repository`, `preflight` and `agent_info`. It never audits
+unasked — `audit_repository` without `action="run"` returns the question — and
+it hands back the **work order first**, because the score is second class.
+
+## Auditing a pull request
+
+```bash
+secure-code-agent . --changed-only origin/main
+```
+
+The whole tree is still scanned; the *report* is scoped to what changed. **No
+grade is issued** for a scoped run, because a run that looks at less must not
+score better.
+
+## Proving the agent stayed inside the order
+
+```bash
+secure-code-agent . --verify-against before.json
+```
+
+Reports what was fixed, what is still open, what was **silenced rather than
+fixed** — and the blast radius: which changed files the work order never
+cited.
+
+```
+work order verification  ·  improved: 1 fixed
+  fixed      sca.python.subprocess.shell_true   bad.py:3
+  scope: EXCEEDED — 1 of 2 changed file(s) were never cited: src/other.py
+```
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -424,7 +461,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.11.0
+- uses: marshallguillory86/secure-code-agent@v0.12.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/pyproject.toml

@@ -49,6 +49,13 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# The chat door. Optional because the CLI is the tested surface and the MCP
+# server drives it by subprocess rather than reimplementing it — so nobody
+# who only wants the gate pays for an MCP dependency.
+mcp = [
+  "mcp>=1.0,<2",
+]
+
 # 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.
@@ -86,6 +93,7 @@ dev = [
 [project.scripts]
 secure-code-agent = "secure_code_audit.cli:main"
 secure-code-audit = "secure_code_audit.cli:main"
+secure-code-agent-mcp = "secure_code_audit.mcp_server:main"
 
 [project.urls]
 Homepage      = "https://github.com/marshallguillory86/secure-code-agent"

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.11.0
+Version: 0.12.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -29,6 +29,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML<7,>=6.0.2
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
 Provides-Extra: required-scanners
 Requires-Dist: bandit==1.9.4; extra == "required-scanners"
 Requires-Dist: pip-audit==2.10.1; extra == "required-scanners"
@@ -90,6 +92,43 @@ A pure-Python repository requires six of the ten floor scanners; the Ruby,
 JavaScript and container tools are *not applicable* rather than missing, so a
 single-language project is never permanently incomplete.
 
+## In your editor or an agent, not just a terminal
+
+```bash
+pip install 'secure-code-agent[mcp]'
+secure-code-agent-mcp
+```
+
+Exposes `audit_repository`, `preflight` and `agent_info`. It never audits
+unasked — `audit_repository` without `action="run"` returns the question — and
+it hands back the **work order first**, because the score is second class.
+
+## Auditing a pull request
+
+```bash
+secure-code-agent . --changed-only origin/main
+```
+
+The whole tree is still scanned; the *report* is scoped to what changed. **No
+grade is issued** for a scoped run, because a run that looks at less must not
+score better.
+
+## Proving the agent stayed inside the order
+
+```bash
+secure-code-agent . --verify-against before.json
+```
+
+Reports what was fixed, what is still open, what was **silenced rather than
+fixed** — and the blast radius: which changed files the work order never
+cited.
+
+```
+work order verification  ·  improved: 1 fixed
+  fixed      sca.python.subprocess.shell_true   bad.py:3
+  scope: EXCEEDED — 1 of 2 changed file(s) were never cited: src/other.py
+```
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -470,7 +509,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.11.0
+- uses: marshallguillory86/secure-code-agent@v0.12.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_agent.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ src/secure_code_audit/findings.py
 src/secure_code_audit/git_tools.py
 src/secure_code_audit/history.py
 src/secure_code_audit/instructions.py
+src/secure_code_audit/mcp_server.py
 src/secure_code_audit/pillar.py
 src/secure_code_audit/practice.py
 src/secure_code_audit/remediation.py

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_agent.egg-info/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
 secure-code-agent = secure_code_audit.cli:main
+secure-code-agent-mcp = secure_code_audit.mcp_server:main
 secure-code-audit = secure_code_audit.cli:main

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_agent.egg-info/requires.txt

@@ -6,6 +6,9 @@ pytest>=8.0
 pytest-cov>=4.0
 ruff==0.16.2
 
+[mcp]
+mcp<2,>=1.0
+
 [python-scanners]
 secure-code-agent[required-scanners]
 semgrep<2,>=1.172

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/__init__.py

@@ -12,4 +12,4 @@
 #:
 #: PyPI is immutable, so 0.4.0 stays wrong. 0.5.0 is the first build whose
 #: artifacts name their own producer correctly.
-__version__ = "0.11.0"
+__version__ = "0.12.0"

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/cli.py

@@ -22,6 +22,7 @@ from secure_code_audit import (
     sarif,
     scanners,
     suppressions,
+    triage,
 )
 from secure_code_audit import baseline as baseline_mod
 from secure_code_audit import config as config_mod
@@ -111,7 +112,16 @@ def _parser() -> argparse.ArgumentParser:
         "--fail-on-new", action="store_true", help="Exit nonzero on findings not in baseline."
     )
 
-    p.add_argument("--changed-only", help="Audit only files changed since REF (e.g. main...HEAD).")
+    p.add_argument(
+        "--changed-only",
+        metavar="REF",
+        help=(
+            "Report only findings in files changed since REF (e.g. main...HEAD). "
+            "The whole tree is still scanned — scanners read trees, not diffs — "
+            "and the grade is WITHHELD, because a run that looks at less must "
+            "not score better."
+        ),
+    )
     p.add_argument("--skip-scanners", help="Comma-separated scanner names to skip.")
     p.add_argument("--only-scanners", help="Comma-separated scanner names — only these run.")
     p.add_argument(
@@ -400,6 +410,19 @@ def _do_audit(args: argparse.Namespace) -> int:
     root_for_tests = target if target.is_dir() else target.parent
 
     def _classify(finding: Finding) -> str:
+        # A dependency advisory is about the dependency, not about the file
+        # that happened to declare it. Classified by category before path,
+        # because the path routing gets it wrong: `requirements.txt` matches
+        # the documentation pattern `**/*.txt`, so every CVE in a pip
+        # manifest was filed under **documentation** — eighteen of them on a
+        # six-file demo tree. A dependency finding is not documentation
+        # whatever the manifest is called.
+        #
+        # Returning "primary" hands it to `split_side_axes` below, which is
+        # what moves it onto the dependencies axis. Neither axis is scored,
+        # so this changes where a finding is *reported*, not the grade.
+        if finding.category is Category.DEPENDENCIES:
+            return "primary"
         if is_test_path(finding.file_path, root_for_tests, cfg.test_patterns):
             return "test tree"
         if is_test_path(finding.file_path, root_for_tests, cfg.docs_patterns):
@@ -418,6 +441,11 @@ def _do_audit(args: argparse.Namespace) -> int:
     #   * the baseline. `baseline.write` recorded only the primary set, so
     #     every side-axis finding was absent from it and `fail_on_new`
     #     re-flagged the same test-tree secret as new on every run, forever.
+    if args.changed_only:
+        all_findings, changed_note = _restrict_to_changed(all_findings, root, args.changed_only)
+    else:
+        changed_note = None
+
     primary_findings, path_axes = partition_by_path(all_findings, _classify)
     test_findings = path_axes.get("test tree", [])
     docs_findings = path_axes.get("documentation", [])
@@ -480,7 +508,27 @@ def _do_audit(args: argparse.Namespace) -> int:
     gate = evaluate_gates(
         gated, score, {**cfg.gates, "_baseline_state": baseline_state.value}, coverage
     )
-    verdict = build_verdict(score, cfg.gates, coverage)
+    # A first run has triaged nothing: no baseline exists, so no finding has
+    # been accepted, deferred or dismissed by anyone. Counted from the
+    # actionable set (§FIX and §REVIEW), not the raw total — §ACCEPT is the
+    # test tree and documentation, which the work order explicitly says not
+    # to patch, and counting those would make every repository look untriaged
+    # forever.
+    untriaged = 0
+    if baseline_state is baseline_mod.State.ABSENT:
+        tiers = triage.partition(all_findings, lambda f: renderers.axis_of(f, axes))
+        untriaged = len(tiers[triage.Tier.FIX]) + len(tiers[triage.Tier.REVIEW])
+    verdict = build_verdict(score, cfg.gates, coverage, untriaged)
+    if changed_note is not None:
+        # A scoped run has no denominator it can defend: the LOC is the whole
+        # tree and the findings are a slice of it, so any number would be
+        # flattering by construction. Withhold the grade and say why. The
+        # findings, the work order and the gate are all still real.
+        verdict = replace(
+            verdict,
+            verified_grade=None,
+            reasons=(*verdict.reasons, changed_note),
+        )
 
     # ----- write outputs -----
     # The pillar artifact is what maintainability-agent ingests (D3). Built
@@ -528,13 +576,14 @@ def _do_audit(args: argparse.Namespace) -> int:
 
     # ----- did the work order actually improve anything? -----
     if args.verify_against:
-        return _do_verify(args, all_findings, root, axes)
+        return _do_verify(args, all_findings, root, axes, own_artifacts)
 
     # ----- terminal output -----
     if args.json:
         sys.stdout.write(
             json.dumps(
-                renderers.to_json(all_findings, score, gate, coverage, verdict, axes), indent=2
+                renderers.to_json(all_findings, score, gate, coverage, verdict, axes, root),
+                indent=2,
             )
         )
         sys.stdout.write("\n")
@@ -548,10 +597,11 @@ def _prepare_audit(
     args: argparse.Namespace,
 ) -> tuple[config_mod.Config, Path, Path]:
     """Load config and resolve the single scan root, or refuse."""
-    if args.changed_only:
-        raise ValueError(
-            "--changed-only is not implemented safely; refusing to claim a scoped audit"
-        )
+    # `--changed-only` used to refuse outright, because a scoped audit that
+    # produced a score would let looking at less score better — the
+    # absence-as-value defect, arriving through a convenience flag. It is
+    # implemented now, and the refusal is replaced by the property that made
+    # it unsafe: a scoped run reports findings and **never a grade**.
     if len(args.paths) > 1:
         raise ValueError("multiple scan roots are not supported; provide one repository root")
     # The target is resolved first because the default config belongs to it.
@@ -856,7 +906,7 @@ def _write_outputs(
             findings, score, gate, paths.markdown, ran, unavailable, coverage, verdict, axes
         )
     if paths.json_out is not None:
-        renderers.write_json(findings, score, gate, paths.json_out, coverage, verdict, axes)
+        renderers.write_json(findings, score, gate, paths.json_out, coverage, verdict, axes, root)
     if paths.sarif is not None:
         sarif.write(findings, paths.sarif, coverage, lambda f: renderers.axis_of(f, axes))
     if paths.comment is not None:
@@ -1056,7 +1106,7 @@ def _print_summary(
         status = "PASS"
     else:
         status = "NOT CONFIGURED"
-    print(f"secure-code-agent  ·  score {verdict.headline()}  ·  gate {status}")
+    print(f"secure-code-agent  ·  {verdict.headline()}  ·  gate {status}")
     for reason in verdict.reasons:
         print(f"  ! grade withheld: {reason}")
     print(f"  scanned LOC: {score.loc_scanned:,}")
@@ -1158,15 +1208,34 @@ def _findings_from_report(path: Path) -> list[Finding]:
     return restored
 
 
-def _do_verify(args: argparse.Namespace, after: list[Finding], root: Path, axes=()) -> int:
+def _do_verify(
+    args: argparse.Namespace,
+    after: list[Finding],
+    root: Path,
+    axes=(),
+    own_artifacts: frozenset[Path] = frozenset(),
+) -> int:
     """Compare this run against the one that produced the work order.
 
     Exits nonzero unless the run passes, because a verification step that
     always passes verifies nothing. "Improved" is deliberately
     strict: something fixed, nothing introduced, nothing merely silenced.
     """
-    before = _findings_from_report(_under_root(root, args.verify_against))
+    report_path = _under_root(root, args.verify_against)
+    before = _findings_from_report(report_path)
     result = verify_mod.compare(before, after, root, lambda f: renderers.axis_of(f, axes))
+    # Blast radius: what changed that the order never cited. Reads the commit
+    # the before-report was taken at; unknown rather than conformant when the
+    # report predates that field or the tree is not a git repository.
+    result = replace(
+        result,
+        scope=verify_mod.measure_scope(
+            before,
+            root,
+            _commit_of_report(report_path),
+            ours={*own_artifacts, report_path},
+        ),
+    )
 
     if args.json:
         sys.stdout.write(json.dumps(verify_mod.to_dict(result), indent=2) + "\n")
@@ -1194,11 +1263,61 @@ def _do_verify(args: argparse.Namespace, after: list[Finding], root: Path, axes=
                 f"  ({len(result.deferred)} finding(s) in the test tree and documentation "
                 f"are reported but not required — see §ACCEPT)"
             )
+        print(f"  {result.scope.headline()}")
+        for path in sorted(result.scope.collateral)[:10]:
+            print(f"    collateral {path}")
         for note in result.notes:
             print(f"  ! {note}")
 
     return 0 if result.passed else 1
 
 
+def _restrict_to_changed(
+    findings: list[Finding], root: Path, ref: str
+) -> tuple[list[Finding], str]:
+    """Keep only findings in files changed since `ref`.
+
+    The whole tree is still scanned. Scanners read trees rather than diffs,
+    and asking one to look at a subset changes what it can see — Semgrep's
+    cross-file dataflow being the obvious case. So the *scan* is complete and
+    the *report* is scoped, which is the only ordering that does not quietly
+    trade coverage for speed.
+
+    A ref git cannot resolve is an error rather than an empty diff. "Nothing
+    changed" and "your ref is wrong" produce the same finding count and only
+    one of them should exit 0.
+    """
+    from secure_code_audit.git_tools import changed_files
+
+    paths, reason = changed_files(root, ref)
+    if paths is None:
+        raise ValueError(f"--changed-only {ref}: {reason}")
+
+    absolute = {(root / path).resolve() for path in paths}
+
+    def touched(finding: Finding) -> bool:
+        try:
+            return finding.file_path.resolve() in absolute
+        except OSError:
+            return False
+
+    kept = [f for f in findings if f.severity is Severity.INFORMATIONAL or touched(f)]
+    note = (
+        f"scoped to files changed since {ref} — a grade needs the whole tree, "
+        f"and this run reports a slice of it"
+    )
+    return kept, note
+
+
+def _commit_of_report(path: Path) -> str | None:
+    """The commit a saved report was taken at, if it recorded one."""
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    commit = payload.get("commit")
+    return commit if isinstance(commit, str) and commit else None
+
+
 if __name__ == "__main__":
     sys.exit(main())

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/demo.py

@@ -101,11 +101,11 @@ def build(destination: Path | None = None) -> Path:
     (root / "README.md").write_text(README, encoding="utf-8")
     # No dependency manifest. A pinned-vulnerable `requirements.txt` was here
     # and it made the demo worse, not better: eighteen pip-audit CVEs drowned
-    # the seven code defects the demo exists to show. It also surfaced a
-    # separate defect worth its own fix — those CVEs were filed on the
-    # **documentation** axis, because the manifest is a `.txt` file and the
-    # axis split reads the extension. A dependency finding is not
-    # documentation whatever the manifest is called.
+    # the seven code defects the demo exists to show.
+    #
+    # It also surfaced a real defect, since fixed: those CVEs were filed on
+    # the **documentation** axis, because the manifest is a `.txt` file and
+    # the axis split read the extension before the category.
     return root
 
 

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/git_tools.py

@@ -216,3 +216,92 @@ def loc_under(
         else:
             primary += lines
     return primary, test, docs
+
+
+def _git() -> str | None:
+    """Resolve `git` to an absolute path, once.
+
+    Invoking a bare `git` leaves the choice of binary to `PATH`, which is the
+    same class of exposure this project refuses for scanner commands — and
+    Bandit says so (`B607`, partial executable path). Resolving it is cheaper
+    than suppressing it, and consistent with how every scanner adapter here
+    already resolves its tool.
+    """
+    import shutil  # noqa: PLC0415
+
+    return shutil.which("git")
+
+
+def head_commit(root: Path) -> str | None:
+    """The commit an audit was taken at, or None outside a git repository.
+
+    Recorded in the JSON report so a later `--verify-against` can ask *what
+    actually changed* rather than inferring it from two finding sets. Two
+    reports tell you which findings moved; they cannot tell you that an agent
+    also rewrote three unrelated modules, and that is the question the work
+    order's constraints exist to answer.
+    """
+    import subprocess  # noqa: PLC0415 — only needed on this path
+
+    git = _git()
+    if git is None:
+        return None
+    try:
+        completed = subprocess.run(
+            [git, "-C", str(root), "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    sha = completed.stdout.strip()
+    return sha or None
+
+
+def changed_files(root: Path, since: str) -> tuple[frozenset[str], str | None] | tuple[None, str]:
+    """Repository-relative paths changed since `since`, or a reason it is unknown.
+
+    Includes uncommitted work, because an agent handed a work order usually
+    has not committed. `git diff --name-only <sha>` covers tracked
+    modifications against the working tree; untracked files are asked for
+    separately, since a newly added module is exactly the kind of collateral
+    worth seeing.
+
+    Returns `(paths, None)` on success and `(None, reason)` when the answer is
+    unavailable — never an empty set standing in for "could not tell", which
+    would read as "nothing changed" and turn a failed measurement into a
+    clean bill of health.
+    """
+    import subprocess  # noqa: PLC0415
+
+    git = _git()
+    if git is None:
+        return None, "git is not on PATH"
+
+    def _run(args: list[str]) -> tuple[str, str | None]:
+        try:
+            completed = subprocess.run(
+                [git, "-C", str(root), *args],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            return "", f"git failed: {type(exc).__name__}"
+        if completed.returncode != 0:
+            return "", (completed.stderr.strip().splitlines() or ["git failed"])[0]
+        return completed.stdout, None
+
+    tracked, reason = _run(["diff", "--name-only", since])
+    if reason is not None:
+        return None, reason
+    untracked, reason = _run(["ls-files", "--others", "--exclude-standard"])
+    if reason is not None:
+        return None, reason
+    paths = {line.strip() for line in (tracked + untracked).splitlines() if line.strip()}
+    return frozenset(paths), None

secure_code_agent-0.12.0/src/secure_code_audit/mcp_server.py

@@ -0,0 +1,186 @@
+"""An MCP door, because almost nobody lives in the CLI.
+
+A reviewer's objection: *"It is named agent and there is no chat door. No
+MCP. Skills are files you copy. MA already learned almost nobody lives in the
+CLI. This still does."* That is fair, and `maintainability-agent` learned it
+first — its server is the reference for the shape used here.
+
+**The server never audits unasked.** `audit_repository` without an explicit
+`action` returns a question, not a result. Scanning someone's repository is
+not a thing to do because a model inferred it might be useful, and a tool
+that audits on mention trains people to stop reading what it did.
+
+**It returns the work order, not only the score.** The score is second class
+here by design; the work order is the product, and a chat surface that hands
+back a letter grade would invert that.
+
+Optional: `pip install 'secure-code-agent[mcp]'`. Nothing in the package
+imports this module unless the server is started, so the dependency stays
+off the default install.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from secure_code_audit import __version__
+
+
+def _run_cli(args: list[str]) -> tuple[int, str, str]:
+    """Drive the CLI rather than reimport its internals.
+
+    The CLI is the tested surface: gates, containment, the axis split and
+    coverage integrity all live behind it. A second entry point that
+    assembled the same pieces differently would be a second set of bugs, and
+    the one thing this project cannot afford is two answers to "what did you
+    find".
+    """
+    completed = subprocess.run(
+        [sys.executable, "-m", "secure_code_audit.cli", *args],
+        capture_output=True,
+        text=True,
+        timeout=1800,
+        check=False,
+    )
+    return completed.returncode, completed.stdout, completed.stderr
+
+
+def _audit(path: str, extra: list[str] | None = None) -> dict[str, Any]:
+    target = Path(path).expanduser().resolve()
+    if not target.exists():
+        return {"error": f"path does not exist: {target}", "audit_ran": False}
+
+    with tempfile.TemporaryDirectory(prefix="sca-mcp-") as tmp:
+        report = Path(tmp) / "report.json"
+        prompt = Path(tmp) / "work-order.md"
+        code, out, err = _run_cli(
+            [
+                str(target),
+                "--json-output",
+                str(report),
+                "--prompt-output",
+                str(prompt),
+                # No report, work order, SARIF or baseline is written into
+                # the operator's tree from a chat surface — they land in a
+                # temp directory and are read back.
+                #
+                # One thing IS written: `.secure-code/history.jsonl`, this
+                # tool's own state directory, because that is how `trend`
+                # works across runs and a trend is the score's one genuine
+                # use. Saying "writes nothing" would have been the tidier
+                # sentence and a false one; a test asserts the tree is
+                # otherwise untouched.
+                "--output",
+                str(Path(tmp) / "report.md"),
+                *(extra or []),
+            ]
+        )
+        if not report.is_file():
+            return {
+                "error": "the audit did not produce a report",
+                "exit_code": code,
+                "stderr": err[-2000:],
+                "audit_ran": False,
+            }
+        payload = json.loads(report.read_text(encoding="utf-8"))
+        work_order = prompt.read_text(encoding="utf-8") if prompt.is_file() else ""
+
+    score = payload.get("score", {})
+    coverage = payload.get("coverage", {})
+    return {
+        "audit_ran": True,
+        "exit_code": code,
+        "summary": out.strip().splitlines()[:1],
+        # The work order first, deliberately. It is the output that changes
+        # the code; the score is the one that describes it.
+        "work_order": work_order,
+        "verified_grade": score.get("verified_grade"),
+        "score": score.get("overall"),
+        "evidence_status": score.get("evidence_status"),
+        "evidence_reasons": score.get("evidence_reasons", []),
+        "coverage_status": coverage.get("status"),
+        "scanners_missing": [
+            s.get("name") for s in coverage.get("scanners", []) if s.get("outcome") != "completed"
+        ],
+        "gate": payload.get("gate", {}),
+        "producer": {"tool": "secure-code-agent", "version": __version__},
+    }
+
+
+def build_server():  # pragma: no cover - exercised by the smoke test below
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP("secure-code-agent")
+
+    @server.tool()
+    def audit_repository(path: str, action: str | None = None) -> dict[str, Any]:
+        """Audit a repository and return its bounded work order.
+
+        `action` must be `"run"` before anything is scanned. Called without
+        it, this returns the question instead — auditing someone's code
+        because it came up in conversation is not a thing to do quietly.
+        """
+        if action != "run":
+            return {
+                "audit_ran": False,
+                "choice_needed": (
+                    f"Audit {path}? This runs the scanner floor over the tree. "
+                    f"No report is written into it; only this tool's own "
+                    f"`.secure-code/history.jsonl` trend log is appended. "
+                    f"Call again with action='run' to proceed."
+                ),
+                "options": ["run", "preflight"],
+            }
+        return _audit(path)
+
+    @server.tool()
+    def preflight(path: str) -> dict[str, Any]:
+        """Which scanners resolve here, and how to install the ones that do not.
+
+        Read-only and safe to call unasked: it resolves tool paths and runs
+        nothing against the code.
+        """
+        code, out, err = _run_cli([path, "--preflight"])
+        return {"audit_ran": False, "exit_code": code, "report": out.strip() or err.strip()}
+
+    @server.tool()
+    def agent_info() -> dict[str, Any]:
+        """What this tool is for, so a model does not have to guess."""
+        return {
+            "tool": "secure-code-agent",
+            "version": __version__,
+            "produces": [
+                "a bounded work order an agent can act on (the product)",
+                "a coverage report stating what was examined (never inferred)",
+                "a score, which is second class to both",
+            ],
+            "never": [
+                "installs a scanner",
+                "audits without an explicit action='run'",
+                "grades what it could not examine",
+            ],
+        }
+
+    return server
+
+
+def main() -> int:
+    try:
+        server = build_server()
+    except ImportError:
+        sys.stderr.write(
+            "ERROR: the MCP server needs the `mcp` package.\n"
+            "       pip install 'secure-code-agent[mcp]'\n"
+        )
+        return 2
+    server.run()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/renderers.py

@@ -10,6 +10,7 @@ from pathlib import Path
 
 from secure_code_audit import __version__
 from secure_code_audit.findings import Finding, Severity
+from secure_code_audit.git_tools import head_commit
 from secure_code_audit.scanner_status import CoverageReport
 from secure_code_audit.scanners import floor
 from secure_code_audit.scoring import AxisReport, GateResult, ScoreReport, Verdict
@@ -27,11 +28,17 @@ def to_json(
     coverage: CoverageReport | None = None,
     verdict: Verdict | None = None,
     axes: Iterable[AxisReport] = (),
+    root: Path | None = None,
 ) -> dict:
     findings = list(findings)
     return {
         "version": __version__,
         "generated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        # The commit this was taken at, so a later `--verify-against` can ask
+        # what actually changed rather than inferring it from two finding
+        # sets. Null outside a git repository, which is honest: the scope
+        # measurement then reports itself unknown rather than conformant.
+        "commit": head_commit(root) if root is not None else None,
         "score": {
             "overall": score.overall,
             "letter": score.letter,
@@ -207,9 +214,10 @@ def write_json(
     coverage: CoverageReport | None = None,
     verdict: Verdict | None = None,
     axes: Iterable[AxisReport] = (),
+    root: Path | None = None,
 ) -> None:
     path.write_text(
-        json.dumps(to_json(findings, score, gate, coverage, verdict, axes), indent=2),
+        json.dumps(to_json(findings, score, gate, coverage, verdict, axes, root), indent=2),
         encoding="utf-8",
     )
 

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/scoring.py

@@ -151,6 +151,9 @@ class Verdict:
     estimated_letter: str | None
     verified_grade: str | None
     reasons: tuple[str, ...]
+    #: Findings exist and none has been triaged — no baseline, nothing
+    #: accepted, nobody has looked. See `headline`.
+    untriaged: int = 0
 
     @property
     def is_verified(self) -> bool:
@@ -161,17 +164,51 @@ class Verdict:
         return "complete" if self.is_verified else "incomplete"
 
     def headline(self) -> str:
-        """One line, used by every renderer that shows a score."""
+        """One line, used by every renderer that shows a score.
+
+        **An untriaged run leads with the work, not a letter.** A reviewer put
+        the failure precisely: *"a staff engineer who sees Django at F turns
+        the gate off."* They are right to, and the F is not wrong — it is a
+        density of findings nobody has looked at yet, which is a starting
+        position rather than a verdict on the code. Leading with the letter
+        invites the reader to treat it as one, and the letter they see on
+        first contact decides whether the tool survives the afternoon.
+
+        So on a first run with findings and no baseline, the headline states
+        the work. The number is still in the report, in the JSON, and in the
+        trend; it is simply not the first thing said about a repository
+        nobody has triaged.
+        """
         if self.estimate is None:
             return "no score — nothing measurable was scanned"
+        if self.untriaged:
+            return f"{self.untriaged} finding(s), none triaged — a starting position, not a grade"
         if self.is_verified:
-            return f"{self.estimate:.2f} ({self.verified_grade})"
-        return f"{self.estimate:.2f} — grade withheld ({self.estimated_letter} unverified)"
+            return f"score {self.estimate:.2f} ({self.verified_grade})"
+        return f"score {self.estimate:.2f} — grade withheld ({self.estimated_letter} unverified)"
 
 
-def verdict(report: ScoreReport, gate_config: dict, coverage: CoverageReport | None) -> Verdict:
+def verdict(
+    report: ScoreReport,
+    gate_config: dict,
+    coverage: CoverageReport | None,
+    untriaged: int = 0,
+) -> Verdict:
     """Decide the letter, or withhold it, once for the whole run."""
     reasons = list(evidence_reasons(gate_config, coverage))
+    # `untriaged` deliberately does NOT join `reasons`.
+    #
+    # It did, briefly, and that conflated two different axes. `reasons`
+    # answers *did we look* — coverage, required scanners, evidence — and
+    # withholding the grade is its consequence. Triage answers *did you
+    # review what we found*, which is the operator's work rather than the
+    # scanners'. Folding it in made a verified grade unreachable on first
+    # contact for any repository with a single finding, and
+    # `test_a_grade_is_issued_only_when_a_declared_scanner_set_actually_ran`
+    # caught it: the positive half of P7 stopped being reachable.
+    #
+    # So an untriaged run changes what the headline *leads with* and nothing
+    # else. The grade is still computed, still reported, still in the trend.
     if report.overall is None:
         # Nothing measurable ran. There is no estimate to qualify, so the
         # reason is stated rather than a letter being caveated — a caveated
@@ -182,6 +219,7 @@ def verdict(report: ScoreReport, gate_config: dict, coverage: CoverageReport | N
         estimated_letter=report.letter,
         verified_grade=None if reasons else report.letter,
         reasons=tuple(reasons),
+        untriaged=untriaged,
     )
 
 

{secure_code_agent-0.11.0 → secure_code_agent-0.12.0}/src/secure_code_audit/verify.py

@@ -44,6 +44,108 @@ class Outcome(enum.Enum):
     INTRODUCED = "introduced"
 
 
+@dataclass(frozen=True)
+class Scope:
+    """Did the work stay inside the order?
+
+    The product's claim is that a bounded work order keeps an agent from
+    doing crypto roulette, auth rewrites and 600-line "while I was in there"
+    patches. Until now only *silencing* and *regressions* were mechanical —
+    a reviewer put it exactly: "ten hard constraints are a leash I can still
+    ignore ... not for 'did you rewrite the session model'."
+
+    This makes that question mechanical. The work order cites files and
+    lines; the repository knows what actually changed. Everything changed
+    outside the cited files is collateral, and collateral is the measurable
+    shadow of the constraint the prompt cannot enforce.
+
+    **`known` is False when the answer is unavailable** — no commit in the
+    before-report, or not a git repository. An unknown scope is reported as
+    unknown and never as conformant: a measurement that failed must not read
+    as a clean result, which is the same rule the coverage axis applies to
+    scanners.
+    """
+
+    known: bool = False
+    reason: str | None = None
+    #: Files the work order named.
+    cited: tuple[str, ...] = ()
+    #: Files that actually changed, including untracked additions.
+    changed: tuple[str, ...] = ()
+    #: Changed, and never cited. The blast radius.
+    collateral: tuple[str, ...] = ()
+
+    @property
+    def conformant(self) -> bool:
+        """Only ever True when the question was actually answered."""
+        return self.known and not self.collateral
+
+    def headline(self) -> str:
+        if not self.known:
+            return f"scope: unknown ({self.reason or 'no baseline commit recorded'})"
+        if not self.changed:
+            return "scope: nothing changed"
+        if not self.collateral:
+            return f"scope: conformant — {len(self.changed)} file(s), all cited in the order"
+        return (
+            f"scope: EXCEEDED — {len(self.collateral)} of {len(self.changed)} changed "
+            f"file(s) were never cited: {', '.join(sorted(self.collateral)[:5])}"
+            + (" …" if len(self.collateral) > 5 else "")
+        )
+
+
+def measure_scope(
+    before: Iterable[Finding],
+    root: Path | None,
+    since: str | None,
+    ours: Iterable[Path] = (),
+) -> Scope:
+    """Compare what the order cited against what the repository changed."""
+    if root is None:
+        return Scope(reason="no repository root")
+    if not since:
+        return Scope(reason="the before-report records no commit")
+
+    from secure_code_audit.git_tools import changed_files
+
+    paths, reason = changed_files(root, since)
+    if paths is None:
+        return Scope(reason=reason)
+
+    cited: set[str] = set()
+    for finding in before:
+        try:
+            cited.add(finding.file_path.resolve().relative_to(root.resolve()).as_posix())
+        except (ValueError, OSError):
+            cited.add(finding.file_path.as_posix())
+
+    # This tool's own artifacts are written *by* the run doing the verifying.
+    # An agent that fixed something did not "also change
+    # secure-code-report.md"; we did, a second ago. Counting them as
+    # collateral would make every verification exceed its scope.
+    #
+    # The set comes from the caller — `cli._own_artifacts`, the same function
+    # that keeps a run from scanning its own report — rather than a list of
+    # default basenames here. A report written to `--json-output
+    # before.json` is ours too, and a hard-coded list of defaults said it was
+    # the agent's.
+    ignored: set[str] = set()
+    for artifact in ours:
+        try:
+            ignored.add(artifact.resolve().relative_to(root.resolve()).as_posix())
+        except (ValueError, OSError):
+            continue
+    changed = {
+        path for path in paths if path not in ignored and not path.startswith(".secure-code/")
+    }
+    return Scope(
+        known=True,
+        cited=tuple(sorted(cited)),
+        changed=tuple(sorted(changed)),
+        collateral=tuple(sorted(changed - cited)),
+    )
+
+
 @dataclass(frozen=True)
 class Verification:
     """What changed between two audits of the same repository."""
@@ -60,6 +162,8 @@ class Verification:
     before_count: int = 0
     after_count: int = 0
     notes: tuple[str, ...] = field(default_factory=tuple)
+    #: Blast radius, when it could be measured.
+    scope: Scope = field(default_factory=Scope)
 
     @property
     def regressed(self) -> bool:
@@ -262,6 +366,17 @@ def compare(
     )
 
 
+def _scope_to_dict(scope: Scope) -> dict:
+    return {
+        "known": scope.known,
+        "reason": scope.reason,
+        "conformant": scope.conformant,
+        "cited": list(scope.cited),
+        "changed": list(scope.changed),
+        "collateral": list(scope.collateral),
+    }
+
+
 def to_dict(result: Verification) -> dict:
     """The machine-readable form, for CI and for maintainability-agent."""
 
@@ -291,5 +406,6 @@ def to_dict(result: Verification) -> dict:
         "deferred": _rows(result.deferred),
         "suppressed": _rows(result.suppressed),
         "introduced": _rows(result.introduced),
+        "scope": _scope_to_dict(result.scope),
         "notes": list(result.notes),
     }