secure-code-agent 0.8.0__tar.gz → 0.10.0__tar.gz

{secure_code_agent-0.8.0/src/secure_code_agent.egg-info → secure_code_agent-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.8.0
+Version: 0.10.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.8.0 → secure_code_agent-0.10.0/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.8.0
+Version: 0.10.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.8.0 → secure_code_agent-0.10.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.8.0"
+__version__ = "0.10.0"

{secure_code_agent-0.8.0 → secure_code_agent-0.10.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.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/cli.py

@@ -160,7 +160,11 @@ def _parser() -> argparse.ArgumentParser:
         "--target",
         action="append",
         default=[],
-        help="Target for --init-agent-standards (codex, claude-code, cursor, copilot, windsurf, generic).",
+        help=(
+            "Agent name for --init-agent-standards (codex, claude-code, cursor, "
+            "copilot, windsurf, generic). NOT the repository to audit — pass that "
+            "as a positional path."
+        ),
     )
     p.add_argument(
         "--instructions-output-dir",
@@ -183,6 +187,22 @@ def main(argv: list[str] | None = None) -> int:
     if args.init_agent_standards:
         return _do_init_standards(args)
 
+    if args.target:
+        # `--target` names an *agent* for --init-agent-standards, and it reads
+        # exactly like the flag for "the repository to audit". It was accepted
+        # and silently discarded on an audit run, so `--target /some/repo`
+        # audited the current directory instead and reported a clean result
+        # for a repository nobody had looked at. Found by using the tool: a
+        # 136k-line control was audited from inside itself and appeared to
+        # honour the flag, which is the kind of coincidence that keeps a bug.
+        sys.stderr.write(
+            "ERROR: --target names an agent for --init-agent-standards, not a "
+            "repository to audit.\n"
+            f"       To audit a repository, pass it as a path: "
+            f"secure-code-agent {args.target[0]}\n"
+        )
+        return 2
+
     try:
         return _do_preflight(args) if args.preflight else _do_audit(args)
     except ValueError as exc:
@@ -338,6 +358,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 +398,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 +408,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 +428,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 +448,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 -----

{secure_code_agent-0.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/config.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any
 
 DEFAULT_CONFIG_PATH = Path("secure-code-agent.json")
@@ -26,6 +26,53 @@ 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",
+    # --- stored analysis output -------------------------------------------
+    #
+    # This tool's own output is never its input, *wherever* it is stored.
+    #
+    # `cli._own_artifacts` already removes the paths the current run is about
+    # to write, which is what stopped an audit scoring the report it had just
+    # produced. It cannot see a *copy* kept somewhere else, and two
+    # independent reports of that landed on the same day:
+    #
+    #   - this repository scanned `calibration/.corpus` — fourteen cloned
+    #     third-party projects, 556,808 LOC and 550 findings, all about code
+    #     that is not ours;
+    #   - `maintainability-agent` scanned `tools/validation/reports/` —
+    #     957,219 LOC of stored audit output *about other repositories*,
+    #     4,929 findings, which diluted five genuine criticals to an A-.
+    #
+    # A stored report is the worst possible input: it quotes findings
+    # verbatim, including the code snippets and the redacted secrets that
+    # produced them, so it manufactures findings about findings and inflates
+    # the denominator at the same time.
+    #
+    # Filename patterns rather than directory names, because the directory is
+    # whatever the operator chose and the filenames are ours. Derived from
+    # `DEFAULT_OUTPUTS` below so the two cannot drift — see
+    # `_own_output_globs`.
+    #
+    # Deliberately NOT here: `vendor/`, `third_party/` and their kin. Vendored
+    # code is deployed code, and excluding it by default would hide real
+    # vulnerabilities in exactly the place nobody is reading. Stored analysis
+    # output is not code at all; that is the whole difference.
+    ".secure-code/",
+    "**/.secure-code/",
+    # maintainability-agent's state and output directory. Same argument: its
+    # reports quote findings, and its history is append-only JSONL.
+    ".maintainability/",
+    "**/.maintainability/",
 )
 
 #: Conventional test-tree locations across the languages the floor reads.
@@ -96,6 +143,24 @@ DEFAULT_OUTPUTS: dict[str, str] = {
     "history_path": ".secure-code/history.jsonl",
 }
 
+
+def _own_output_globs() -> tuple[str, ...]:
+    """Match this tool's default output filenames anywhere in a tree.
+
+    Kept as a function over `DEFAULT_OUTPUTS` rather than a hand-written list
+    so that adding an output cannot leave a file this tool writes readable by
+    the next run. `history_path` is already covered by the `.secure-code/`
+    directory entries; matching its basename anywhere would be wrong, since
+    `history.jsonl` is not a name this project owns.
+    """
+    names = {
+        PurePosixPath(path).name for key, path in DEFAULT_OUTPUTS.items() if key != "history_path"
+    }
+    return tuple(sorted(f"**/{name}" for name in names))
+
+
+DEFAULT_EXCLUDES = DEFAULT_EXCLUDES + _own_output_globs()
+
 _SEVERITIES = {"critical", "high", "medium", "low", "informational"}
 _CATEGORIES = {
     "secrets",
@@ -169,7 +234,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 +425,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.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/git_tools.py

@@ -58,9 +58,25 @@ def _matches(rel: str, name: str, pat: str) -> bool:
     `router/context_test.go` and never `context_test.go`. Gin keeps its tests
     beside the code they test, so three of its four "production" secrets were
     test fixtures at the repository root, and that alone held it at F.
+
+    **The `**/` strip has to happen on the directory branch too.** It did not,
+    and so `**/__pycache__/` matched *nothing*: the branch searched for a
+    literal `/**/__pycache__/` inside the path, and no real path contains
+    `/**/`. A bare `__pycache__/` already matches at any depth, so the two
+    spellings differed by everything — one worked and the one this
+    repository's own config used was inert. `.pyc` files were scanned as
+    source the whole time, and CI caught it only because a compiled test
+    fixture tripped a secrets rule.
+
+    An inert exclude pattern is the worst kind of configuration defect: it
+    reads as intent, it never errors, and the only symptom is findings the
+    operator believed they had excluded.
     """
     if pat.endswith("/"):
-        return rel.startswith(pat) or f"/{pat}" in f"/{rel}/"
+        bare = pat[3:] if pat.startswith("**/") else pat
+        if not bare:  # a lone `**/` would otherwise exclude the entire tree
+            return False
+        return rel.startswith(bare) or f"/{bare}" in f"/{rel}/"
     bare = pat[3:] if pat.startswith("**/") else pat
     return fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(rel, bare) or fnmatch.fnmatch(name, bare)
 
@@ -97,8 +113,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 +123,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 +137,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 +163,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.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/pillar.py

@@ -5,6 +5,41 @@ declares Security a `DELEGATED` pillar naming this tool, and reports it as
 `NotApplicable` so a reader never mistakes silence for safety. This module is
 the other half: the thing that makes that entry unnecessary.
 
+**Changing this document's shape is a two-repository release, in order.**
+
+MA refuses an unknown `schema` or `schema_version` outright and reports no
+delegated pillar rather than a partial one — deliberately, because "the schema
+string is the producer's promise about the shape, and guessing past it is how
+a consumer starts reporting fields that mean something different." That is the
+safe failure and a *silent* one.
+
+So a schema bump ships in this sequence and no other:
+
+1. specify the new shape and send it to MA;
+2. **MA lands its reader first**, accepting the old version and the new;
+3. only then does this tool emit the new version.
+
+Emitting first leaves the pillar unmeasured for the entire window between the
+two releases, with nothing on either side reporting why. MA will not
+pre-accept an unspecified shape, which is correct for the same reason this
+rule exists. Agreed with the MA maintainer 2026-09-11; see D18, D19 and MA's
+D155.
+
+**v2 is live and was cut this way.** It is v1 plus one field, `scoring_model`
+— every v1 key keeps its name, type and meaning. MA's reader accepts v1 and
+v2 and keys its trend on `scoring_model` when present, falling back to the
+producer version when absent, so its reader could land before this tool
+emitted anything and no document was ever refused.
+
+**`scoring_model` is load-bearing and is not ours alone.** MA keys trend
+comparability on it, because a delegated pillar can change its scoring model
+without changing its schema — which is exactly what D16 and D17 did. A wrong
+value here silently splices two scoring models into one trend and presents it
+as knowledge, so `tests/integration/test_scoring_drift.py` digests the weights,
+the bands and the real `score()` output and fails when the model moves without
+the integer. `producer.version` remains pinned to `__version__` for the same
+reason, since it is still the key for any v1 document.
+
 **Everything structural here is MA's and is reused deliberately.** The scope
 vocabulary, the two-axis split, the posture matrix and its thresholds all come
 from `_pillars.py`. Two tools reporting "level 3" or "healthy" about the same
@@ -41,7 +76,7 @@ from typing import Any
 from secure_code_audit import __version__
 from secure_code_audit.practice import PracticeLevel
 from secure_code_audit.scanner_status import CoverageReport, CoverageStatus
-from secure_code_audit.scoring import AxisReport, ScoreReport, Verdict
+from secure_code_audit.scoring import SCORING_MODEL, AxisReport, ScoreReport, Verdict
 
 #: MA's matrix thresholds, imported by value because the two tools must agree
 #: on where the cells fall. `_pillars.py` holds the originals.
@@ -151,8 +186,24 @@ def to_dict(pillar: SecurityPillar) -> dict[str, Any]:
     """The document MA reads. Both axes present, their mean absent."""
     return {
         "schema": "secure-code-agent/security-pillar",
-        "schema_version": 1,
+        # v2 = v1 plus `scoring_model`. Nothing else moved: every v1 key keeps
+        # its name, its type and its meaning.
+        "schema_version": 2,
         "producer": {"tool": "secure-code-agent", "version": __version__},
+        # Which scoring model produced `condition`, for a consumer keeping a
+        # trend. Deliberately top-level rather than inside `producer`:
+        # `producer` says *who*, this says *what model*, and a consumer keying
+        # on it should not have to reach through an identity block.
+        #
+        # An integer, not a version string, because the only question is "same
+        # or different" — an integer cannot be padded, or compared as text, or
+        # read as ordering that means more than it does.
+        #
+        # MA keyed this on our release version before, which is correct and far
+        # too broad: a new series opened on every release, including ones that
+        # changed no scoring, and a signal that fires constantly teaches people
+        # to ignore it.
+        "scoring_model": SCORING_MODEL,
         "generated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
         "pillar": "security",
         "scope": SCOPE,

{secure_code_agent-0.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/scoring.py

@@ -3,8 +3,8 @@
 Implements the model documented in docs/scoring.md:
   · finding_score = severity × confidence × category × top25_bonus
   · category_subtotal = Σ finding_score per category
-  · category_normalized = subtotal / sqrt(LOC / 1000)
-  · category_grade = clamp(5.0 - (normalized × 0.5), 0, 5)
+  · category_normalized = subtotal / (LOC / 1000)
+  · category_grade = clamp(5.0 - (normalized × 1.5), 0, 5)
   · overall = min(category_grades)
 """
 
@@ -48,6 +48,43 @@ CATEGORY_WEIGHT: dict[Category, float] = {
 
 CWE_TOP25_BONUS = 1.25
 
+#: Which scoring model produced a number, for consumers that keep a trend.
+#:
+#: `maintainability-agent` stores this tool's `condition` in its scan history
+#: and has to know when two readings are comparable. A delegated pillar can
+#: change its scoring model **without changing its schema** — same shape, same
+#: fields, a different number for the same repository — which is exactly what
+#: D16 and D17 did. MA previously keyed on our release version, which is
+#: correct but far too broad: it opened a new series on every release,
+#: including ones that changed no scoring, and a signal that fires constantly
+#: teaches people to ignore it.
+#:
+#: **Bump this when a repository's condition could differ for a reason that is
+#: not the repository.** Concretely: the normalizer, the grade slope, any
+#: weight table, the letter bands, the rank discount, `COUNT_LIKE_CATEGORIES`,
+#: the scanner floor, or the built-in rule profile (D10).
+#:
+#: **Do not bump for** documentation, adapters, CLI flags, output formats,
+#: performance, or a parser fix that does not change which findings are
+#: produced.
+#:
+#: A new *rule* does bump it. That was the arguable case and it resolves
+#: against intuition: a repository containing `yaml.unsafe_load` scores lower
+#: the day that rule ships, with no change to the repository. Adding findings
+#: *is* rescoring, because the score is a function of the finding set, and a
+#: user must not read "we can see more now" as "your code got worse".
+#:
+#: **1 is reserved and is never emitted.** It denotes every release before
+#: this field existed, and those releases do not share one model — the
+#: corroboration merge, the rank discount and D16 all moved the numbers. A v1
+#: document simply omits the field and MA keys those on the release version,
+#: which fragments them correctly. Nothing may back-fill a 1.
+#:
+#: `tests/integration/test_scoring_drift.py` holds this honest: it digests the
+#: weights, the bands and the output of the real `score()` over a fixed
+#: matrix, so changing a constant *or* a formula without bumping this fails.
+SCORING_MODEL = 2
+
 
 # --- letter-grade boundaries (mirrors maintainability-agent) ---------------
 
@@ -173,7 +210,7 @@ def category_subtotal(findings: Iterable[Finding], category: Category) -> float:
 
     A straight sum measures how many times a pattern matched, and that
     tracks codebase size times how talkative the scanner is — not how much
-    risk is in the code. `sqrt(LOC)` was meant to cancel the size half.
+    risk is in the code. The normalizer was meant to cancel the size half.
     Nothing cancelled the other half, and the corpus said so plainly: the
     worst-first ordering read Python → JavaScript → Go/Ruby → Java, which is
     the order of Bandit's verbosity, and Django, FastAPI, httpx and Flask all
@@ -216,15 +253,111 @@ def category_subtotal(findings: Iterable[Finding], category: Category) -> float:
     )
 
 
-def normalize(subtotal: float, loc_scanned: int) -> float:
-    """sqrt(LOC/1000) dampener — see docs/scoring.md for the rationale."""
+#: Categories where a finding is a count rather than a rate.
+#:
+#: One committed credential is one committed credential regardless of how
+#: much code surrounds it. Everything else here — injection sinks, weak
+#: crypto calls, unsafe deserialization — genuinely does scale with how much
+#: code there is, and comparing two repositories on those means comparing
+#: rates. See `normalize` for the measurement that settled which is which.
+COUNT_LIKE_CATEGORIES: frozenset[str] = frozenset({"secrets"})
+
+
+def _category_name(category: Category | str) -> str:
+    return category.value if isinstance(category, Category) else str(category)
+
+
+def normalize(subtotal: float, loc_scanned: int, category: Category | str | None = None) -> float:
+    """Weighted findings per thousand lines of scanned code — a density.
+
+    This was `sqrt(LOC/1000)` and that under-corrected for size, so the
+    ranking followed how *big* a repository is rather than how much is wrong
+    with it. Measured across the examined corpus:
+
+        repo      LOC        weighted findings/kLOC   sqrt-normalized
+        django    144,473    1.51                     18.18  <- ranked worst
+        flask       7,841    3.35                      9.38
+        fastapi    23,764    1.60                      7.81
+
+    Flask carries **2.2x Django's finding density** and normalised at half
+    the value. Django sat fifth by density and first by penalty. Spearman
+    correlation of grade against size was -0.37 while correlation of density
+    against size was +0.12: the number was tracking the wrong variable.
+
+    Straight density fixes the ordering: re-measured over the same corpus
+    after the change, Spearman(LOC, grade) is +0.02, and the worst-ranked
+    repository is the densest one rather than the largest one. The slope
+    moves with it — see `category_grade` — because the two only make sense
+    together.
+
+    **`secrets` is not a density, and D17 is why.** Adding
+    vulnerable-by-design anchors to the corpus exposed the failure directly:
+    OWASP Juice Shop carries four hardcoded API keys and three private keys
+    and graded **B+**, because 115,340 lines of surrounding code divided
+    seven committed credentials down to nothing. Meanwhile Flask, with no
+    secrets at all, graded F. A committed private key is one committed
+    private key whether the repository is a thousand lines or a million; it
+    is a count, not a rate, and dividing it by size is how a training
+    application built to be insecure outscored a well-run library.
+
+    So `secrets` normalizes by `sqrt(LOC/1000)` instead. Not by nothing: a
+    larger codebase genuinely does carry more configuration surface, and an
+    absolute count made Django fail on two low-confidence hits. Measured over
+    the fourteen examined repositories, against whether a repository is
+    maintained or written to be vulnerable:
+
+        variant                       AUC    separation   Spearman(LOC, grade)
+        linear everywhere (D16)       0.80      -3.76            +0.14
+        sqrt everywhere (pre-D16)     0.91      -0.58            -0.32
+        linear; secrets absolute      0.90      +0.00            -0.24
+        linear; secrets sqrt          1.00      +0.65            -0.01   <-
+
+    AUC is the probability that a maintained repository outscores a
+    vulnerable-by-design one. Negative separation means the populations
+    overlap and *no* band table can tell them apart — which is what blocked
+    D5's band edges for as long as the corpus had no bad end in it.
+    """
     if loc_scanned <= 0:
         return subtotal
-    return subtotal / math.sqrt(max(loc_scanned, 1) / 1000)
+    per_kloc = max(loc_scanned, 1) / 1000
+    if category is not None and _category_name(category) in COUNT_LIKE_CATEGORIES:
+        return subtotal / math.sqrt(per_kloc)
+    return subtotal / per_kloc
+
+
+#: Grade points lost per normalized weighted finding.
+#:
+#: The slope only rescales — it cannot reorder anything — so it is chosen
+#: against two things the ordering does not fix: where the median of
+#: well-maintained code lands, and how much of the corpus clamps at 0.0 and
+#: loses its tail.
+#:
+#: 1.3 is the largest slope that keeps the maintained-corpus median inside the
+#: B band [3.00, 3.50) *and* keeps the two populations from touching. Measured
+#: across the range, holding the D17 normalizer fixed:
+#:
+#:     slope   median (maintained)   AUC   separation   clamped at 0
+#:      1.2          3.53 (B+)       1.00     +0.98          4
+#:      1.3          3.41 (B)        1.00     +0.65          4   <- adopted
+#:      1.4          3.28 (B)        1.00     +0.31          4
+#:      1.5          3.16 (B)        0.95     +0.00          5
+#:
+#: At 1.5 a maintained repository joins the four vulnerable-by-design ones at
+#: the clamp, the populations touch, and AUC falls. 1.3 has the widest margin
+#: of the slopes that land the median in B.
+#:
+#: The cost, stated: a large repository with a handful of serious findings
+#: still scores better than a small noisy one. A 135,841-line control carrying
+#: SQL injection, `shell=True`, `pickle.loads`, MD5 and `eval` grades in the
+#: A band. What protects that repository is the default `fail_on_new` gate,
+#: which fails it outright, and the work order, which puts all seven findings
+#: in §FIX. A grade is for comparing and for trend; it was never the thing
+#: that catches a vulnerability. See D16 and D17.
+GRADE_SLOPE = 1.3
 
 
 def category_grade(normalized: float) -> float:
-    return max(0.0, min(5.0, 5.0 - (normalized * 0.5)))
+    return max(0.0, min(5.0, 5.0 - (normalized * GRADE_SLOPE)))
 
 
 # --- overall score ---------------------------------------------------------
@@ -520,7 +653,7 @@ def score(
             per_category[cat] = None
             continue
         subtotal = category_subtotal(findings, cat)
-        per_category[cat] = category_grade(normalize(subtotal, loc_scanned))
+        per_category[cat] = category_grade(normalize(subtotal, loc_scanned, cat))
 
     for f in findings:
         if not f.suppressed:
@@ -691,7 +824,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(

{secure_code_agent-0.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/standards.py

@@ -95,8 +95,19 @@ class StandardsEntry:
 _MAP: dict[tuple[str, str], StandardsEntry] = {
     # ----- Bandit ----------------------------------------------------------
     # Source: https://bandit.readthedocs.io/en/latest/plugins/index.html
+    # B102 read CWE-78 — *OS* command injection, the shell-injection weakness
+    # that B602/B603/B605/B607 cover. `exec()` does not invoke a shell; it
+    # compiles and runs Python. The mislabel travelled: into the OWASP
+    # mapping, into SARIF, into the work order, and into the Top-25 bonus,
+    # which CWE-78 carries and the true weakness does not directly.
+    #
+    # It also broke corroboration, which is how it was found. Bandit's B102
+    # and our own `sca.python.eval` fire on the same `exec(compile(...))`
+    # line in Flask's `config.py`; `_same_weakness` merges across scanners on
+    # a shared CWE, CWE-78 and CWE-95 are not shared, so one defect scored
+    # twice. Flask carried four such pairs and graded F partly on doubles.
     ("bandit", "B102"): StandardsEntry(
-        canonical_cwe="CWE-78",
+        canonical_cwe="CWE-95",
         owasp_top10="A03",
         asvs_section="V5.3.8",
         nist_ssdf="PW.5.1",
@@ -106,6 +117,20 @@ _MAP: dict[tuple[str, str], StandardsEntry] = {
         short_desc="Use of exec() — arbitrary code execution risk.",
         fix_hint="Eliminate exec() entirely. If dynamic dispatch is required, use a typed registry / function map.",
     ),
+    # B307 (`eval`) had no curated entry, so `_make_finding` fell back to the
+    # CWE the scanner reports — and Bandit files `eval` under CWE-78 too. Same
+    # weakness as B102, same fix, and curating it is what stops the fallback.
+    ("bandit", "B307"): StandardsEntry(
+        canonical_cwe="CWE-95",
+        owasp_top10="A03",
+        asvs_section="V5.2.4",
+        nist_ssdf="PW.5.1",
+        category=Category.CODE_VULNERABILITIES,
+        severity=Severity.HIGH,
+        confidence=Confidence.MEDIUM,
+        short_desc="Use of eval() — arbitrary code execution risk.",
+        fix_hint="Use ast.literal_eval for data. For dispatch, use a dict of callables rather than evaluating a name.",
+    ),
     ("bandit", "B301"): StandardsEntry(
         canonical_cwe="CWE-502",
         owasp_top10="A08",
@@ -494,9 +519,41 @@ def lookup(scanner: str, rule_id: str) -> StandardsEntry | None:
     return _MAP.get((scanner.lower(), "*"))
 
 
+#: Child CWEs this project maps to, and the Top-25 entry each is a ChildOf.
+#:
+#: The Top-25 list names classes, and a scanner names the specific weakness
+#: inside one. CWE-95 ("Eval Injection") is a documented ChildOf CWE-94
+#: ("Improper Control of Generation of Code"), which is on the list — so a
+#: confirmed eval injection *is* a Top-25 weakness, and a membership test
+#: that only compares strings says it is not.
+#:
+#: This is deliberately a hand-checked handful rather than an imported CWE
+#: hierarchy. Every entry is a relationship stated in the MITRE definition of
+#: the child, and each is used by a rule this project actually maps. Adding a
+#: parent here widens the 1.25x bonus, so it is a decision, not a lookup.
+_TOP25_PARENT: dict[str, str] = {
+    # cwe.mitre.org/data/definitions/95.html — ChildOf 94
+    "CWE-95": "CWE-94",
+    # cwe.mitre.org/data/definitions/77.html is itself on the list; 78 is the
+    # OS-command child and is also listed, so neither needs an entry here.
+}
+
+
 def is_top25(canonical_cwe: str | None) -> bool:
-    """Is this CWE on the MITRE Top 25 (2025) list? Used for scoring boost."""
-    return canonical_cwe is not None and canonical_cwe in CWE_TOP25_2025
+    """Is this CWE on the MITRE Top 25 (2025) list, directly or as a child?
+
+    Correcting Bandit's B102/B307 from CWE-78 to CWE-95 was right on the
+    weakness and would have quietly removed the Top-25 bonus from every
+    eval/exec finding in the corpus — CWE-78 is on the list and CWE-95 is
+    not. Losing the bonus for the *reason* "we now describe the weakness
+    accurately" is the wrong trade, and CWE-95 is a child of CWE-94, which
+    is listed. So membership follows the relationship.
+    """
+    if canonical_cwe is None:
+        return False
+    if canonical_cwe in CWE_TOP25_2025:
+        return True
+    return _TOP25_PARENT.get(canonical_cwe, "") in CWE_TOP25_2025
 
 
 def cwe_url(canonical_cwe: str) -> str:

{secure_code_agent-0.8.0 → secure_code_agent-0.10.0}/src/secure_code_audit/triage.py

@@ -29,7 +29,7 @@ import enum
 import re
 from collections.abc import Iterable
 
-from secure_code_audit.findings import Confidence, Finding, Severity
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
 
 
 class Tier(enum.Enum):
@@ -104,6 +104,123 @@ def _looks_like_a_credential(message: str) -> bool:
     return len(value) >= 12 and any(c.isdigit() for c in value) and any(c.isupper() for c in value)
 
 
+#: A credential *reference* — a name standing in for a value that is not here.
+#:
+#: Shell (`$TOKEN`, `${TOKEN}`), GitHub Actions (`${{ secrets.X }}`,
+#: `${{ env.X }}`), Windows (`%TOKEN%`), and the ordinary code spellings.
+_VARIABLE_REFERENCE = re.compile(
+    r"""
+      \$\{\{\s*(?:secrets|env|vars)\.        # ${{ secrets.NAME }}
+    | \$\{[A-Za-z_][A-Za-z0-9_]*            # ${NAME}
+    | \$[A-Za-z_][A-Za-z0-9_]*              # $NAME
+    | %[A-Za-z_][A-Za-z0-9_]*%              # %NAME%
+    | os\.environ | os\.getenv              # Python
+    | process\.env\.                        # Node
+    | ENV\[                                 # Ruby
+    """,
+    re.VERBOSE,
+)
+
+#: A URL, stripped before looking for a literal credential.
+#:
+#: This is not cosmetic. The first version of the literal test matched
+#: `//sonarcloud` inside `https://sonarcloud.io/api` — twelve characters of
+#: `[A-Za-z0-9+/_-]`, because `/` and `+` are base64 alphabet and a URL is
+#: full of them. Every `curl` line has a URL on it, so the demotion never
+#: fired on the exact case it was written for.
+_URL = re.compile(r"\bhttps?://\S+", re.IGNORECASE)
+
+#: A literal that could itself be the credential, sitting on the same line.
+_LITERAL_RUN = re.compile(r"[A-Za-z0-9+/_\-]{12,}")
+
+
+def _contains_a_literal_credential(text: str) -> bool:
+    """Twelve-plus characters with a digit and an uppercase letter.
+
+    Deliberately the same dull test `_looks_like_a_credential` applies to
+    Bandit's quoted values — same shape, same reasons, and it keeps the two
+    heuristics from drifting into disagreement about what a secret looks
+    like.
+
+    **Known miss, stated:** an all-lowercase hex token such as
+    `a3f9c2b1d4e5` has no uppercase letter and is not caught. That costs a
+    demotion from FIX to REVIEW, and only on a line that *also* carries a
+    variable reference, which is an odd thing to write. The finding still
+    appears in the work order, still appears in the report, and still
+    escalates through `fail_on_category`. The error falls in the safe
+    direction.
+    """
+    for run in _LITERAL_RUN.findall(_URL.sub(" ", text)):
+        if any(c.isdigit() for c in run) and any(c.isupper() for c in run):
+            return True
+    return False
+
+
+def _line_of(finding: Finding) -> str | None:
+    """Read back the source line a secrets finding points at.
+
+    Gitleaks is run with `--redact`, so the matched text never reaches the
+    report — the message reads `curl -sS -u REDACTED`, and the variable name
+    is precisely what was redacted. The only way to tell a reference from a
+    value is to look at the line, the way `verify._is_silenced` does.
+
+    Returns None whenever the line cannot be read with confidence: the file
+    is gone, the path is a directory, the line number is out of range, or the
+    finding came out of git history and the working tree has moved on. Every
+    one of those must leave the finding where it was.
+    """
+    path = finding.file_path
+    if path is None or finding.line_start is None or finding.line_start < 1:
+        return None
+    try:
+        if not path.is_file():
+            return None
+        with path.open("r", encoding="utf-8", errors="replace") as handle:
+            for number, line in enumerate(handle, 1):
+                if number == finding.line_start:
+                    return line
+                if number > finding.line_start:
+                    break
+    except OSError:
+        return None
+    return None
+
+
+def _is_a_reference_not_a_value(finding: Finding) -> bool:
+    """Is the flagged credential a variable name rather than a credential?
+
+    `gitleaks.curl-auth-user` fires CRITICAL on
+    `curl -sS -u "$SONAR_TOKEN:"` in a GitHub Actions workflow. No credential
+    is present; `$SONAR_TOKEN` is how you write *not* putting one there, and
+    the idiom is the recommended one. Reported independently on two
+    repositories on the same day, five occurrences on one of them.
+
+    This matters more than it used to. D17 made `secrets` count-like — it
+    normalizes by `sqrt(LOC/1000)` rather than by size — so a single false
+    critical now costs roughly two grade points on a 100k-line repository
+    where it previously cost two tenths. Raising the weight of a category
+    raises the cost of being wrong in it, and this is the corresponding
+    precision work.
+
+    Conservative in both directions. It demotes to REVIEW, never to ACCEPT:
+    the finding stays in the work order, stays in the report, and still
+    escalates through `fail_on_category: [secrets]` from any axis. And it
+    declines to act unless it can read the line and finds no literal token on
+    it, so `curl -u "$USER:hunter2Passw0rd"` is untouched.
+    """
+    if finding.category is not Category.SECRETS:
+        return False
+    line = _line_of(finding)
+    if line is None:
+        return False
+    if not _VARIABLE_REFERENCE.search(line):
+        return False
+    # A reference and a literal on one line is still a leak. Strip the
+    # references first so their own names cannot satisfy the literal test.
+    without_references = _VARIABLE_REFERENCE.sub(" ", line)
+    return not _contains_a_literal_credential(without_references)
+
+
 def tier_of(finding: Finding, axis: str = "primary") -> Tier:
     """Classify one finding.
 
@@ -118,6 +235,8 @@ def tier_of(finding: Finding, axis: str = "primary") -> Tier:
         if _looks_like_a_credential(finding.message):
             return Tier.FIX
         return Tier.REVIEW
+    if _is_a_reference_not_a_value(finding):
+        return Tier.REVIEW
     if finding.confidence is Confidence.LOW:
         return Tier.REVIEW
     return Tier.FIX
@@ -128,6 +247,15 @@ def reason_for(finding: Finding) -> str | None:
     measured = LOW_PRECISION.get(finding.rule_id)
     if measured:
         return measured
+    if _is_a_reference_not_a_value(finding):
+        return (
+            "The line holds a variable reference, not a credential — a name "
+            "standing in for a value kept elsewhere, which is the recommended "
+            "way to write this. Checked by reading the line back, because "
+            "gitleaks runs with --redact and the redacted text is the "
+            "variable name itself. Confirm the value really is injected at "
+            "runtime, then suppress it."
+        )
     if finding.confidence is Confidence.LOW:
         return (
             f"{finding.scanner} reported this at low confidence — it is "