secure-code-agent 0.12.6__tar.gz → 0.12.8__tar.gz

{secure_code_agent-0.12.6/src/secure_code_agent.egg-info → secure_code_agent-0.12.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.6
+Version: 0.12.8
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -60,7 +60,9 @@ secure-code-agent --fail-on-gate \
     --sarif-output secure-code.sarif
 ```
 
-The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Same shape: deterministic CI gate · plain-file outputs · per-host skill bundle. Different concern: security, not maintainability.
+**Runs on its own.** Install it, point it at a repository, get the gate, the report and the work order. Nothing else is required, and most people who use it will use only this.
+
+It is also the sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — same shape (deterministic CI gate · plain-file outputs · per-host skill bundle), different concern — and can feed that tool's Security pillar through [one file](docs/ma-integration.md). That is an integration, not a dependency: a family resemblance, not a component relationship. The two are separate products, installed separately, with their own dependency pins.
 
 ---
 
@@ -513,7 +515,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.6
+- uses: marshallguillory86/secure-code-agent@v0.12.8
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -612,4 +614,4 @@ MIT — see [`LICENSE`](LICENSE).
 
 ---
 
-Built by [Marshall Guillory](https://github.com/marshallguillory86). The companion to [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — both tools encode a single thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*
+Built by [Marshall Guillory](https://github.com/marshallguillory86), who also builds [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Two independent tools, released and installed separately, encoding one thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/README.md

@@ -12,7 +12,9 @@ secure-code-agent --fail-on-gate \
     --sarif-output secure-code.sarif
 ```
 
-The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Same shape: deterministic CI gate · plain-file outputs · per-host skill bundle. Different concern: security, not maintainability.
+**Runs on its own.** Install it, point it at a repository, get the gate, the report and the work order. Nothing else is required, and most people who use it will use only this.
+
+It is also the sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — same shape (deterministic CI gate · plain-file outputs · per-host skill bundle), different concern — and can feed that tool's Security pillar through [one file](docs/ma-integration.md). That is an integration, not a dependency: a family resemblance, not a component relationship. The two are separate products, installed separately, with their own dependency pins.
 
 ---
 
@@ -465,7 +467,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.6
+- uses: marshallguillory86/secure-code-agent@v0.12.8
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -564,4 +566,4 @@ MIT — see [`LICENSE`](LICENSE).
 
 ---
 
-Built by [Marshall Guillory](https://github.com/marshallguillory86). The companion to [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — both tools encode a single thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*
+Built by [Marshall Guillory](https://github.com/marshallguillory86), who also builds [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Two independent tools, released and installed separately, encoding one thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.12.6
+Version: 0.12.8
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -60,7 +60,9 @@ secure-code-agent --fail-on-gate \
     --sarif-output secure-code.sarif
 ```
 
-The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Same shape: deterministic CI gate · plain-file outputs · per-host skill bundle. Different concern: security, not maintainability.
+**Runs on its own.** Install it, point it at a repository, get the gate, the report and the work order. Nothing else is required, and most people who use it will use only this.
+
+It is also the sibling of [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — same shape (deterministic CI gate · plain-file outputs · per-host skill bundle), different concern — and can feed that tool's Security pillar through [one file](docs/ma-integration.md). That is an integration, not a dependency: a family resemblance, not a component relationship. The two are separate products, installed separately, with their own dependency pins.
 
 ---
 
@@ -513,7 +515,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.12.6
+- uses: marshallguillory86/secure-code-agent@v0.12.8
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -612,4 +614,4 @@ MIT — see [`LICENSE`](LICENSE).
 
 ---
 
-Built by [Marshall Guillory](https://github.com/marshallguillory86). The companion to [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent) — both tools encode a single thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*
+Built by [Marshall Guillory](https://github.com/marshallguillory86), who also builds [`maintainability-agent`](https://github.com/marshallguillory86/maintainability-agent). Two independent tools, released and installed separately, encoding one thesis: *AI agents need deterministic boundaries, not best-effort guardrails.*

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/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.6"
+__version__ = "0.12.8"

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/src/secure_code_audit/cli.py

@@ -98,6 +98,14 @@ def _parser() -> argparse.ArgumentParser:
     )
     p.add_argument("--comment-output", help="PR-comment markdown output path.")
     p.add_argument("--prompt-output", help="Remediation prompt output path.")
+    p.add_argument(
+        "--work-order-json",
+        help=(
+            "The remediation work order as JSON: the same triage and the same "
+            "caps as the prompt, as facts rather than prose, for a tool that "
+            "renders its own presentation."
+        ),
+    )
     p.add_argument(
         "--security-pillar",
         help=(
@@ -561,7 +569,18 @@ def _do_audit(args: argparse.Namespace) -> int:
         summarize_axis("test tree", test_findings, test_loc),
         summarize_axis("documentation", docs_findings, docs_loc or None),
         summarize_axis("dependencies", dependency_findings),
-        *(summarize_axis(name, found) for name, found in declared_axes.items()),
+        # 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.
@@ -867,6 +886,10 @@ def _own_artifacts(paths: _OutputPaths, cfg: config_mod.Config, root: Path) -> f
         paths.json_out,
         paths.sarif,
         paths.code_scanning_sarif,
+        # The work order as data (D27). Here for the same reason the prompt
+        # is: it quotes finding text and code snippets, so the next run
+        # would score this tool's own output as source.
+        paths.work_order_json,
         paths.comment,
         paths.prompt,
         paths.security_pillar,
@@ -1019,6 +1042,20 @@ def _write_outputs(
         # The work order needs the axis to tier a finding: a secret in a
         # test fixture is a suppression decision, not a patch target.
         remediation.write(findings, paths.prompt, root, lambda f: renderers.axis_of(f, axes))
+    # The same work order as facts. `maintainability-agent` embeds this one
+    # in an HTML report, and prose is the thing a consumer cannot
+    # re-present: with only Markdown it wrapped the text in `<pre>` and a
+    # reader got `##` headings inside a rendered page (D27).
+    if paths.work_order_json is not None:
+        paths.work_order_json.parent.mkdir(parents=True, exist_ok=True)
+        paths.work_order_json.write_text(
+            json.dumps(
+                remediation.as_data(findings, root, lambda f: renderers.axis_of(f, axes)),
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
     # The artifact maintainability-agent ingests (D3). Written last because it
     # is the only output that carries both axes plus the practice level.
     if paths.security_pillar is not None and pillar is not None:
@@ -1051,6 +1088,8 @@ class _OutputPaths:
     prompt: Path | None
     security_pillar: Path | None
     code_scanning_sarif: Path | None = None
+    #: The work order as data, for a tool that renders its own (D27).
+    work_order_json: Path | None = None
 
 
 def _resolve_outputs(args: argparse.Namespace, cfg: config_mod.Config, root: Path) -> _OutputPaths:
@@ -1096,6 +1135,7 @@ def _resolve_outputs(args: argparse.Namespace, cfg: config_mod.Config, root: Pat
         prompt=_p(args.prompt_output, "prompt_path"),
         security_pillar=_p(args.security_pillar, "security_pillar_path"),
         code_scanning_sarif=_p(args.code_scanning_sarif_output, "code_scanning_sarif_path"),
+        work_order_json=_p(args.work_order_json, "work_order_json_path"),
     )
 
 

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/src/secure_code_audit/config.py

@@ -147,6 +147,12 @@ DEFAULT_OUTPUTS: dict[str, str] = {
     "code_scanning_sarif_path": "secure-code.code-scanning.sarif",
     "comment_path": "secure-code-pr-comment.md",
     "prompt_path": "secure-code-remediation-prompt.md",
+    # The work order as data, for a tool that renders its own presentation
+    # (D27). Off unless declared, like the code-scanning SARIF: the prompt
+    # is the artifact an operator reads, and a second copy in JSON is only
+    # wanted by a consumer. The name is still declared so this tool never
+    # scans a file it wrote.
+    "work_order_json_path": "secure-code-work-order.json",
     "baseline_path": "secure-code-baseline.json",
     # Append-only trend. The score's one genuine use is movement over time.
     "history_path": ".secure-code/history.jsonl",

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/src/secure_code_audit/remediation.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 from pathlib import Path
+from typing import Any
 
 from secure_code_audit import triage
 from secure_code_audit.findings import Finding
@@ -245,6 +246,93 @@ def generate(
     return "\n".join(parts)
 
 
+#: The work order's data schema. Bumped when a consumer would have to
+#: change to keep reading it; new optional keys do not bump it.
+WORK_ORDER_SCHEMA_VERSION = 1
+
+
+def _finding_data(f: Finding, root: Path | None, note: str | None = None) -> dict[str, Any]:
+    """One finding, as the facts a renderer needs and nothing more.
+
+    Deliberately not the whole `Finding`. The fingerprint, the baseline
+    flag and the suppression note are this tool's bookkeeping; a consumer
+    drawing a work order needs what it is, where it is, what to do, and
+    the citation that makes it checkable.
+    """
+    return {
+        "rule_id": f.rule_id,
+        "scanner": f.scanner,
+        "title": f.short_desc or f.message,
+        "message": f.message,
+        "fix_hint": f.fix_hint,
+        "severity": f.severity.value,
+        "confidence": f.confidence.value,
+        "category": f.category.value,
+        "path": _display_path(f.file_path, root),
+        "line_start": f.line_start,
+        "line_end": f.line_end,
+        "location": _location(f, root),
+        "code_snippet": f.code_snippet,
+        "standards": {
+            "cwe": f.canonical_cwe,
+            "cwe_top25": f.cwe_top25,
+            "owasp_top10": f.owasp_top10,
+            "asvs_section": f.asvs_section,
+            "nist_ssdf": f.nist_ssdf,
+        },
+        # Only §REVIEW findings carry one: it is why the tier demoted them.
+        "review_note": note,
+    }
+
+
+def as_data(
+    findings: Iterable[Finding],
+    root: Path | None = None,
+    axis_of=lambda _f: "primary",
+) -> dict[str, Any]:
+    """The work order as facts, for a consumer that renders its own.
+
+    `generate` writes Markdown, which is right for the operator and for
+    the agent that reads the prompt. It is the wrong thing to hand a
+    *tool*: `maintainability-agent` embeds this work order in an HTML
+    report and had only prose, so it wrapped it in `<pre>` and a reader
+    got raw Markdown — headings as `##`, bold as asterisks — inside a
+    page where everything else was rendered.
+
+    Prose is the one thing a consumer cannot re-present. This is the same
+    triage, the same order and the same caps, as data: the tiers come from
+    `triage.partition` exactly as the Markdown's do, so the two can never
+    describe different work.
+
+    The caps are kept rather than dropped. A consumer showing more than
+    the prompt shows would disagree with the artifact the operator reads,
+    and `omitted` says how many are not here — the same number
+    `_overflow` prints.
+    """
+    tiers = triage.partition(findings, axis_of, root)
+    fix = tiers[triage.Tier.FIX]
+    review = tiers[triage.Tier.REVIEW]
+    accept = tiers[triage.Tier.ACCEPT]
+    return {
+        "schema_version": WORK_ORDER_SCHEMA_VERSION,
+        "counts": {"fix": len(fix), "review": len(review), "accept": len(accept)},
+        "fix": {
+            "shown": [_finding_data(f, root) for f in fix[:_MAX_BLOCKS]],
+            "omitted": max(0, len(fix) - _MAX_BLOCKS),
+        },
+        "review": {
+            "shown": [
+                _finding_data(f, root, triage.reason_for(f, root))
+                for f in review[:_MAX_REVIEW_LINES]
+            ],
+            "omitted": max(0, len(review) - _MAX_REVIEW_LINES),
+        },
+        # The accept tier is a count and a summary in the Markdown too: it is
+        # the test tree and documentation, which nobody patches one by one.
+        "accept": {"summary": _accept_summary(accept, root) if accept else ""},
+    }
+
+
 def _location(f: Finding, root: Path | None) -> str:
     span = f"-{f.line_end}" if f.line_end and f.line_end != f.line_start else ""
     return f"{_display_path(f.file_path, root)}:{f.line_start}{span}"

{secure_code_agent-0.12.6 → secure_code_agent-0.12.8}/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.6 → secure_code_agent-0.12.8}/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,