secure-code-agent 0.7.0__tar.gz → 0.9.0__tar.gz

{secure_code_agent-0.7.0/src/secure_code_agent.egg-info → secure_code_agent-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.7.0
+Version: 0.9.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.7.0
+Version: 0.9.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT

{secure_code_agent-0.7.0 → secure_code_agent-0.9.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.7.0"
+__version__ = "0.9.0"

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/baseline.py

@@ -10,6 +10,7 @@ operator has acknowledged at a point in time. On the next run:
 from __future__ import annotations
 
 import datetime
+import enum
 import json
 import shutil
 import subprocess
@@ -32,6 +33,36 @@ class BaselineEntry:
     notes: str = ""
 
 
+class State(enum.Enum):
+    """Why the baseline is the shape it is.
+
+    `load` returns an empty mapping for a baseline that is absent, one that
+    is unreadable, and one that is genuinely empty. Downstream those look
+    identical and every finding reads as new — which is correct for the
+    first case, a silent failure for the second, and worth saying out loud
+    in all three once `fail_on_new` gates by default.
+
+    On a first run the honest message is "there is nothing to compare
+    against yet", not "2 new findings since baseline", which claims a
+    baseline exists and that these appeared after it.
+    """
+
+    ABSENT = "absent"
+    UNREADABLE = "unreadable"
+    PRESENT = "present"
+
+
+def state(path: Path) -> State:
+    """Distinguish a missing baseline from a broken one."""
+    if not path.exists():
+        return State.ABSENT
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return State.UNREADABLE
+    return State.PRESENT if isinstance(raw, dict) else State.UNREADABLE
+
+
 def load(path: Path) -> dict[str, BaselineEntry]:
     if not path.exists():
         return {}

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/cli.py

@@ -338,6 +338,7 @@ def _do_audit(args: argparse.Namespace) -> int:
     # ----- baseline -----
     baseline_path = _under_root(root, args.baseline or cfg.outputs["baseline_path"])
     baseline = baseline_mod.load(baseline_path)
+    baseline_state = baseline_mod.state(baseline_path)
     all_findings = baseline_mod.mark_new(all_findings, baseline)
 
     # ----- scoring -----
@@ -377,8 +378,9 @@ def _do_audit(args: argparse.Namespace) -> int:
     if cfg.loc_for_scoring:
         loc = int(cfg.loc_for_scoring.get("value", 0))
         test_loc = 0
+        docs_loc = 0
     else:
-        loc, test_loc = loc_under(
+        loc, test_loc, docs_loc = loc_under(
             target,
             cfg.include_extensions,
             cfg.exclude_patterns,
@@ -386,6 +388,7 @@ def _do_audit(args: argparse.Namespace) -> int:
             # Same set the findings were filtered against. Numerator and
             # denominator have to describe the same repository.
             own_artifacts,
+            cfg.docs_patterns,
         )
     # Dependencies come off the code-condition score and onto their own axis.
     # A CVE in a pinned dependency is fixed with a version bump; an injection
@@ -405,7 +408,7 @@ def _do_audit(args: argparse.Namespace) -> int:
     score = score_findings(scored_findings, loc, measurable)
     axes = (
         summarize_axis("test tree", test_findings, test_loc),
-        summarize_axis("documentation", docs_findings),
+        summarize_axis("documentation", docs_findings, docs_loc or None),
         summarize_axis("dependencies", dependency_findings),
     )
     # Naming an import on the command line asserts that it contributes coverage,
@@ -425,7 +428,12 @@ def _do_audit(args: argparse.Namespace) -> int:
     ]
     coverage = evaluate_coverage(executions, required)
     # Gates see the dependency advisories; the score does not.
-    gate = evaluate_gates(gated, score, cfg.gates, coverage)
+    # The gate needs to know *why* the baseline is empty to describe a first
+    # run truthfully. Passed in the config dict rather than as a parameter so
+    # the gate signature stays the one every check shares.
+    gate = evaluate_gates(
+        gated, score, {**cfg.gates, "_baseline_state": baseline_state.value}, coverage
+    )
     verdict = build_verdict(score, cfg.gates, coverage)
 
     # ----- write outputs -----
@@ -897,7 +905,15 @@ def _under_root(root: Path, value: str) -> Path:
 def _print_summary(
     verdict, score, gate, ran, unavailable, coverage, paths, axes=(), trend=None
 ) -> None:
-    status = "PASS" if gate.passed else "FAIL"
+    # "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
+    # false assurance.
+    if not gate.passed:
+        status = "FAIL"
+    elif gate.enforced:
+        status = "PASS"
+    else:
+        status = "NOT CONFIGURED"
     print(f"secure-code-agent  ·  score {verdict.headline()}  ·  gate {status}")
     for reason in verdict.reasons:
         print(f"  ! grade withheld: {reason}")
@@ -921,6 +937,15 @@ def _print_summary(
     if not gate.passed:
         for reason in gate.reasons:
             print(f"  ✗ {reason}")
+    elif not gate.enforced:
+        print(
+            "  ! no gate is configured, so nothing here could have failed. "
+            "This audit is a report, not a check."
+        )
+        print(
+            "    Set gates.fail_on_severity in secure-code-agent.json to make "
+            "findings block a build; read the work order either way."
+        )
     written = [
         str(p)
         for p in (

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/config.py

@@ -26,6 +26,17 @@ DEFAULT_EXCLUDES: tuple[str, ...] = (
     ".mypy_cache/",
     "**/*.min.js",
     "**/*.lock",
+    # Lockfiles that are not named `.lock`. `**/*.lock` catches
+    # `poetry.lock`, `Gemfile.lock`, `Cargo.lock` and `yarn.lock` and misses
+    # every lockfile the JavaScript ecosystem actually ships:
+    # `package-lock.json` alone was 9,699 of axios's 17,532 non-code lines
+    # and 5,845 of lodash's 6,222. A generated dependency manifest is not
+    # source, and counting it inflates the denominator that decides the
+    # grade.
+    "**/package-lock.json",
+    "**/npm-shrinkwrap.json",
+    "**/pnpm-lock.yaml",
+    "**/bun.lockb",
 )
 
 #: Conventional test-tree locations across the languages the floor reads.
@@ -169,7 +180,24 @@ class Config:
     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)
-    gates: dict[str, Any] = field(default_factory=dict)
+    #: Default policy: **ratchet on regressions**, not on absolute state.
+    #:
+    #: `fail_on_new` is the one gate measured to work. Severity-based
+    #: defaults cannot: `fail_on_severity: ["critical"]` caught none of four
+    #: known-vulnerable control repositories, and `["critical","high"]`
+    #: failed five of ten well-maintained ones while still missing SQL
+    #: injection and `pickle.loads`, which Bandit rates *medium*. See D15.
+    #:
+    #: The ratchet reads no severity at all, so it inherits none of that. A
+    #: false positive is baselined once and never asked about again, which
+    #: is the property a threshold cannot have. Measured across an adoption
+    #: lifecycle: first run fails (everything is new), `--bump-baseline`
+    #: accepts existing debt, an introduced SQL injection fails, reverting
+    #: passes.
+    #:
+    #: An empty `{}` was the previous default and provided no floor at all —
+    #: an absent gate cannot trip, so every audit "passed".
+    gates: dict[str, Any] = field(default_factory=lambda: {"fail_on_new": True})
     outputs: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_OUTPUTS))
     suppressions_file: str = ".scignore.yaml"
     loc_for_scoring: dict[str, Any] | None = None
@@ -343,7 +371,9 @@ def _from_dict(raw: dict[str, Any]) -> Config:
         raise ValueError(f"invalid severity override: {', '.join(invalid)}")
     if invalid := sorted(set(cfg.category_overrides.values()) - _CATEGORIES):
         raise ValueError(f"invalid category override: {', '.join(invalid)}")
-    cfg.gates = _validate_gates(raw.get("gates", {}))
+    # An operator who writes a `gates` block chooses their own policy
+    # entirely; the ratchet default applies only when they write none.
+    cfg.gates = _validate_gates(raw["gates"]) if "gates" in raw else dict(cfg.gates)
 
     outputs = raw.get("outputs", {})
     if not isinstance(outputs, dict):

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/git_tools.py

@@ -97,8 +97,9 @@ def loc_under(
     excludes: Iterable[str],
     test_patterns: Iterable[str] = (),
     skip: Iterable[Path] = (),
-) -> tuple[int, int]:
-    """Non-blank in-scope lines, split into (primary, test).
+    docs_patterns: Iterable[str] = (),
+) -> tuple[int, int, int]:
+    """Non-blank in-scope lines, split into (primary, test, docs).
 
     The split exists because the score's denominator has to move with its
     numerator. Scoring primary-tree findings over a LOC count that included the
@@ -106,6 +107,12 @@ def loc_under(
     tested — the same numerator/denominator mismatch that `exclude_patterns`
     already caused once, arriving by a different door.
 
+    Documentation is split for the same reason, and was not: its *findings*
+    move to their own axis and out of the score, while its *lines* stayed in
+    the primary denominator. FastAPI carries 7,160 lines of `docs/en/data/`
+    — translator and contributor lists — diluting the count its code is
+    graded against. Third occurrence of one mismatch.
+
     `skip` names the run's own artifacts — the report, the baseline, the
     suppressions file. Dropping their *findings* without dropping their
     *lines* is that same mismatch a third time: an audit that wrote a
@@ -114,9 +121,11 @@ def loc_under(
     unchanged repository returned 0.00 and 4.25.
     """
     test_patterns = tuple(test_patterns)
+    docs_patterns = tuple(docs_patterns)
     skip = {p.resolve() for p in skip}
     primary = 0
     test = 0
+    docs = 0
     # `rglob` on a file yields nothing, so a single-file audit reported zero
     # lines — and a zero denominator is not normalised at all, so the grade
     # became the raw subtotal. Auditing one file is supported; it should be
@@ -138,6 +147,8 @@ def loc_under(
         lines = sum(1 for line in text.splitlines() if line.strip())
         if test_patterns and is_test_path(path, root, test_patterns):
             test += lines
+        elif docs_patterns and is_test_path(path, root, docs_patterns):
+            docs += lines
         else:
             primary += lines
-    return primary, test
+    return primary, test, docs

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/renderers.py

@@ -51,6 +51,12 @@ def to_json(
         },
         "gate": {
             "passed": gate.passed,
+            # Which gates could actually have failed. Empty means no policy
+            # was configured, and `passed: true` then says only that nothing
+            # tripped — not that anything was checked. A consumer treating
+            # `passed` as a security signal needs to see this.
+            "configured": list(gate.configured),
+            "enforced": gate.enforced,
             "reasons": list(gate.reasons),
             "tripped": list(gate.tripped),
         },

{secure_code_agent-0.7.0 → secure_code_agent-0.9.0}/src/secure_code_audit/scoring.py

@@ -551,6 +551,26 @@ class GateResult:
     passed: bool
     reasons: tuple[str, ...]  # human-readable trip reasons
     tripped: tuple[str, ...] = field(default_factory=tuple)
+    #: Gates that could actually have failed this run. Empty means no
+    #: policy was configured, which is **not** the same as passing one.
+    #:
+    #: `passed` stays True in that case — no gate tripped, which is
+    #: accurate — but reporting it as PASS is a claim nothing checked. A
+    #: 200,000-line repository carrying SQL injection, `shell=True`,
+    #: `pickle.loads` and `eval` printed "gate PASS" out of the box, with
+    #: no configuration, because an absent gate cannot trip. The work
+    #: order listed all seven findings correctly at the same time.
+    #:
+    #: `_require_configured_gates` already refuses `--fail-on-gate` in this
+    #: situation, calling it "a green build with no security floor". This
+    #: is the same fact, carried far enough to reach the summary line a
+    #: person actually reads.
+    configured: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def enforced(self) -> bool:
+        """Did any gate actually stand between these findings and a pass?"""
+        return bool(self.configured)
 
 
 # Every gate, with the predicate that decides whether it can actually trip.
@@ -611,6 +631,7 @@ def evaluate_gates(
         passed=not tripped,
         reasons=tuple(reasons),
         tripped=tuple(tripped),
+        configured=active_gates(gate_config),
     )
 
 
@@ -670,7 +691,26 @@ def _gate_fail_on_new(
     ]
     if new_findings:
         tripped.append("fail_on_new")
-        reasons.append(f"{len(new_findings)} new finding(s) since baseline")
+        # What "new" means depends on whether there is anything to be new
+        # *against*. Saying "since baseline" when no baseline exists claims
+        # these findings appeared after one, which is the opposite of the
+        # truth on a first run.
+        baseline_state = gate_config.get("_baseline_state")
+        if baseline_state == "absent":
+            reasons.append(
+                f"{len(new_findings)} finding(s), and no baseline exists yet — on a first "
+                f"run everything is new because there is nothing to compare against. "
+                f"Work the order, then re-run with --bump-baseline to accept what is "
+                f"left and gate on regressions from there."
+            )
+        elif baseline_state == "unreadable":
+            reasons.append(
+                f"{len(new_findings)} finding(s) read as new because the baseline file "
+                f"could not be parsed. Fix or delete it — a broken baseline silently "
+                f"turns an established repository back into a first run."
+            )
+        else:
+            reasons.append(f"{len(new_findings)} new finding(s) since baseline")
 
 
 def _gate_min_score(