secure-code-agent 0.12.5__tar.gz → 0.12.7__tar.gz

{secure_code_agent-0.12.5/src/secure_code_agent.egg-info → secure_code_agent-0.12.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.5
+Version: 0.12.7
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -513,7 +513,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.5
+- uses: marshallguillory86/secure-code-agent@v0.12.7
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/README.md

@@ -465,7 +465,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.5
+- uses: marshallguillory86/secure-code-agent@v0.12.7
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.5
+Version: 0.12.7
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -513,7 +513,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.5
+- uses: marshallguillory86/secure-code-agent@v0.12.7
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/src/secure_code_agent.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/secure_code_agent.egg-info/requires.txt
 src/secure_code_agent.egg-info/top_level.txt
 src/secure_code_audit/__init__.py
 src/secure_code_audit/baseline.py
+src/secure_code_audit/capabilities.py
 src/secure_code_audit/cli.py
 src/secure_code_audit/config.py
 src/secure_code_audit/demo.py

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/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.12.5"
+__version__ = "0.12.7"

secure_code_agent-0.12.7/src/secure_code_audit/capabilities.py

@@ -0,0 +1,137 @@
+"""What a project declares it does, and the findings that follow from it.
+
+Some findings are not defects and never will be. A tool that runs external
+analyzers imports `subprocess` and spawns them; a tool that reads analyzer
+output parses XML it did not write. Bandit reports both, correctly — the
+observation is true. What was missing is any way for the project to say "yes,
+that is what this is", so the same findings were reported as defects on every
+run forever.
+
+The instruments that existed could only hide them. `exclude_patterns` stops
+the scan. `extra_args: --skip` turns the check off. Both leave a report that
+says nothing, which is the silence this tool exists to refuse — the same shape
+`_conformance` counts as a defect when it finds `NOSONAR` in someone else's
+tree. `.scignore.yaml` states a reason, but a suppression expires, and an
+architectural fact does not stop being true in a year; renewing it annually is
+a ritual that teaches people to renew rituals.
+
+A declaration is different from all three. The operator states, in the config,
+what the project does. Findings consistent with that declaration are routed to
+their own axis: **counted, listed in the report, and not scored**. Nothing is
+hidden, nothing expires, and a subprocess call written next year is already
+covered rather than generating a new exception.
+
+**Declared, never inferred.** The tool does not decide that a project looks
+like it spawns processes. It is told, in a file a reviewer reads, and the
+report names the declaration next to the findings it accounts for. Inference
+here would make the grade depend on a guess about the codebase, which is the
+property this rubric does not have anywhere else.
+
+**A declaration is falsifiable.** Declaring a capability the project does not
+exercise is itself reported (`unexercised`), so the config cannot be padded
+with pre-emptive declarations against findings that might arrive later.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from secure_code_audit.findings import Finding
+
+#: Capability name -> the rule ids whose finding *is* that capability being
+#: exercised. Deterministic and enumerated rather than pattern-matched: a
+#: reader can see exactly which observations a declaration accounts for, and
+#: a rule absent from this table is never routed by it.
+#:
+#: Scoped narrowly on purpose. `spawns_processes` covers the reports that say
+#: "this code starts a process", not every report that happens to occur in a
+#: file that also starts one. B602 (`shell=True`) is deliberately **not**
+#: here: spawning a process is architecture, handing a string to a shell is a
+#: decision, and a project that declares the former has not excused the latter.
+CAPABILITY_RULES: dict[str, frozenset[str]] = {
+    "spawns_processes": frozenset(
+        {
+            "B404",  # import subprocess
+            "B603",  # subprocess call without shell
+            "B606",  # start process with no shell
+            "B607",  # start process with a partial executable path
+        }
+    ),
+    "parses_untrusted_xml": frozenset(
+        {
+            "B313",  # xml.etree.cElementTree
+            "B314",  # xml.etree.ElementTree
+            "B405",  # import xml.etree
+            "B406",  # import xml.sax
+            "B408",  # import xml.minidom
+            "B409",  # import xml.pulldom
+        }
+    ),
+    "fetches_remote_urls": frozenset(
+        {
+            "B310",  # urllib.request.urlopen
+        }
+    ),
+    "uses_nondeterministic_randomness": frozenset(
+        {
+            "B311",  # random, not suitable for cryptography
+        }
+    ),
+}
+
+#: The axis a declared finding is reported on, prefixed so a reader of the
+#: report can tell a declaration apart from a path-derived side axis.
+AXIS_PREFIX = "declared: "
+
+
+@dataclass(frozen=True)
+class DeclarationReport:
+    """What the declarations accounted for, for the report to state."""
+
+    #: Capability -> the operator's stated reason, as written in the config.
+    declared: dict[str, str]
+    #: Capability -> how many findings it accounted for.
+    accounted: dict[str, int]
+    #: Declared, and nothing matched it. A declaration that describes nothing
+    #: this project does is reported rather than ignored, because a config can
+    #: otherwise be padded against findings that have not arrived yet.
+    unexercised: tuple[str, ...]
+
+    @property
+    def total_accounted(self) -> int:
+        return sum(self.accounted.values())
+
+
+def unknown_capabilities(declared: Iterable[str]) -> tuple[str, ...]:
+    """Declared names this build has no rules for.
+
+    A typo in a capability name would otherwise declare nothing and route
+    nothing, silently, and the operator would read a report that still scored
+    the findings they thought they had accounted for.
+    """
+    return tuple(sorted(name for name in declared if name not in CAPABILITY_RULES))
+
+
+def capability_for(finding: Finding, declared: Iterable[str]) -> str | None:
+    """The declared capability this finding is an instance of, or None."""
+    for name in declared:
+        if finding.rule_id in CAPABILITY_RULES.get(name, frozenset()):
+            return name
+    return None
+
+
+def summarize_declarations(
+    declared: dict[str, str], findings: Iterable[Finding]
+) -> DeclarationReport:
+    """Count what each declaration accounted for, and what accounted for nothing."""
+    accounted = dict.fromkeys(declared, 0)
+    for finding in findings:
+        name = capability_for(finding, declared)
+        if name is not None:
+            accounted[name] += 1
+    return DeclarationReport(
+        declared=dict(declared),
+        accounted=accounted,
+        unexercised=tuple(sorted(n for n, count in accounted.items() if count == 0)),
+    )

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/src/secure_code_audit/cli.py

@@ -30,6 +30,11 @@ from secure_code_audit import history as history_mod
 from secure_code_audit import pillar as pillar_mod
 from secure_code_audit import practice as practice_mod
 from secure_code_audit import verify as verify_mod
+from secure_code_audit.capabilities import (
+    AXIS_PREFIX,
+    capability_for,
+    summarize_declarations,
+)
 from secure_code_audit.findings import (
     Category,
     Confidence,
@@ -454,6 +459,16 @@ def _do_audit(args: argparse.Namespace) -> int:
             return "test tree"
         if is_test_path(located, root_for_tests, cfg.docs_patterns):
             return "documentation"
+        # A finding that *is* a declared capability being exercised (D24),
+        # checked **after** the path axes. A subprocess call in the test tree
+        # is test tree: it is already unscored, and routing it to the
+        # declaration instead moved 492 findings off the tree's own axis and
+        # made the declaration look like it accounted for work it did not.
+        # The declaration is for the shipped source, which is the only place
+        # the path axes leave on the primary axis.
+        declared_as = capability_for(finding, cfg.capabilities)
+        if declared_as is not None:
+            return AXIS_PREFIX + declared_as
         return "primary"
 
     # `all_findings` keeps meaning *all* of them. Rebinding it to the primary
@@ -504,13 +519,60 @@ def _do_audit(args: argparse.Namespace) -> int:
     # named — a secret matters wherever it lives, a test fixture's HIGH code
     # smell does not, and feeding a deliberately-vulnerable fixture tree to
     # `fail_on_severity` would fail every build in the corpus.
-    gated = gate_set(primary_findings, (test_findings, docs_findings), cfg.gates)
+    # Every axis whose name carries the declaration prefix, in the order the
+    # operator declared them so the report is stable across runs.
+    declared_axes = {
+        AXIS_PREFIX + name: path_axes.get(AXIS_PREFIX + name, []) for name in cfg.capabilities
+    }
+    # Declared axes gate on the same terms as the path axes: a secret is a
+    # secret wherever it is found, and declaring that this project spawns
+    # processes does not excuse a credential sitting next to one.
+    gated = gate_set(
+        primary_findings,
+        (test_findings, docs_findings, *declared_axes.values()),
+        cfg.gates,
+    )
     measurable = _measurable_categories(executions, scored_findings)
+    # Counted over what was actually *routed*, not over every finding whose
+    # rule id matches. A subprocess call in the test tree is test tree, and
+    # counting it here made the disclosure claim 554 findings while the axis
+    # beside it showed 62 — two numbers about the same thing, in the same
+    # report, disagreeing by an order of magnitude.
+    declarations = summarize_declarations(
+        cfg.capabilities,
+        [f for found in declared_axes.values() for f in found],
+    )
     score = score_findings(scored_findings, loc, measurable)
+    # What the declarations bought, stated as a number rather than left for a
+    # reader to reconstruct (D24). A declaration moves the grade — that is its
+    # purpose, and `exclude_patterns` has always been able to move it further
+    # while leaving no trace at all. The difference is disclosure: this reports
+    # the score the same tree earns when the declarations are disregarded, so a
+    # project that declares its way up a band has to show that on its own
+    # report. Computed only when something was actually accounted for, so an
+    # undeclared repository's output is unchanged.
+    undeclared_score = None
+    if declarations.total_accounted:
+        undeclared_findings = list(scored_findings) + [
+            f for found in declared_axes.values() for f in found if not f.suppressed
+        ]
+        undeclared_score = score_findings(undeclared_findings, loc, measurable)
     axes = (
         summarize_axis("test tree", test_findings, test_loc),
         summarize_axis("documentation", docs_findings, docs_loc or None),
         summarize_axis("dependencies", dependency_findings),
+        # The note is the reason the project wrote, carried verbatim. A
+        # declared axis whose page shows counts and no statement of why is a
+        # grade moved in silence — the one thing this mechanism exists not to
+        # be (D25).
+        *(
+            summarize_axis(
+                name,
+                found,
+                note=cfg.capabilities[name.removeprefix(AXIS_PREFIX)],
+            )
+            for name, found in declared_axes.items()
+        ),
     )
     # Naming an import on the command line asserts that it contributes coverage,
     # so a broken one fails the gate even if no config requires that scanner.
@@ -615,7 +677,18 @@ def _do_audit(args: argparse.Namespace) -> int:
         )
         sys.stdout.write("\n")
     else:
-        _print_summary(verdict, score, gate, ran, unavailable, coverage, paths, axes, trend_line)
+        _print_summary(
+            verdict,
+            score,
+            gate,
+            ran,
+            unavailable,
+            coverage,
+            paths,
+            axes,
+            trend_line,
+            _declaration_delta(score, undeclared_score, declarations),
+        )
 
     return _exit_code(args, gate, all_findings)
 
@@ -1139,8 +1212,42 @@ def _print_install_guidance(unavailable: list[str]) -> None:
     print("    (or --preflight to check the whole floor before a run)")
 
 
+def _declaration_delta(score, undeclared_score, declarations) -> str | None:
+    """One line naming what the declarations accounted for, and what it cost.
+
+    `exclude_patterns` can move a grade further than this and says nothing at
+    all. The difference this mechanism is meant to hold is disclosure, so the
+    number a reader would otherwise have to reconstruct is printed for them.
+    """
+    if undeclared_score is None or not declarations.total_accounted:
+        return None
+    named = ", ".join(
+        f"{name} ({count})" for name, count in sorted(declarations.accounted.items()) if count
+    )
+    line = (
+        f"declared: {declarations.total_accounted} finding(s) accounted for by "
+        f"{named}; without declarations "
+        f"{undeclared_score.overall:.2f} ({undeclared_score.letter})"
+    )
+    if declarations.unexercised:
+        # A declaration that matched nothing describes something this project
+        # does not do. Named rather than dropped, so a config cannot be padded
+        # against findings that have not arrived yet.
+        line += f"; unexercised: {', '.join(declarations.unexercised)}"
+    return line
+
+
 def _print_summary(
-    verdict, score, gate, ran, unavailable, coverage, paths, axes=(), trend=None
+    verdict,
+    score,
+    gate,
+    ran,
+    unavailable,
+    coverage,
+    paths,
+    axes=(),
+    trend=None,
+    declaration_delta=None,
 ) -> None:
     # "PASS" is a claim that something was checked. With no gate configured
     # nothing was, and saying so is the difference between a report and a
@@ -1162,6 +1269,13 @@ def _print_summary(
     for axis in axes or ():
         if axis.count or axis.loc:
             print(f"  {axis.headline()}")
+    # What the declarations bought, next to the axes that show what they
+    # accounted for. Printed only when they accounted for something, and
+    # printed even when the two scores land in the same band — "no change"
+    # is the reassuring case and is exactly what a reader should be able to
+    # see without recomputing it.
+    if declaration_delta:
+        print(f"  {declaration_delta}")
     print(f"  scanners run: {', '.join(ran) if ran else '(none)'}")
     coverage_line = f"  coverage: {coverage.status.value.upper()}"
     if coverage.unverified:

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/src/secure_code_audit/config.py

@@ -11,6 +11,11 @@ from dataclasses import dataclass, field
 from pathlib import Path, PurePosixPath
 from typing import Any
 
+from secure_code_audit.capabilities import (
+    CAPABILITY_RULES,
+    unknown_capabilities,
+)
+
 DEFAULT_CONFIG_PATH = Path("secure-code-agent.json")
 
 DEFAULT_EXCLUDES: tuple[str, ...] = (
@@ -245,6 +250,13 @@ class Config:
     #: carries example JWTs that scored as critical secrets and drove it to F.
     #: Reported and gated like the test tree, never scored as code condition.
     docs_patterns: tuple[str, ...] = DEFAULT_DOCS_PATTERNS
+    #: What this project declares it does, as ``name -> reason`` (D24). A
+    #: finding that *is* a declared capability being exercised is reported on
+    #: its own axis rather than scored: a tool that runs analyzers spawns
+    #: processes, and reporting that as a defect on every run forever is the
+    #: observation being true and useless. Declared, never inferred, and
+    #: falsifiable — a declaration nothing matches is reported as unexercised.
+    capabilities: dict[str, str] = field(default_factory=dict)
     scanners: dict[str, ScannerConfig] = field(default_factory=dict)
     severity_overrides: dict[str, str] = field(default_factory=dict)
     category_overrides: dict[str, str] = field(default_factory=dict)
@@ -398,6 +410,7 @@ _KNOWN_KEYS = frozenset(
         "$schema",
         "version",
         "paths",
+        "capabilities",
         "scanners",
         "severity_overrides",
         "category_overrides",
@@ -442,6 +455,31 @@ def _from_dict(raw: dict[str, Any]) -> Config:
     if "docs_patterns" in paths:
         cfg.docs_patterns = tuple(_string_list(paths["docs_patterns"], "paths.docs_patterns"))
 
+    capabilities_raw = raw.get("capabilities", {})
+    if not isinstance(capabilities_raw, dict):
+        raise ValueError("capabilities must be a JSON object of name -> reason")
+    for name, reason in capabilities_raw.items():
+        if not isinstance(name, str) or not name:
+            raise ValueError("capability names must be non-empty strings")
+        if not isinstance(reason, str) or not reason.strip():
+            # A declaration without a reason is the thing this is meant to
+            # replace. The reason is what a reviewer reads to decide whether
+            # the declaration is still true, so an empty one is refused here
+            # rather than rendered as a blank line in the report.
+            raise ValueError(f"capabilities.{name} must state a non-empty reason")
+    unknown = unknown_capabilities(capabilities_raw)
+    if unknown:
+        # A typo would declare nothing, route nothing, and score the findings
+        # the operator believed they had accounted for -- silently, which is
+        # the failure mode this whole mechanism exists to remove.
+        raise ValueError(
+            "unknown capabilities: "
+            + ", ".join(unknown)
+            + "; known names are "
+            + ", ".join(sorted(CAPABILITY_RULES))
+        )
+    cfg.capabilities = dict(capabilities_raw)
+
     scanners_raw = raw.get("scanners", {})
     if not isinstance(scanners_raw, dict):
         raise ValueError("scanners must be a JSON object")

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/src/secure_code_audit/renderers.py

@@ -167,7 +167,7 @@ def _axes_to_dict(axes: Iterable[AxisReport]) -> dict:
             "count": axis.count,
             "scored": False,
             "gated": axis.name == "dependencies",
-            "note": _AXIS_NOTES.get(axis.name, ""),
+            "note": _axis_note(axis),
             "per_severity_count": {s.value: n for s, n in axis.per_severity_count.items()},
             "per_category_count": {c.value: n for c, n in axis.per_category_count.items()},
             # Not repeated here: every one of these appears in the top-level
@@ -206,6 +206,17 @@ _AXIS_NOTES = {
 }
 
 
+def _axis_note(axis: AxisReport) -> str:
+    """Why this axis sits outside the score, in the report's own words.
+
+    An axis that carries its own note wins. Only a declared axis does, and
+    its note is the reason the audited project wrote in its configuration —
+    the tool cannot supply that sentence, and a declared axis printed without
+    it is a grade moved with no statement of why.
+    """
+    return axis.note or _AXIS_NOTES.get(axis.name, "")
+
+
 def write_json(
     findings: Iterable[Finding],
     score: ScoreReport,
@@ -361,7 +372,7 @@ def _axis_section(report: AxisReport | None) -> str:
             )
         )
         out.append(f"- **By severity:** {by_severity}")
-    note = _AXIS_NOTES.get(report.name)
+    note = _axis_note(report)
     if note:
         out.append(f"- {note}")
     out.append("")

{secure_code_agent-0.12.5 → secure_code_agent-0.12.7}/src/secure_code_audit/scoring.py

@@ -554,6 +554,17 @@ class AxisReport:
     #: advisories are counted against a lockfile, not a line count, so this is
     #: None for them rather than a misleading zero.
     loc: int | None = None
+    #: Why this axis sits outside the score, in the report's own words. Empty
+    #: for the fixed axes, whose notes the renderer holds because they are the
+    #: same sentence for every project.
+    #:
+    #: A declared axis is the case this field exists for. Its justification is
+    #: not a constant the tool can write: it is the reason *this* project
+    #: stated in its configuration. 0.12.6 shipped the declaration reaching the
+    #: routing and never reaching the page, so a reader saw
+    #: `## Declared: spawns_processes` with counts under it and no statement of
+    #: why — which is the disclosure the whole mechanism rests on (D25).
+    note: str = ""
 
     @property
     def count(self) -> int:
@@ -580,7 +591,12 @@ class AxisReport:
         )
 
 
-def summarize_axis(name: str, findings: Iterable[Finding], loc: int | None = None) -> AxisReport:
+def summarize_axis(
+    name: str,
+    findings: Iterable[Finding],
+    loc: int | None = None,
+    note: str = "",
+) -> AxisReport:
     """Count an axis without scoring it.
 
     Not named `test_*` anything: pytest collects any callable whose name begins
@@ -601,6 +617,7 @@ def summarize_axis(name: str, findings: Iterable[Finding], loc: int | None = Non
     return AxisReport(
         name=name,
         loc=loc,
+        note=note,
         findings=findings,
         per_severity_count=per_severity,
         per_category_count=per_category,