secure-code-agent 0.2.0__py3-none-any.whl

secure_code_audit/instructions.py

@@ -0,0 +1,141 @@
+"""Per-agent standards file generator — `--init-agent-standards`.
+
+For each target host (codex, claude-code, cursor, copilot, windsurf, generic),
+emit a standing-instructions file that tells the agent how to behave when
+asked to fix security findings in this repo. Additive to repo-specific rules
+in AGENTS.md / CLAUDE.md.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+# Map target → (filename, friendly_label)
+_TARGETS: dict[str, tuple[str, str]] = {
+    "codex":         ("AGENTS.md",                                "Codex (AGENTS.md)"),
+    "claude-code":   ("CLAUDE.md",                                "Claude Code (CLAUDE.md)"),
+    "cursor":        (".cursor/rules/security.mdc",               "Cursor (.cursor/rules/security.mdc)"),
+    "copilot":       (".github/copilot-instructions.md",          "GitHub Copilot (.github/copilot-instructions.md)"),
+    "windsurf":      (".windsurf/rules/security.md",              "Windsurf (.windsurf/rules/security.md)"),
+    "generic":       ("AI-SECURITY-STANDARDS.md",                 "Generic agent (AI-SECURITY-STANDARDS.md)"),
+}
+
+
+_BODY = """\
+# AI agent security standards (generated by secure-code-agent)
+
+This file is **appended** to the repo's existing AI-agent instructions.
+It encodes the bounded-remediation rules `secure-code-agent` enforces. If
+this file conflicts with the repo's own `AGENTS.md` / `CLAUDE.md`,
+**repo-specific rules win**.
+
+## When you are asked to fix a security finding
+
+1. **Read `secure-code-remediation-prompt.md` first if it exists.** It
+   is the canonical, finding-scoped task brief.
+2. **If no prompt exists**, run `secure-code-agent --prompt-output
+   secure-code-remediation-prompt.md` first, then read it.
+3. Follow the prompt's hard constraints verbatim.
+
+## Standing rules (apply to ALL security-related work in this repo)
+
+- **Do not change cryptographic algorithms, key derivation, IV/nonce
+  handling, padding modes, or random sources** unless a finding
+  explicitly names them as the defect.
+- **Do not change authentication flows, session handling, token
+  lifetime, cookie attributes, or authorization gates** unless a
+  finding explicitly names them.
+- **Do not weaken input validation, output encoding, sanitization,
+  bounds checks, regex strictness, or rate limits** to make existing
+  tests pass.
+- **Do not disable, delete, or skip security tests.** Do not remove
+  `@_limiter.limit`, `@require_auth`, `@require_csrf`, or similar
+  decorators.
+- **Do not silence linter warnings** via `# nosec`, `# noqa`,
+  `# type: ignore`, `eslint-disable`, `sonar-disable`, or
+  equivalent.
+- **Do not introduce new third-party dependencies.** Prefer stdlib
+  or already-vendored libraries. If a new dependency is necessary,
+  stop and ask the operator first.
+- **Preserve behavior.** Same inputs must produce the same outputs
+  unless a finding explicitly proves the current behavior is
+  unsafe.
+- **Add a focused test** that exercises the specific security
+  boundary you fixed. The test must FAIL on the pre-fix code and
+  PASS on the post-fix code.
+- **Keep patches small.** If you find yourself rewriting a function
+  rather than patching it, stop and report the structural issue
+  to the operator.
+
+## Standards anchors
+
+Findings carry: CWE id, OWASP Top 10 bucket, OWASP ASVS section,
+NIST SSDF practice. Read the standards entries before editing —
+they are the authoritative description of the weakness.
+
+- CWE: https://cwe.mitre.org/data/definitions/<num>.html
+- OWASP Top 10: https://owasp.org/Top10/2021/
+- OWASP ASVS: https://github.com/OWASP/ASVS
+- NIST SSDF: https://csrc.nist.gov/pubs/sp/800/218/final
+
+## False positives
+
+If a finding is a false positive, do NOT silently apply a fix.
+Add a suppression entry to `.scignore.yaml` with:
+
+  - `rule_id` (or `*` scoped to `file`/`paths`)
+  - `reason` (required, non-empty)
+  - `expires` (required, ISO date, ≤ 365 days from today)
+
+The operator will review the suppression in PR.
+"""
+
+
+def render() -> str:
+    """Return the generated body. Operators may append additional
+    repo-specific rules to the emitted file after the first run."""
+    return _BODY
+
+
+def write_for_target(target: str, output_dir: Path) -> Path:
+    if target not in _TARGETS:
+        raise ValueError(
+            f"Unknown target {target!r}. Known: {', '.join(sorted(_TARGETS))}."
+        )
+    rel_path, _ = _TARGETS[target]
+    out = output_dir / rel_path
+    out.parent.mkdir(parents=True, exist_ok=True)
+    body = render()
+
+    # If the target file exists, append below a fenced section so the
+    # operator's existing content is preserved.
+    if out.exists():
+        existing = out.read_text(encoding="utf-8")
+        marker   = "<!-- secure-code-agent:standards -->"
+        if marker in existing:
+            # Already initialized; refresh between markers.
+            before, _, rest    = existing.partition(marker)
+            _, _, after_close  = rest.partition("<!-- /secure-code-agent:standards -->")
+            new = f"{before}{marker}\n{body}\n<!-- /secure-code-agent:standards -->{after_close}"
+        else:
+            new = (
+                f"{existing.rstrip()}\n\n"
+                f"{marker}\n{body}\n<!-- /secure-code-agent:standards -->\n"
+            )
+    else:
+        new = (
+            "<!-- secure-code-agent:standards -->\n"
+            f"{body}\n"
+            "<!-- /secure-code-agent:standards -->\n"
+        )
+
+    out.write_text(new, encoding="utf-8")
+    return out
+
+
+def write_for_targets(targets: Iterable[str], output_dir: Path) -> list[Path]:
+    return [write_for_target(t, output_dir) for t in targets]
+
+
+def known_targets() -> list[str]:
+    return sorted(_TARGETS.keys())

secure_code_audit/remediation.py

@@ -0,0 +1,168 @@
+"""Remediation prompt generator — the differentiator.
+
+Produces an LLM-ready prompt scoped to the actual findings with explicit
+guardrails against the documented failure modes for AI security fixes.
+
+See docs/remediation.md for the full template + rationale.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from secure_code_audit.findings import Finding, Severity
+from secure_code_audit.standards import cwe_url, owasp_label
+
+
+_HARD_CONSTRAINTS = """\
+## Hard constraints (MUST NOT violate)
+
+1. Fix only the findings listed in §FINDINGS. Do not touch unrelated
+   code, files, or modules.
+2. Do not change cryptographic algorithms, key derivation, IV/nonce
+   handling, padding modes, or random sources unless a finding in
+   §FINDINGS explicitly names them as the defect.
+3. Do not change authentication flows, session handling, token
+   lifetime, cookie attributes, or authorization gates unless a
+   finding in §FINDINGS explicitly names them.
+4. Do not weaken input validation, output encoding, sanitization,
+   bounds checks, regex strictness, or rate limits to make existing
+   tests pass.
+5. Do not disable, delete, or skip security tests. Do not remove
+   `@_limiter.limit`, `@require_auth`, `@require_csrf`, or similar
+   decorators.
+6. Do not silence linter warnings via `# nosec`, `# noqa`, `# type:
+   ignore`, `eslint-disable`, `sonar-disable`, or equivalent.
+7. Do not introduce new third-party dependencies. Prefer stdlib or
+   already-vendored libraries. If a new dependency is necessary,
+   stop and ask the operator first.
+8. Preserve behavior. Same inputs must produce the same outputs
+   unless a finding explicitly proves the current behavior is
+   unsafe (in which case, name the input/output pair that changes
+   in the patch description).
+9. Add a focused test that exercises the specific security boundary
+   you fixed. The test must FAIL on the pre-fix code and PASS on the
+   post-fix code. No "TODO: add test later".
+10. Keep the patch small. If you find yourself rewriting a function
+    rather than patching it, stop and report the structural issue
+    to the operator instead.
+"""
+
+
+_PATCH_PROTOCOL = """\
+## Patch protocol
+
+For each finding:
+
+  1. Quote the specific lines you will change (file:line_start-line_end).
+  2. State the minimum change that resolves the finding.
+  3. State the test you will add.
+  4. Apply the change.
+  5. Run the test. Confirm it fails on the pre-fix code (via git stash
+     or equivalent) and passes after.
+  6. Re-run the audit (the operator's CI will do this — you don't need
+     to invoke secure-code-agent yourself).
+
+## Reporting
+
+When done, emit a single summary block per finding:
+
+  · Finding id:
+  · Files changed (file:line ranges):
+  · Test added (file:line range):
+  · Behavior change (yes/no — if yes, name input → old output / new output):
+  · Standards satisfied:
+
+If you discover the finding is a false positive, do NOT apply a fix.
+Instead, emit a suppression candidate for `.scignore.yaml` with the
+justification and a proposed `expires` date (max 90 days). Operator
+will review.
+"""
+
+
+def generate(findings: Iterable[Finding]) -> str:
+    """Build the full remediation prompt. Operators write the output to a
+    file and hand it to their agent (Claude Code, Codex, Cursor, Copilot)."""
+    actionable = [f for f in findings if not f.suppressed and f.severity != Severity.INFORMATIONAL]
+    if not actionable:
+        return (
+            "# Security remediation — no actionable findings\n\n"
+            "secure-code-agent did not surface any actionable security findings "
+            "for this run. Nothing to fix.\n"
+        )
+
+    parts: list[str] = []
+    parts.append("# Security remediation — bounded scope\n")
+    parts.append(
+        "You are fixing the security findings listed in §FINDINGS below.\n"
+        "This is a constrained task, not a refactor.\n"
+    )
+    parts.append(_HARD_CONSTRAINTS)
+    parts.append(_PATCH_PROTOCOL)
+    parts.append("## Standards context\n")
+    parts.append(
+        "Each finding below carries its CWE id, OWASP Top 10 bucket, OWASP\n"
+        "ASVS section, and NIST SSDF practice. Read the linked standards\n"
+        "entries before editing — they are the authoritative description\n"
+        "of the weakness.\n"
+    )
+    parts.append("## §FINDINGS\n")
+
+    # Sort: severity desc, then by file
+    sorted_findings = sorted(
+        actionable,
+        key=lambda f: (-f.severity.rank, f.file_path.as_posix(), f.line_start),
+    )
+    for n, f in enumerate(sorted_findings, start=1):
+        parts.append(_finding_block(n, f))
+
+    parts.append(_footer())
+    return "\n".join(parts)
+
+
+def _finding_block(n: int, f: Finding) -> str:
+    lines: list[str] = []
+    lines.append(f"### Finding {n}: `{f.rule_id}` — {f.short_desc or f.message[:120]}")
+    lines.append("")
+    lines.append(f"- **Severity:** {f.severity.value} ({f.confidence.value} confidence)")
+    if f.canonical_cwe:
+        top25 = " (MITRE Top 25)" if f.cwe_top25 else ""
+        lines.append(f"- **CWE:** [{f.canonical_cwe}]({cwe_url(f.canonical_cwe)}){top25}")
+    if f.owasp_top10:
+        lines.append(f"- **OWASP Top 10:** {owasp_label(f.owasp_top10)}")
+    if f.asvs_section:
+        lines.append(f"- **OWASP ASVS:** `{f.asvs_section}`")
+    if f.nist_ssdf:
+        lines.append(f"- **NIST SSDF:** `{f.nist_ssdf}`")
+    lines.append(f"- **Scanner:** `{f.scanner}`")
+    lines.append(f"- **Category:** `{f.category.value}`")
+    lines.append("")
+    lines.append(
+        f"**Location:** `{f.file_path.as_posix()}:{f.line_start}"
+        + (f"-{f.line_end}" if f.line_end and f.line_end != f.line_start else "")
+        + "`"
+    )
+    if f.code_snippet:
+        lines.append("")
+        lines.append("```")
+        lines.append(f.code_snippet.rstrip())
+        lines.append("```")
+    lines.append("")
+    lines.append(f"**Why this matters:** {f.message}")
+    if f.fix_hint:
+        lines.append("")
+        lines.append(f"**Suggested approach:** {f.fix_hint}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _footer() -> str:
+    return (
+        "---\n\n"
+        "End of findings. Apply the patch protocol above per finding. "
+        "Report each one in the summary block format.\n"
+    )
+
+
+def write(findings: Iterable[Finding], path: Path) -> None:
+    path.write_text(generate(findings), encoding="utf-8")

secure_code_audit/renderers.py

@@ -0,0 +1,253 @@
+"""Renderers — markdown report, canonical JSON, PR-comment summary."""
+from __future__ import annotations
+
+import datetime
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Iterable
+
+from secure_code_audit import __version__
+from secure_code_audit.findings import Category, Finding, Severity
+from secure_code_audit.scoring import GateResult, ScoreReport, letter_grade
+from secure_code_audit.standards import cwe_url, owasp_label
+
+
+# ---------------------------------------------------------------------------
+# Canonical JSON
+# ---------------------------------------------------------------------------
+
+def to_json(findings: Iterable[Finding], score: ScoreReport, gate: GateResult) -> dict:
+    findings = list(findings)
+    return {
+        "version":   __version__,
+        "generated": datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "score": {
+            "overall":             score.overall,
+            "letter":              score.letter,
+            "loc_scanned":         score.loc_scanned,
+            "worst_category":      score.worst_category.value if score.worst_category else None,
+            "per_category":        {c.value: round(v, 2) for c, v in score.per_category.items()},
+            "per_category_count":  {c.value: n for c, n in score.per_category_count.items()},
+            "per_severity_count":  {s.value: n for s, n in score.per_severity_count.items()},
+        },
+        "gate": {
+            "passed":  gate.passed,
+            "reasons": list(gate.reasons),
+            "tripped": list(gate.tripped),
+        },
+        "findings": [_finding_to_dict(f) for f in findings],
+    }
+
+
+def _finding_to_dict(f: Finding) -> dict:
+    return {
+        "rule_id":          f.rule_id,
+        "scanner":          f.scanner,
+        "fingerprint":      f.fingerprint,
+        "canonical_cwe":    f.canonical_cwe,
+        "owasp_top10":      f.owasp_top10,
+        "asvs_section":     f.asvs_section,
+        "nist_ssdf":        f.nist_ssdf,
+        "category":         f.category.value,
+        "severity":         f.severity.value,
+        "confidence":       f.confidence.value,
+        "cwe_top25":        f.cwe_top25,
+        "file_path":        f.file_path.as_posix(),
+        "line_start":       f.line_start,
+        "line_end":         f.line_end,
+        "code_snippet":     f.code_snippet,
+        "message":          f.message,
+        "short_desc":       f.short_desc,
+        "fix_hint":         f.fix_hint,
+        "suppressed":       f.suppressed,
+        "suppression_note": f.suppression_note,
+        "is_new":           f.is_new,
+    }
+
+
+def write_json(findings: Iterable[Finding], score: ScoreReport, gate: GateResult, path: Path) -> None:
+    path.write_text(json.dumps(to_json(findings, score, gate), indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Markdown report
+# ---------------------------------------------------------------------------
+
+def write_markdown(
+    findings:    list[Finding],
+    score:       ScoreReport,
+    gate:        GateResult,
+    path:        Path,
+    scanners_run: list[str],
+    scanners_unavailable: list[str],
+) -> None:
+    path.write_text(_markdown(findings, score, gate, scanners_run, scanners_unavailable), encoding="utf-8")
+
+
+def _markdown(
+    findings: list[Finding],
+    score:    ScoreReport,
+    gate:     GateResult,
+    scanners_run: list[str],
+    scanners_unavailable: list[str],
+) -> str:
+    lines: list[str] = []
+    lines.append(f"# secure-code-agent report\n")
+    lines.append(f"Generated: {datetime.datetime.now(datetime.UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}  ·  "
+                 f"agent v{__version__}\n")
+
+    lines.append(_summary_section(score, gate))
+    lines.append(_categories_table(score))
+    lines.append(_severity_table(score))
+    lines.append(_scanners_section(scanners_run, scanners_unavailable))
+    lines.append(_findings_sections(findings))
+    return "\n".join(lines)
+
+
+def _summary_section(score: ScoreReport, gate: GateResult) -> str:
+    status = "✅ PASS" if gate.passed else "❌ FAIL"
+    out  = ["## Summary", ""]
+    out.append(f"- **Score:** {score.overall:.2f} / 5.00 — **{score.letter}**")
+    out.append(f"- **Gate:** {status}")
+    if not gate.passed:
+        out.append("- **Tripped gates:**")
+        for reason, key in zip(gate.reasons, gate.tripped):
+            out.append(f"    - `{key}` — {reason}")
+    out.append(f"- **LOC scanned:** {score.loc_scanned:,}")
+    if score.worst_category is not None:
+        out.append(f"- **Worst category:** `{score.worst_category.value}`")
+    out.append("")
+    return "\n".join(out)
+
+
+def _categories_table(score: ScoreReport) -> str:
+    out = ["## Categories", "", "| Category | Grade | Score | Findings |", "|---|---|---:|---:|"]
+    for cat_name, grade_letter, grade_score, count in score.as_table():
+        out.append(f"| `{cat_name}` | **{grade_letter}** | {grade_score:.2f} | {count} |")
+    out.append("")
+    return "\n".join(out)
+
+
+def _severity_table(score: ScoreReport) -> str:
+    out = ["## Severity breakdown", "", "| Severity | Count |", "|---|---:|"]
+    for sev in (Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFORMATIONAL):
+        out.append(f"| **{sev.value}** | {score.per_severity_count.get(sev, 0)} |")
+    out.append("")
+    return "\n".join(out)
+
+
+def _scanners_section(scanners_run: list[str], scanners_unavailable: list[str]) -> str:
+    out = ["## Scanners", ""]
+    out.append(f"- Run: {', '.join(scanners_run) if scanners_run else '_none_'}")
+    if scanners_unavailable:
+        out.append(f"- Skipped (binary not on PATH): {', '.join(scanners_unavailable)}")
+    out.append("")
+    return "\n".join(out)
+
+
+def _findings_sections(findings: list[Finding]) -> str:
+    if not findings:
+        return "## Findings\n\n_None._\n"
+
+    # Sort: severity desc, then category, then file
+    severity_order = list(Severity)
+    sorted_findings = sorted(
+        findings,
+        key=lambda f: (
+            -f.severity.rank,
+            0 if f.is_new else 1,
+            f.category.value,
+            f.file_path.as_posix(),
+            f.line_start,
+        ),
+    )
+
+    by_sev: dict[Severity, list[Finding]] = defaultdict(list)
+    for f in sorted_findings:
+        if f.suppressed:
+            continue
+        by_sev[f.severity].append(f)
+
+    out = ["## Findings", ""]
+    for sev in severity_order:
+        bucket = by_sev.get(sev) or []
+        if not bucket:
+            continue
+        out.append(f"### {sev.value.title()}")
+        out.append("")
+        for f in bucket:
+            out.extend(_one_finding_md(f))
+            out.append("")
+
+    suppressed = [f for f in findings if f.suppressed]
+    if suppressed:
+        out.append("---")
+        out.append("")
+        out.append("## Acknowledged (suppressed)")
+        out.append("")
+        for f in suppressed:
+            out.append(f"- `{f.rule_id}` — `{f.file_path.as_posix()}:{f.line_start}` — "
+                       f"{f.suppression_note or 'no note'}")
+        out.append("")
+    return "\n".join(out)
+
+
+def _one_finding_md(f: Finding) -> list[str]:
+    out: list[str] = []
+    new_marker = " 🆕" if f.is_new else ""
+    out.append(f"#### `{f.rule_id}` — {f.short_desc or f.message[:120]}{new_marker}")
+    out.append("")
+    out.append(f"- **Severity:** {f.severity.value} ({f.confidence.value} confidence)")
+    out.append(f"- **Category:** `{f.category.value}`")
+    out.append(f"- **Scanner:** `{f.scanner}`")
+    if f.canonical_cwe:
+        cwe_marker = " (Top 25)" if f.cwe_top25 else ""
+        out.append(f"- **CWE:** [{f.canonical_cwe}]({cwe_url(f.canonical_cwe)}){cwe_marker}")
+    if f.owasp_top10:
+        out.append(f"- **OWASP Top 10:** {owasp_label(f.owasp_top10)}")
+    if f.asvs_section:
+        out.append(f"- **OWASP ASVS:** `{f.asvs_section}`")
+    if f.nist_ssdf:
+        out.append(f"- **NIST SSDF:** `{f.nist_ssdf}`")
+    out.append(f"- **Location:** `{f.file_path.as_posix()}:{f.line_start}"
+               + (f"-{f.line_end}" if f.line_end and f.line_end != f.line_start else "")
+               + "`")
+    if f.code_snippet:
+        out.append("")
+        out.append("```")
+        out.append(f.code_snippet.rstrip())
+        out.append("```")
+    if f.fix_hint:
+        out.append("")
+        out.append(f"> 💡 **Fix:** {f.fix_hint}")
+    return out
+
+
+# ---------------------------------------------------------------------------
+# PR comment (short, scannable)
+# ---------------------------------------------------------------------------
+
+def write_pr_comment(findings: list[Finding], score: ScoreReport, gate: GateResult, path: Path) -> None:
+    path.write_text(_pr_comment(findings, score, gate), encoding="utf-8")
+
+
+def _pr_comment(findings: list[Finding], score: ScoreReport, gate: GateResult) -> str:
+    status = "✅" if gate.passed else "❌"
+    n_crit = score.per_severity_count.get(Severity.CRITICAL, 0)
+    n_high = score.per_severity_count.get(Severity.HIGH, 0)
+    n_new  = sum(1 for f in findings if f.is_new and not f.suppressed)
+
+    out = [
+        f"### secure-code-agent {status} — score **{score.letter}** ({score.overall:.2f}/5.00)",
+        "",
+        f"- Critical: **{n_crit}** · High: **{n_high}** · New since baseline: **{n_new}**",
+        f"- Worst category: `{score.worst_category.value if score.worst_category else '_none_'}`",
+    ]
+    if not gate.passed:
+        out.append("- Tripped gates:")
+        for r in gate.reasons:
+            out.append(f"    - {r}")
+    out.append("")
+    out.append("_Full report uploaded as artifact._")
+    return "\n".join(out)