secure-code-agent 0.12.12__tar.gz → 0.13.1__tar.gz

{secure_code_agent-0.12.12/src/secure_code_agent.egg-info → secure_code_agent-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.12
+Version: 0.13.1
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -49,6 +49,8 @@ Dynamic: license-file
 
 # secure-code-agent
 
+![secure-code-agent — a deterministic security gate whose findings become a bounded remediation work order for your AI coding agent](https://raw.githubusercontent.com/marshallguillory86/secure-code-agent/main/docs/brand/sca.png)
+
 > **Deterministic security gate + bounded AI remediation prompts for repos with AI coding agents in the loop.**
 > Anchored to NIST SSDF · OWASP ASVS · OWASP Top 10 · MITRE CWE Top 25 · OpenSSF Scorecard · SARIF 2.1.0.
 
@@ -554,7 +556,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.12
+- uses: marshallguillory86/secure-code-agent@v0.13.1
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/README.md

@@ -1,5 +1,7 @@
 # secure-code-agent
 
+![secure-code-agent — a deterministic security gate whose findings become a bounded remediation work order for your AI coding agent](https://raw.githubusercontent.com/marshallguillory86/secure-code-agent/main/docs/brand/sca.png)
+
 > **Deterministic security gate + bounded AI remediation prompts for repos with AI coding agents in the loop.**
 > Anchored to NIST SSDF · OWASP ASVS · OWASP Top 10 · MITRE CWE Top 25 · OpenSSF Scorecard · SARIF 2.1.0.
 
@@ -505,7 +507,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.12
+- uses: marshallguillory86/secure-code-agent@v0.13.1
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.12
+Version: 0.13.1
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -49,6 +49,8 @@ Dynamic: license-file
 
 # secure-code-agent
 
+![secure-code-agent — a deterministic security gate whose findings become a bounded remediation work order for your AI coding agent](https://raw.githubusercontent.com/marshallguillory86/secure-code-agent/main/docs/brand/sca.png)
+
 > **Deterministic security gate + bounded AI remediation prompts for repos with AI coding agents in the loop.**
 > Anchored to NIST SSDF · OWASP ASVS · OWASP Top 10 · MITRE CWE Top 25 · OpenSSF Scorecard · SARIF 2.1.0.
 
@@ -554,7 +556,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.12
+- uses: marshallguillory86/secure-code-agent@v0.13.1
   with:
     config: secure-code-agent.json
     fail-on-gate: true

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/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.12"
+__version__ = "0.13.1"

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/cli.py

@@ -44,13 +44,20 @@ from secure_code_audit.findings import (
     anchor,
     merge_corroborating,
 )
-from secure_code_audit.git_tools import find_repo_root, is_excluded, is_test_path, loc_under
+from secure_code_audit.git_tools import (
+    extensions_under,
+    find_repo_root,
+    is_excluded,
+    is_test_path,
+    loc_under,
+)
 from secure_code_audit.scanner_status import (
     COVERING_OUTCOMES,
     ScannerExecution,
     ScannerOutcome,
     evaluate_coverage,
     execution_from_result,
+    languages_for,
 )
 from secure_code_audit.scanners import floor
 from secure_code_audit.scoring import (
@@ -622,7 +629,27 @@ def _score_everything(
         ),
         *(execution.name for execution in imported_executions),
     ]
-    coverage = evaluate_coverage(executions, required)
+    # The languages the *scored* tree actually contains, so COMPLETE can mean
+    # "this tree was covered" rather than "every configured scanner ran".
+    # `gin` — 7,146 lines of Go — reported COMPLETE and `code_vulnerabilities:
+    # 5.0` while bandit, njsscan and rubocop found nothing in Go source and
+    # gosec was not in the run. P7's own falsification condition.
+    #
+    # Scoped exactly as the scoring denominator is, which is why it is
+    # `extensions_under` and not `_repository_inventory`: the broad inventory
+    # answers "is there any Go here at all" for applicability, and a Go fixture
+    # under `tests/` must not oblige a Python project to install gosec.
+    primary_languages = languages_for(
+        extensions_under(
+            target,
+            cfg.include_extensions,
+            cfg.exclude_patterns,
+            cfg.test_patterns,
+            own_artifacts,
+            cfg.docs_patterns,
+        )
+    )
+    coverage = evaluate_coverage(executions, required, primary_languages)
     # Gates see the dependency advisories; the score does not.
     # 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

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/git_tools.py

@@ -229,6 +229,47 @@ def loc_under(
     return primary, test, docs
 
 
+def extensions_under(
+    root: Path,
+    include_exts: Iterable[str],
+    excludes: Iterable[str],
+    test_patterns: Iterable[str] = (),
+    skip: Iterable[Path] = (),
+    docs_patterns: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """The file extensions of the **primary** tree, sorted.
+
+    The input to coverage's question "was this tree covered". Scoped exactly
+    as `loc_under`'s primary count is, and for the same reason: a claim about
+    coverage has to describe the tree the score describes.
+
+    Primary only. A Go fixture under `tests/` does not oblige a Python
+    project to install `gosec` — the test tree is reported and not scored, so
+    a language appearing only there cannot make the score unsupported.
+    """
+    test_patterns = tuple(test_patterns)
+    docs_patterns = tuple(docs_patterns)
+    skip = {path.resolve() for path in skip}
+    found: set[str] = set()
+    # `rglob` on a file yields nothing, the same case `loc_under` documents.
+    candidates = root.rglob("*") if root.is_dir() else [root]
+    for path in candidates:
+        if not path.is_file():
+            continue
+        if path.resolve() in skip:
+            continue
+        if is_excluded(path, root, excludes):
+            continue
+        if not in_scope(path, include_exts):
+            continue
+        if test_patterns and is_test_path(path, root, test_patterns):
+            continue
+        if docs_patterns and is_test_path(path, root, docs_patterns):
+            continue
+        found.add(path.suffix)
+    return tuple(sorted(found))
+
+
 def _git() -> str | None:
     """Resolve `git` to an absolute path, once.
 

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/renderers.py

@@ -137,6 +137,10 @@ def _coverage_to_dict(coverage: CoverageReport | None) -> dict | None:
         "required": list(coverage.required),
         "unverified": list(coverage.unverified),
         "failures": list(coverage.failures),
+        # Languages the scored tree contains that nothing in the run reads.
+        # Carried here because MA's security pillar and any other machine
+        # consumer needs to know the grade's breadth, not just its value.
+        "unread_languages": list(coverage.unread_languages),
         "scanners": [
             {
                 "name": execution.name,
@@ -305,6 +309,13 @@ def _summary_section(
     out = ["## Summary", ""]
     if coverage is not None:
         out.append(f"- **Scanner coverage:** {coverage.status.value.upper()}")
+        # The language *and* the remedy, in the summary rather than only in
+        # the scanners section. "scanner coverage is partial" tells a reader
+        # that something is missing, not what — the same half-answer that
+        # said `did not complete: failed` while trivy's 429 and its fix sat
+        # one field away in the same record.
+        for entry in coverage.unread_languages:
+            out.append(f"- **Language not covered:** {entry}")
     # No verdict means nobody decided this run could claim a grade, so it
     # cannot. Falling back to a locally-invented condition here is what put a
     # second decision rule in the codebase in the first place.
@@ -421,6 +432,8 @@ def _scanners_section(
         out.append(f"- Coverage: **{coverage.status.value.upper()}**")
         if coverage.required:
             out.append(f"- Required: {', '.join(coverage.required)}")
+        for entry in coverage.unread_languages:
+            out.append(f"- Not read by any scanner that ran: {entry}")
         if coverage.unverified:
             out.append(
                 f"- Unverified (imported artifact, execution not observed): "

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/sarif.py

@@ -13,8 +13,8 @@ from pathlib import Path
 from secure_code_audit import __version__
 from secure_code_audit.findings import Category, Confidence, Finding, Severity
 from secure_code_audit.scanner_status import (
+    COVERING_OUTCOMES,
     CoverageReport,
-    CoverageStatus,
     ScannerExecution,
     ScannerOutcome,
 )
@@ -92,8 +92,20 @@ def emit(
 
 
 def _invocation(coverage: CoverageReport) -> dict:
+    """The run, and what it covered, on two separate axes.
+
+    `executionSuccessful` says whether this tool ran to completion, and a
+    document is only written when it did. It was set from coverage instead,
+    so `maintainability-agent` — every scanner completed, PARTIAL only because
+    nothing in the floor reads shell — uploaded "unsuccessful tool execution,
+    exit code 0" on every run, and GitHub code scanning put a configuration
+    error banner on its Security overview. Coverage stays in
+    `properties.coverageStatus`, and each gap is a notification naming what
+    was not read: `error` for a required scanner that broke the gate,
+    `warning` for a limit of the floor.
+    """
     invocation = {
-        "executionSuccessful": coverage.status is CoverageStatus.COMPLETE,
+        "executionSuccessful": True,
         "properties": {
             "coverageStatus": coverage.status.value,
             "requiredScanners": list(coverage.required),
@@ -108,18 +120,30 @@ def _invocation(coverage: CoverageReport) -> dict:
             ],
         },
     }
-    if coverage.failures:
-        invocation["toolExecutionNotifications"] = [
-            {
-                "level": "error",
-                "message": {"text": failure},
-                "descriptor": {"id": "scanner-coverage"},
-            }
-            for failure in coverage.failures
-        ]
+    notifications = [_coverage_notification("error", failure) for failure in coverage.failures]
+    notifications += [
+        _coverage_notification("warning", f"language not covered: {entry}")
+        for entry in coverage.unread_languages
+    ]
+    notifications += [
+        _coverage_notification(
+            "warning",
+            f"scanner {execution.name!r} did not complete: {execution.outcome.value}"
+            + (f" — {execution.reason}" if execution.reason else ""),
+        )
+        for execution in coverage.executions
+        if execution.name not in coverage.required
+        and execution.outcome not in (*COVERING_OUTCOMES, ScannerOutcome.NOT_APPLICABLE)
+    ]
+    if notifications:
+        invocation["toolExecutionNotifications"] = notifications
     return invocation
 
 
+def _coverage_notification(level: str, text: str) -> dict:
+    return {"level": level, "message": {"text": text}, "descriptor": {"id": "scanner-coverage"}}
+
+
 def _rule(f: Finding) -> dict:
     rule: dict = {
         "id": f.rule_id,

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/scanner_status.py

@@ -91,6 +91,12 @@ class CoverageReport:
     #: than a process we watched. Reported everywhere so COMPLETE is never
     #: read as "we verified all of this ourselves".
     unverified: tuple[str, ...] = ()
+    #: Languages present in the tree that nothing in this run reads for code
+    #: vulnerabilities. Separate from `failures` on purpose: a required
+    #: scanner that did not run broke a promise the operator made and fails
+    #: the gate, while an unread language is a limit of the floor and
+    #: withholds the verified grade instead.
+    unread_languages: tuple[str, ...] = ()
 
 
 def execution_from_result(
@@ -150,10 +156,115 @@ def worst_by_name(
     return by_name
 
 
+#: Which scanners in this floor actually read a language for *code* defects.
+#:
+#: **Verified by running them, not adopted from anywhere.** An earlier version
+#: of this lifted `calibration/calibrate.py`'s `LANGUAGE_SCANNERS` wholesale
+#: and was wrong, because that map answers a different question: the study
+#: fixes its scanner set and uses "did the *dedicated* language scanner run"
+#: as a proxy for coverage depth. Read as "what reads this language at all" it
+#: asserts things that are false — that nothing reads Go without `gosec`
+#: (semgrep's offline profile carries five Go rules, and they fire), and that
+#: nothing reads Python without `bandit` (`builtin_rules` is Python-only and
+#: found the findings in the very fixture that caught this).
+#:
+#: So this lists every scanner that genuinely reads the language, and a
+#: language is flagged only when **nothing** read it. That is a weaker claim
+#: than the study's and it is the one that is true.
+#:
+#: The depth question the study is really asking — "five generic rules is a
+#: floor, not coverage" — is deliberately *not* answered here. `COMPLETE` and
+#: `PARTIAL` cannot express it, and inventing a third state is a product
+#: decision rather than a bug fix.
+LANGUAGE_SCANNERS: dict[str, tuple[str, ...]] = {
+    # `builtin_rules` is Python-only; semgrep's offline profile adds two more.
+    "python": ("bandit", "semgrep", "builtin_rules"),
+    "javascript": ("njsscan", "semgrep"),
+    "typescript": ("njsscan", "semgrep"),
+    "ruby": ("rubocop", "semgrep"),
+    # No dedicated Go scanner in the floor, but the offline profile's five Go
+    # rules do read it: command injection, weak hash, weak cipher, TLS
+    # verification disabled, weak random. Verified firing on the shipped Go
+    # fixture.
+    "go": ("gosec", "semgrep"),
+    # Likewise Java: five offline rules. D12 is about PMD and SpotBugs not
+    # providing a *dedicated* scanner, which is a statement about depth.
+    "java": ("semgrep",),
+    # Nothing in the floor reads shell for code defects — no entry to name.
+    "shell": (),
+}
+
+
+#: File extension -> the language `LANGUAGE_SCANNERS` keys on.
+#:
+#: Only extensions whose language this floor claims to scan for *code*
+#: defects. `.yaml`, `.json`, `Dockerfile` and `.md` are deliberately absent:
+#: they are covered on other axes by checkov and trivy, and mapping them to a
+#: language would make PARTIAL the permanent state of every repository.
+_EXTENSION_LANGUAGE: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".rb": "ruby",
+    ".go": "go",
+    ".java": "java",
+    ".sh": "shell",
+    ".bash": "shell",
+    ".zsh": "shell",
+}
+
+
+def languages_for(extensions: Iterable[str]) -> tuple[str, ...]:
+    """The code-vulnerability languages these extensions represent, sorted.
+
+    Deduplicated: `.js` and `.mjs` are both JavaScript and the result names it
+    once. An extension with no entry is dropped rather than guessed at.
+    """
+    return tuple(
+        sorted({_EXTENSION_LANGUAGE[ext] for ext in extensions if ext in _EXTENSION_LANGUAGE})
+    )
+
+
+def _unread_languages(languages: Iterable[str], covered_by: set[str]) -> tuple[str, ...]:
+    """Languages present in the tree that no scanner in this run reads.
+
+    `gin` — 7,146 lines of Go — reported `coverage: complete` and
+    `code_vulnerabilities: 5.0` while bandit, njsscan and rubocop found
+    nothing in Go source and `gosec` was not in the run. That is P7's own
+    falsification condition, and COMPLETE was a fact about the scanner list
+    rather than about the tree.
+    """
+    out: list[str] = []
+    for language in dict.fromkeys(languages):
+        readers = LANGUAGE_SCANNERS.get(language)
+        if readers is None:
+            # Not a code-vulnerability language in this floor's terms.
+            continue
+        if any(name in covered_by for name in readers):
+            continue
+        if readers:
+            out.append(f"{language}: no scanner that reads it ran ({', '.join(readers)})")
+        else:
+            # Nothing exists to suggest, so do not invent a name.
+            out.append(f"{language}: no scanner in this floor reads it")
+    return tuple(out)
+
+
 def evaluate_coverage(
     executions: Iterable[ScannerExecution],
     required: Iterable[str],
+    languages: Iterable[str] = (),
 ) -> CoverageReport:
+    """What examined this tree, and whether that was enough to cover it.
+
+    `languages` names the programming languages actually present in the
+    scanned tree. Omitting it keeps the previous behaviour exactly, so every
+    existing call site and every older report keeps its meaning.
+    """
     executions = tuple(executions)
     required = tuple(dict.fromkeys(required))
     by_name = worst_by_name(executions)
@@ -188,8 +299,20 @@ def evaluate_coverage(
         if execution.outcome is ScannerOutcome.UNVERIFIED
     )
 
+    covered_by = {
+        execution.name for execution in by_name.values() if execution.outcome in COVERING_OUTCOMES
+    }
+    unread = _unread_languages(languages, covered_by)
+
     if failures:
         status = CoverageStatus.FAILED
+    elif unread:
+        # PARTIAL, not FAILED. PARTIAL withholds the *verified* grade and
+        # leaves `require_scanners` alone, which is how a partially covered
+        # repository already behaves. FAILED would refuse to audit anything
+        # containing a shell script. An operator who wants the stricter
+        # reading of P7 has `require_scanners` for it.
+        status = CoverageStatus.PARTIAL
     elif any(
         execution.outcome not in (*COVERING_OUTCOMES, ScannerOutcome.NOT_APPLICABLE)
         for execution in executions
@@ -204,4 +327,5 @@ def evaluate_coverage(
         unverified=unverified,
         executions=executions,
         failures=tuple(failures),
+        unread_languages=unread,
     )

{secure_code_agent-0.12.12 → secure_code_agent-0.13.1}/src/secure_code_audit/scoring.py

@@ -723,8 +723,8 @@ def score(
     # one state, and only one of them was closed.
     nothing_scanned = loc_scanned <= 0
     for cat in Category:
-        count = sum(1 for f in findings if f.category == cat and not f.suppressed)
-        per_category_count[cat] = count
+        reported = [f for f in findings if f.category == cat and not f.suppressed]
+        per_category_count[cat] = len(reported)
         # A finding *is* evidence the category was measurable, whatever the
         # scanner inventory says — otherwise a tool reporting outside its
         # declared domain would have its findings graded as unmeasured. The
@@ -732,7 +732,28 @@ def score(
         # on a tree that counted no lines (a credential in a `.env`, a
         # misconfiguration in a bare dotfile — LOC counts only configured
         # source extensions) is still evidence, and is still graded.
-        if count == 0 and (nothing_scanned or cat not in measured):
+        #
+        # But only a finding that could *move* the score is evidence that a
+        # score may be produced. A weightless one cannot: `INFORMATIONAL` is
+        # 0.0 in `SEVERITY_WEIGHT`, so it contributes nothing to the subtotal
+        # and the category grades a perfect 5.0 on the strength of its own
+        # presence.
+        #
+        # That is how the published 0.12.12 wheel reported 5.00/A+ on an empty
+        # tree. A clean install ships no scanners, every adapter emitted its
+        # `{name}.tool_unavailable` notice — POLICY_DOCS, INFORMATIONAL — and
+        # that notice graded its own category, which then became the overall:
+        # `{...all null..., "policy_docs": 5.0}`. D33 was right about scanner
+        # findings and wrong about control findings: a notice saying "this tool
+        # could not run" is evidence of the opposite of examination.
+        #
+        # Deliberately expressed as weight rather than as a list of control
+        # rule ids. `scoring` must not know about the scanner layer (see this
+        # module's own boundary note), the suffixes are four strings that would
+        # drift, and the real property is simply "could this have changed the
+        # number".
+        evidence = sum(1 for f in reported if SEVERITY_WEIGHT[f.severity] > 0.0)
+        if evidence == 0 and (nothing_scanned or cat not in measured):
             per_category[cat] = None
             continue
         subtotal = category_subtotal(findings, cat)