diff options
| author | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
|---|---|---|
| committer | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
| commit | 7aba3deae3ff17d032c37e07d2929d1426b34278 (patch) | |
| tree | 9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/claude-security/scripts | |
| parent | 5472f5f56e0070feeeb464318b316714fe3e9105 (diff) | |
| parent | b8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (diff) | |
Merge remote-tracking branch 'origin/main' into add-plugin/xcodeadd-plugin/xcode
Diffstat (limited to 'plugins/claude-security/scripts')
| -rw-r--r-- | plugins/claude-security/scripts/lib/finding.py | 258 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/git.py | 27 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/link.py | 23 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/plugin.py | 18 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/revision.py | 28 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/sarif.py | 51 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/secret.py | 22 | ||||
| -rw-r--r-- | plugins/claude-security/scripts/lib/strictjson.py | 20 | ||||
| -rwxr-xr-x | plugins/claude-security/scripts/patch_artifacts.py | 678 | ||||
| -rwxr-xr-x | plugins/claude-security/scripts/render_report.py | 173 | ||||
| -rwxr-xr-x | plugins/claude-security/scripts/save_result.py | 98 | ||||
| -rwxr-xr-x | plugins/claude-security/scripts/write_scan_meta.py | 299 |
12 files changed, 1343 insertions, 352 deletions
diff --git a/plugins/claude-security/scripts/lib/finding.py b/plugins/claude-security/scripts/lib/finding.py index b7cfa0dd..0a14e4d3 100644 --- a/plugins/claude-security/scripts/lib/finding.py +++ b/plugins/claude-security/scripts/lib/finding.py @@ -4,7 +4,11 @@ from __future__ import annotations import ntpath import os +import posixpath import re +from enum import IntEnum +from itertools import dropwhile +from pathlib import Path from typing import TypedDict from . import absolute, cwe @@ -38,6 +42,8 @@ class Finding(TypedDict): snippet: str symbol: str declared_line: int + via_change: str | None + other_cwe_ids: list[str] class Record(Finding): @@ -46,9 +52,29 @@ class Record(Finding): claudeSecurityPluginFindingId: str -SEVERITIES = ("CRITICAL", "HIGH", "MEDIUM", "LOW") -CONFIDENCES = ("low", "medium", "high") -CONFIDENCE_RANK = {"low": 1, "medium": 2, "high": 3} +class Severity(IntEnum): + """A finding's severity.""" + + CRITICAL = 4 + HIGH = 3 + MEDIUM = 2 + LOW = 1 + + @classmethod + def of(cls, record: JsonMap) -> Severity | None: + """A record's severity from its word, stripped and in any letter case; None when the + word names none. + """ + return cls.__members__.get(str(record.get("severity", "")).strip().upper()) + + +class Confidence(IntEnum): + """A finding's confidence.""" + + low = 1 + medium = 2 + high = 3 + PANEL_VOTER_COUNT = 3 PANEL_KEEP_QUORUM = 2 @@ -71,7 +97,7 @@ class FindingPathError(FindingError): finding_id: str wrong: str - cwe: int = 0 + cwes: tuple[int, ...] = () snippet: str = "" def __init__(self, finding_id: str, *, declared: str, wrong: str) -> None: @@ -88,22 +114,60 @@ def cwe_number(item: JsonMap, finding_id: str) -> int: under Uncategorized, and the renderer discloses the substitution. """ declared = text_field(item, "cwe_id", finding_id, required=True) + return cwe_parsed(declared, finding_id, "cwe_id") + + +def cwe_parsed(declared: str, finding_id: str, field: str) -> int: + """The number in one CWE id as a record may spell it; anything else is refused.""" matched = re.fullmatch( r"(?:CWE-)?0*([1-9][0-9]{0,4})", declared.strip().upper().replace("_", "-") ) if not matched: - msg = f"finding {finding_id} cwe_id {declared!r} is not a CWE id such as CWE-89" + msg = f"finding {finding_id} {field} {declared!r} is not a CWE id such as CWE-89" raise FindingError(msg) return int(matched[1]) -def confidence_value(raw: object) -> str: - """A finding's stated confidence, normalized to low|medium|high; refuses others.""" +# The research schema opens every change link with "file:line "; sarif.placed reads that site. +LINK_SITE = re.compile(r"(.+?):([1-9][0-9]{0,14})(?:-([1-9][0-9]{0,14}))?\b") + + +def link_field(item: JsonMap, finding_id: str, scan_root: str, scan_prefix: str) -> str | None: + """A change scan's via_change with its leading file normalised like `file`; None when absent. + + A link that does not open with a file:line the scan can place is kept as written. + """ + link = text_field(item, "via_change", finding_id).strip() or None + matched = LINK_SITE.match(link or "") + if not (link and matched): + return link + try: + file = relative_path(matched[1], finding_id, scan_root, scan_prefix, must_exist=False) + except FindingPathError: + return link + return file + link[matched.end(1) :] + + +def other_cwe_numbers(item: JsonMap, finding_id: str, primary: int) -> list[int]: + """The further CWE numbers a finding carries, the primary and repeats left out.""" + raw = item.get("other_cwe_ids") + if raw is None: + return [] + entries = [entry for entry in raw if is_str(entry)] if is_list(raw) else [] + if not is_list(raw) or len(entries) != len(raw): + msg = f"finding {finding_id} other_cwe_ids is not a list of CWE ids" + raise FindingError(msg) + numbers = [cwe_parsed(entry, finding_id, "other_cwe_ids") for entry in entries] + return [n for n in dict.fromkeys(numbers) if n != primary] + + +def confidence_value(raw: object) -> Confidence: + """A finding's stated confidence, in any letter case; refuses any other value.""" if is_str(raw): word = raw.strip().lower() - if word in CONFIDENCE_RANK: - return word - msg = f"confidence {raw!r} is not one of {'/'.join(CONFIDENCES)}" + if word in Confidence.__members__: + return Confidence[word] + msg = f"confidence {raw!r} is not one of {'/'.join(Confidence.__members__)}" raise FindingError(msg) @@ -127,12 +191,23 @@ def panel_complete(record: object) -> Panel | None: } -def vote_confidence_ceiling(record: object) -> str | None: +def vote_rounds(votes: JsonMap) -> JsonMap: + """The vote record's rounds by id, or an empty map when it holds none.""" + raw = votes.get("rounds") + return raw if is_map(raw) else {} + + +def finding_panels(rounds: JsonMap, ids: list[str]) -> list[tuple[str, Panel | None]]: + """Each finding id with its complete panel in the rounds, or None, in the order given.""" + return [(i, panel_complete(rounds.get(i))) for i in ids] + + +def vote_confidence_ceiling(record: object) -> Confidence | None: """A finding's vote-backed confidence: `high` if unanimous, `medium` if complete, else None.""" panel = panel_complete(record) if panel is None: return None - return "high" if panel["true"] >= PANEL_VOTER_COUNT else "medium" + return Confidence.high if panel["true"] >= PANEL_VOTER_COUNT else Confidence.medium def line_number(raw: object) -> int | None: @@ -151,6 +226,20 @@ def line_field(item: JsonMap, key: str, finding_id: str, default: int) -> int: return line +def repository_file(scan_prefix: str, *, file: str) -> str: + """A scan-root-relative `file` made repository-relative by a lexical fold.""" + return posixpath.normpath(scan_prefix + file) + + +def scan_prefix_fits(prefix: str, *, scan_root: str) -> bool: + """Whether `prefix` has no more components than the scan root's real path, as a prefix git + printed always does.""" + try: + return prefix.count("/") <= len(Path(os.path.realpath(scan_root)).parents) + except (OSError, ValueError): + return False + + def scan_prefix_shaped(prefix: str) -> bool: """Whether `prefix` is what `git rev-parse --show-prefix` prints: empty, or `a/b/`.""" if not prefix: @@ -196,49 +285,102 @@ def file_field( ) -> str: """A finding's file relative to the scan root; a path that leaves the repository is refused. - `scan_prefix` is the scan root's path below the repository top level (`a/b/`, - or empty): a file may climb one directory per prefix component and no further. - A file spelled relative to the top level, absent under the scan root but - present under the top level, is respelled relative to the scan root. - With `must_exist` (a codebase scan, whose whole tree is still present when - the report renders), a path that exists neither under the scan root nor at - the repository top level is refused. - A name that merely spells like another platform's absolute path is treated - as repository content when the scan root holds its first segment. + `scan_prefix` is the scan root's path below the repository top level (`a/b/`, or empty). + With `must_exist` (a codebase scan) a missing file is refused. relative_path has the rules. """ declared = text_field(item, "file", finding_id, required=True).strip() + return relative_path(declared, finding_id, scan_root, scan_prefix, must_exist) + + +def located(spelled: str, *, root: Path, top: Path) -> Path | None: + """The path `spelled` resolves to from the scan root `root` or the repository top level `top`. + + The result may lie outside the repository, through a link. None when no place holds the folder + the path names and the path has a `..` after its leading climb. + """ + if Path(spelled).is_absolute(): + return Path(os.path.realpath(spelled)) + files: list[Path] = [] + for base in dict.fromkeys((root, top)): + spelled_from = Path(base, spelled) + if top not in Path(os.path.normpath(spelled_from)).parents: + continue + folder = Path(os.path.realpath(spelled_from.parent)) + if top not in {folder, *folder.parents}: + if not files: + return Path(os.path.realpath(spelled_from)) + continue + if spelled_from.parent.is_dir(): + file = Path(os.path.realpath(spelled_from)) + if top not in file.parents: + if not files: + return file + continue + if file.exists(): + return file + files.append(file) + if not files and ".." not in dropwhile(lambda part: part == "..", Path(spelled).parts): + files = [Path(os.path.realpath(Path(root, spelled)))] + return next(iter(files), None) + + +def relative_path( + declared: str, finding_id: str, scan_root: str, scan_prefix: str, must_exist: bool +) -> str: + """A file as a finding spells it, resolved and made relative to the scan root. + + The path is refused when it resolves outside the repository, to the scan root or above, or + to a missing file that a codebase scan needs or whose stored path would name another file. + """ depth = scan_prefix.count("/") escapes = f"escapes the {'repository' if depth else 'scan root'}" - path = declared.replace("\\", "/") + unresolved = "cannot be resolved" + elsewhere = "could be mistaken for a path at the repository top level" + spelled = declared.replace("\\", "/") prefix = scan_root.replace("\\", "/").rstrip("/") + "/" - if scan_root and path.startswith(prefix): - path = path[len(prefix) :].lstrip("/") - if os.path.isabs(path): - try: - path = os.path.relpath(os.path.realpath(path), scan_root).replace("\\", "/") - except (ValueError, OSError) as error: - raise FindingPathError(finding_id, declared=declared, wrong=escapes) from error - parts = [part for part in path.split("/") if part and part != "."] - climb = next((i for i, part in enumerate(parts) if part != ".."), len(parts)) - inside = parts[climb:] + if scan_root and spelled.startswith(prefix): + spelled = spelled[len(prefix) :].lstrip("/") + root = Path(os.path.realpath(scan_root)) + top = (root, *root.parents)[depth] + leaves = top not in Path(os.path.normpath(Path(root, spelled))).parents + if leaves and not Path(spelled).is_absolute(): + raise FindingPathError(finding_id, declared=declared, wrong=escapes) + try: + file = located(spelled, root=root, top=top) + except (OSError, ValueError) as error: + wrong = escapes if leaves else unresolved + raise FindingPathError(finding_id, declared=declared, wrong=wrong) from error + if file is None: + unreadable = "cannot be read from the scan root or the repository top level" + raise FindingPathError(finding_id, declared=declared, wrong=unreadable) + if top not in file.parents: + raise FindingPathError(finding_id, declared=declared, wrong=escapes) + if root.is_relative_to(file): + raise FindingPathError(finding_id, declared=declared, wrong="names a folder, not a file") + relative = Path(os.path.relpath(file, root)).as_posix() + if leaked_spelling(relative, first=relative.split("/")[0], scan_root=scan_root): + raise FindingPathError(finding_id, declared=declared, wrong=escapes) + try: + exists = file.exists() + except OSError as error: + raise FindingPathError(finding_id, declared=declared, wrong=unresolved) from error + if exists: + return relative + if must_exist: + raise FindingPathError( + finding_id, declared=declared, wrong="does not exist in the scanned tree" + ) + try: + again = located(relative, root=root, top=top) + except OSError as error: + raise FindingPathError(finding_id, declared=declared, wrong=unresolved) from error if ( - not inside - or ".." in inside - or climb > depth - or leaked_spelling(path, first=parts[0], scan_root=scan_root) + again is None + or top not in again.parents + or Path(os.path.relpath(again, root)).as_posix() != relative ): - raise FindingPathError(finding_id, declared=declared, wrong=escapes) - if not os.path.lexists(os.path.join(scan_root, *parts)): - # A file only the repository top level holds was spelled relative to it, not the scan root. - if depth and not climb: - at_top = os.path.join(os.path.normpath(os.path.join(scan_root, "../" * depth)), *parts) - if os.path.lexists(at_top): - return os.path.relpath(at_top, scan_root).replace("\\", "/") - if must_exist: - raise FindingPathError( - finding_id, declared=declared, wrong="does not exist in the scanned tree" - ) - return "/".join(parts) + raise FindingPathError(finding_id, declared=declared, wrong=elsewhere) + return relative def build_finding( @@ -259,18 +401,18 @@ def build_finding( msg = f"finding id {finding_id!r} is not a valid id" raise FindingError(msg) - severity = str(raw.get("severity", "")).strip().upper() - if severity not in SEVERITIES: + severity = Severity.of(raw) + if severity is None: msg = ( f"finding {finding_id} severity {raw.get('severity')!r} is not one of " - f"{'/'.join(SEVERITIES)}" + f"{'/'.join(Severity.__members__)}" ) raise FindingError(msg) confidence = confidence_value(raw.get("confidence")) ceiling = vote_confidence_ceiling(rounds_by_id.get(finding_id)) - if ceiling is not None and CONFIDENCE_RANK[confidence] > CONFIDENCE_RANK[ceiling]: - confidence = ceiling + if ceiling is not None: + confidence = min(confidence, ceiling) line = line_field(raw, "line", finding_id, 0) declared_line = line_field(raw, "declared_line", finding_id, line) @@ -295,10 +437,12 @@ def build_finding( recommendation = text_field(raw, "recommendation", finding_id) snippet = text_field(raw, "snippet", finding_id) symbol = text_field(raw, "symbol", finding_id) + via_change = link_field(raw, finding_id, scan_root, scan_prefix) + further = other_cwe_numbers(raw, finding_id, number) try: file = file_field(raw, finding_id, scan_root, scan_prefix, must_exist) except FindingPathError as error: - error.cwe, error.snippet = number, snippet + error.cwes, error.snippet = (number, *further), snippet raise return { @@ -311,11 +455,13 @@ def build_finding( "exploit_scenario": exploit_scenario, "preconditions": preconditions, "category": category.name if category is not None else cwe.UNCATEGORIZED, - "severity": severity, - "confidence": confidence, + "severity": severity.name, + "confidence": confidence.name, "recommendation": recommendation, "cwe_id": f"CWE-{number}", "snippet": snippet, "symbol": symbol, "declared_line": declared_line, + "via_change": via_change, + "other_cwe_ids": [f"CWE-{n}" for n in further], } diff --git a/plugins/claude-security/scripts/lib/git.py b/plugins/claude-security/scripts/lib/git.py new file mode 100644 index 00000000..ded163d3 --- /dev/null +++ b/plugins/claude-security/scripts/lib/git.py @@ -0,0 +1,27 @@ +"""Read-only git calls for the scripts: one runner, prompts suppressed, output byte-faithful.""" + +from __future__ import annotations + +import os +import subprocess + +REDIRECTS = frozenset({"GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"}) +ENV = {k: v for k, v in os.environ.items() if k not in REDIRECTS} | {"GIT_TERMINAL_PROMPT": "0"} + + +def run(cwd: str, *args: str) -> str | None: + """The stdout of `git -C <cwd> <args>` without trailing newlines; None on any failure.""" + try: + out = subprocess.run( + ["git", "-C", cwd, *args], + env=ENV, + stdout=subprocess.PIPE, + stderr=subprocess.DEVNULL, + timeout=30, + check=False, + ) + except (OSError, subprocess.SubprocessError): + return None + if out.returncode != 0: + return None + return out.stdout.decode("utf-8", "surrogateescape").rstrip("\r\n") diff --git a/plugins/claude-security/scripts/lib/link.py b/plugins/claude-security/scripts/lib/link.py new file mode 100644 index 00000000..4c70b542 --- /dev/null +++ b/plugins/claude-security/scripts/lib/link.py @@ -0,0 +1,23 @@ +"""Whether a path is a link that a removal must not be sent through.""" + +from __future__ import annotations + +import os +import stat + + +def is_link(path: str | os.PathLike[str]) -> bool: + """Whether `path` is a symbolic link or, on Windows, a directory junction. + + False for a path that is absent or cannot be examined. + """ + try: + status = os.lstat(path) + except OSError: + return False + if stat.S_ISLNK(status.st_mode): + return True + if os.name == "nt": + reparse_point = status.st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT + return bool(reparse_point) and status.st_reparse_tag == stat.IO_REPARSE_TAG_MOUNT_POINT + return False diff --git a/plugins/claude-security/scripts/lib/plugin.py b/plugins/claude-security/scripts/lib/plugin.py index 2d8321cd..c7f902a0 100644 --- a/plugins/claude-security/scripts/lib/plugin.py +++ b/plugins/claude-security/scripts/lib/plugin.py @@ -16,8 +16,26 @@ TARGET_FILES_NAME = "target-files.json" VOTES_PROVENANCE = "workflows/scan.js" MODES = ("scan", "changes", "commit") REPORT_DIR_PREFIX = "CLAUDE-SECURITY-" +# \Z, not $: `$` also matches before a trailing newline, and this is a fence. +REPORT_DIR_RE = re.compile(rf"^{re.escape(REPORT_DIR_PREFIX)}[0-9][0-9-]*\Z") +JSONL_NAME = "CLAUDE-SECURITY-RESULTS.jsonl" +REVISION_PREFIX = "CLAUDE-SECURITY-REVISION-" # \Z, not $: `$` also matches before a trailing newline, and this id names product files. SHA_RE = re.compile(r"^[0-9a-fA-F]{7,64}\Z") +SHORT_ID_CHARS = 12 +_RETIRED_MAX_NOTE = ( + "The `max` effort tier has been retired, so I'm running this scan at `high`. " + "A future version will stop accepting `max` and return an error." +) +RETIRED_MAX_RELAY = ( + "relay: say this to the user exactly as printed, to open your kickoff message and " + f"again to close your results message: {_RETIRED_MAX_NOTE}" +) + + +def is_revision_stamp(path: Path) -> bool: + """Whether `path` has a revision stamp's name, `CLAUDE-SECURITY-REVISION-<tag>.json`.""" + return path.name.startswith(REVISION_PREFIX) and path.suffix == ".json" def version() -> str | None: diff --git a/plugins/claude-security/scripts/lib/revision.py b/plugins/claude-security/scripts/lib/revision.py new file mode 100644 index 00000000..afe334e2 --- /dev/null +++ b/plugins/claude-security/scripts/lib/revision.py @@ -0,0 +1,28 @@ +"""The revision a scan records, and the `<base>..<commit>` range a change scan's revision names.""" + +from __future__ import annotations + +from typing import Literal, TypedDict + +from .strictjson import JsonMap, is_str + + +class Revision(TypedDict, total=False): + """What was scanned. `versioned` is always present; the rest when in git.""" + + versioned: bool + commit: str | None + parent: str | None + branch: str | None + dirty: bool | None + sparse: Literal[True] + not_checked_out_dirs: list[str] + base: str | None + merge_base: str | None + + +def change_range(revision: JsonMap) -> str | None: + """The `<base>..<commit>` range a change scan's revision names; None when it names no change.""" + base = revision.get("merge_base") or revision.get("parent") + commit = revision.get("commit") + return f"{base}..{commit}" if is_str(base) and is_str(commit) else None diff --git a/plugins/claude-security/scripts/lib/sarif.py b/plugins/claude-security/scripts/lib/sarif.py index de98e4f5..ace752ba 100644 --- a/plugins/claude-security/scripts/lib/sarif.py +++ b/plugins/claude-security/scripts/lib/sarif.py @@ -4,13 +4,13 @@ from __future__ import annotations import hashlib import json -import posixpath import re from dataclasses import dataclass from typing import TYPE_CHECKING, Final, NamedTuple from urllib.parse import quote from . import cwe, secret, source +from .finding import LINK_SITE, repository_file if TYPE_CHECKING: import uuid @@ -173,7 +173,7 @@ def placed( `sources` is the text of each scanned file by the finding's `file`; a finding whose file is absent from it keeps its line and hashes the number. """ - texts = {repository_file(scan, file): text for file, text in sources.items()} + texts = {repository_file(scan.prefix, file=file): text for file, text in sources.items()} secrets = { (path, line) for f in findings @@ -188,23 +188,55 @@ def placed( return [placed_one(f, scan, sources.get(f["file"]), secrets) for f in findings] +class Span(NamedTuple): + """Lines `first` to `last` of the file at repository path `path`.""" + + path: str + first: int + last: int + + def placed_one( finding: Finding, scan: Scan, text: str | None, secrets: Collection[tuple[str, int]] ) -> Record: - """One finding placed in `text`, its file's content (None when unread), and given its id.""" + """One finding placed in `text`, its file's content (None when unread), and given its id. + + The link to the change is dropped for a finding inside a credential's window, + or whose link opens at a line or range that reaches one: it may describe the credential. + """ moved: Finding = finding code = None + path = repository_path(scan, finding) if text is not None: lines = source.normalized_lines(text) row = source.placing_row(lines, finding["line"], finding["snippet"]) if row is not None: moved = {**finding, "line": row + 1} - path = repository_path(scan, finding) - near_secret = any(p == path and abs(row + 1 - n) <= CONTEXT_LINES for p, n in secrets) - code = None if near_secret else code_at(lines, row) + code = None if near(Span(path, row + 1, row + 1), secrets) else code_at(lines, row) + anchor = Span(path, moved["line"], moved["line"]) + link = link_site(scan, moved["via_change"]) + if near(anchor, secrets) or (link is not None and near(link, secrets)): + moved = {**moved, "via_change": None} return {**moved, FINDING_ID: fingerprint(moved, scan, code)} +def near(span: Span, secrets: Collection[tuple[str, int]]) -> bool: + """True when `span` comes within CONTEXT_LINES of a credential line in its file.""" + return any( + p == span.path and span.first - CONTEXT_LINES <= n <= span.last + CONTEXT_LINES + for p, n in secrets + ) + + +def link_site(scan: Scan, via_change: str | None) -> Span | None: + """The span a change link opens with; None when it opens with no file:line.""" + matched = LINK_SITE.match(via_change or "") + if not matched: + return None + first, last = sorted((int(matched[2]), int(matched[3] or matched[2]))) + return Span(repository_file(scan.prefix, file=matched[1]), first, last) + + def secret_lines(home: str, credential: Finding, texts: Mapping[str, str]) -> set[tuple[str, int]]: """Every (repository path, line) of `texts` on which the `credential` finding's quote occurs. @@ -306,12 +338,7 @@ def location(finding: Finding, scan: Scan) -> dict[str, object]: def repository_path(scan: Scan, finding: Finding) -> str: """The finding's file relative to the repository top level, with any leading climb folded.""" - return repository_file(scan, finding["file"]) - - -def repository_file(scan: Scan, file: str) -> str: - """A scan-root-relative `file`, as file_field carries it, made repository-relative.""" - return posixpath.normpath(scan.prefix + file) + return repository_file(scan.prefix, file=finding["file"]) def uri_bytes(text: str) -> bytes: diff --git a/plugins/claude-security/scripts/lib/secret.py b/plugins/claude-security/scripts/lib/secret.py index 67f4d0f4..df061c2e 100644 --- a/plugins/claude-security/scripts/lib/secret.py +++ b/plugins/claude-security/scripts/lib/secret.py @@ -1,12 +1,15 @@ -"""The snippet of a hard-coded credential finding, withheld from what the products carry. +"""A hard-coded credential finding's snippet and link to the change, withheld from the products. The line such a finding quotes is the credential itself, and the JSONL and SARIF files exist to leave the machine (a code scanning upload, a CI artifact), so neither file quotes it: the finding's file, line and symbol still locate the code, and the SARIF result's message says why no line is -quoted. Only the emitted copy changes: the finding is still placed on the -snippet as the researcher quoted it, and neither its id nor that of a -finding placed near it hashes the credential's line. +quoted. A change scan's link to the change (via_change) describes that same +line in the researcher's words, so it goes with the snippet: here for the +credential finding, in sarif.placed for a finding near the credential's line +or whose link opens there. Only the emitted copy changes: the finding is still +placed on the snippet as the researcher quoted it, and neither its id nor that +of a finding placed near it hashes the credential's line. """ from __future__ import annotations @@ -28,10 +31,13 @@ def is_credential_cwe(number: int) -> bool: def is_credential(finding: Finding) -> bool: - """Whether the finding's CWE rolls up to Use of Hard-coded Credentials.""" - return is_credential_cwe(cwe.id_number(finding["cwe_id"])) + """Whether any CWE the finding carries rolls up to Use of Hard-coded Credentials.""" + ids = (finding["cwe_id"], *finding["other_cwe_ids"]) + return any(is_credential_cwe(cwe.id_number(cwe_id)) for cwe_id in ids) def withheld(finding: Record) -> Record: - """`finding` as the products carry it: a hard-coded credential's snippet is empty.""" - return {**finding, "snippet": ""} if is_credential(finding) else finding + """`finding` as the products carry it: a hard-coded credential's snippet and link withheld.""" + if not is_credential(finding): + return finding + return {**finding, "snippet": "", "via_change": None} diff --git a/plugins/claude-security/scripts/lib/strictjson.py b/plugins/claude-security/scripts/lib/strictjson.py index 91d4ee30..b1b6f267 100644 --- a/plugins/claude-security/scripts/lib/strictjson.py +++ b/plugins/claude-security/scripts/lib/strictjson.py @@ -15,9 +15,11 @@ import re from collections.abc import Mapping from typing import TYPE_CHECKING, NoReturn, cast +# pyright: reportMissingModuleSource=false if TYPE_CHECKING: from pathlib import Path - from typing import TypeGuard + + from typing_extensions import TypeGuard JsonMap = Mapping[str, object] @@ -65,14 +67,18 @@ def _finite(digits: str) -> float: return value +def loads(document: str) -> object: + """The JSON value in `document`; ValueError if not strict JSON.""" + try: + return cast("object", json.loads(document, parse_constant=_refuse, parse_float=_finite)) + except RecursionError as error: + msg = "nested too deeply" + raise ValueError(msg) from error + + def load(path: Path) -> object: """The JSON value in `path`; OSError if unreadable, ValueError if not strict JSON.""" - with path.open(encoding="utf-8") as handle: - try: - return cast("object", json.load(handle, parse_constant=_refuse, parse_float=_finite)) - except RecursionError as error: - msg = "nested too deeply" - raise ValueError(msg) from error + return loads(path.read_text(encoding="utf-8")) def text(value: object, indent: int | None = None) -> str: diff --git a/plugins/claude-security/scripts/patch_artifacts.py b/plugins/claude-security/scripts/patch_artifacts.py index ad5248f1..9cde6b18 100755 --- a/plugins/claude-security/scripts/patch_artifacts.py +++ b/plugins/claude-security/scripts/patch_artifacts.py @@ -1,8 +1,14 @@ #!/usr/bin/env python3 -"""Render the suggested-fix products from a patch run directory. +"""Prepare a patch run, and render the suggested-fix products from it. -Reads the run's `patches.json` and raw `F<n>.diff` files, and writes into the -report's `patches/` directory: +`--prepare` lays out a patch run for a report: it checks the repository root +and the base revision, makes the run's working directory and the report's +`patches/` directory, writes one `findings/F<n>.json` per selected finding +(the report's record, its `file` made repository-relative), and prints the two +directories and the selected ids. + +The render form reads the run's `patches.json` and raw `F<n>.diff` files, and +writes into the report's `patches/` directory: * `F<n>.patch` -- the raw diff behind an explanatory comment header; * `F<n>.md` -- a short note per finding, whether or not a patch was written; @@ -11,10 +17,11 @@ report's `patches/` directory: Each written patch is checked read-only against the repository with `git apply --check`, and the whole patch run directory -- scratch workspaces, -raw diffs and the record -- is removed once the products are written, along -with the run directory above it when nothing else remains there. +prepared findings, raw diffs and the record -- is removed once the products are +written, along with the run directory above it when nothing else remains there. Usage: + patch_artifacts.py --prepare <report_dir> <selection> --repo-root <dir> --base <sha> patch_artifacts.py <patch_dir> <patches_dir> <scan_root> --base <sha> patch_artifacts.py --remove-scratch <workspace> @@ -26,6 +33,7 @@ Python 3.9-compatible, stdlib only. from __future__ import annotations import argparse +import functools import os import re import shlex @@ -33,28 +41,41 @@ import shutil import stat import subprocess import sys +from collections import Counter +from contextlib import suppress +from datetime import datetime, timezone +from enum import Enum from pathlib import Path -from typing import TYPE_CHECKING, TypedDict +from typing import TYPE_CHECKING, NamedTuple, TypedDict # The lib/ package lives next to this script. Python normally adds a script's own # directory to the import path, but not under -P or PYTHONSAFEPATH, so we add it here. sys.path.insert(0, str(Path(__file__).resolve().parent)) -from lib import absolute, console, plugin, strictjson -from lib.strictjson import JsonMap, is_list, is_map, is_str +from lib import absolute, console, git, plugin, strictjson +from lib.finding import Severity, repository_file, scan_prefix_shaped +from lib.link import is_link +from lib.strictjson import JsonMap, is_int, is_list, is_map, is_str if TYPE_CHECKING: from collections.abc import Callable from types import TracebackType - from typing import NoReturn + from typing import Literal FINDING_ID_PATTERN = "F[0-9]{1,9}" FINDING_ID_RE = re.compile(rf"^{FINDING_ID_PATTERN}\Z") + + +def finding_number(finding_id: str) -> int: + """The number in a finding id, for sorting ids as a reader expects (F2 before F10).""" + return int(finding_id[1:]) + + REGULAR_FILE_MODE = "100644" -# \Z, not $: `$` also matches before a trailing newline, and this is a fence. -REPORT_DIR_RE = re.compile(rf"^{re.escape(plugin.REPORT_DIR_PREFIX)}[0-9][0-9-]*\Z") PATCHES_DIR_NAME = "patches" +FINDINGS_DIR_NAME = "findings" SCRATCH_NAME_RE = re.compile(rf"^scratch-{FINDING_ID_PATTERN}\Z") -PATCH_DIR_RE = re.compile(r"^patch-[0-9][0-9-]*\Z") +PATCH_DIR_PREFIX = "patch-" +PATCH_DIR_RE = re.compile(rf"^{re.escape(PATCH_DIR_PREFIX)}[0-9][0-9-]*\Z") DIFF_HEADER = "diff --git " CLAIM_KEYS = ("targeted", "no_new_vulnerability", "behaviour_unchanged") CLAIM_LABELS = { @@ -67,7 +88,11 @@ CLAIM_LABELS = { } CLAIM_STATES = ("CONFIDENT", "NOT_CONFIDENT", "UNSURE") STATUSES = ("patch_written", "declined", "skipped_stale") -GIT_ENV = dict(os.environ, GIT_TERMINAL_PROMPT="0") +NOT_CONFIRMED = ( + "The review found this finding is not exploitable as the report describes at this " + "revision, so no patch was written for it." +) +UNTESTED_NOTICE = "no project test of the patched code was run" class Claim(TypedDict): @@ -77,12 +102,38 @@ class Claim(TypedDict): evidence: str +class PathKind(str, Enum): + """The kind the fresh reviewer gave an attack path it reported.""" + + OPENED = "opened" + STILL_REACHABLE = "still_reachable" + SET_ASIDE = "set_aside" + + @property + def blocks_patch(self) -> bool: + return self is not PathKind.SET_ASIDE + + +PATH_KIND_LABELS = { + PathKind.OPENED: "opened by the rejected change", + PathKind.STILL_REACHABLE: "the finding's exploit, still reachable by another route", + PathKind.SET_ASIDE: "set aside as outside this finding; not addressed here", +} + + +class AttackPath(TypedDict): + """An attack path the fresh reviewer reported, with the kind it gave it.""" + + kind: PathKind + text: str + + class DiffStat(TypedDict): - """Per-file added/deleted line counts.""" + """Per-file added/deleted line counts, "-" for a binary file as git prints it.""" path: str - added: object - deleted: object + added: int | Literal["-"] + deleted: int | Literal["-"] class Unit(TypedDict): @@ -96,12 +147,15 @@ class Unit(TypedDict): untested: bool tests_run: str reviewed_paths: list[str] + attack_paths: list[AttackPath] + attempts: int | None + confirmed: bool | None decline_reason: str recommendation: str -class Args(argparse.Namespace): - """The parsed command line.""" +class RenderArgs(argparse.Namespace): + """The parsed render command line.""" patch_dir: str = "" patches_dir: str = "" @@ -109,20 +163,30 @@ class Args(argparse.Namespace): base: str = "" -class PatchError(Exception): - """The run record or a raw diff is malformed; the caller must correct it.""" +class PrepareArgs(argparse.Namespace): + """The parsed `--prepare` command line.""" + + report_dir: str = "" + selection: str = "" + repo_root: str = "" + base: str = "" + + +class RemoveArgs(argparse.Namespace): + """The parsed `--remove-scratch` command line.""" + + workspace: str = "" -def die(message: str) -> NoReturn: - """A refusal: the inputs are well-formed arguments but bad data. Exits 1.""" - sys.stderr.write(f"patch_artifacts.py: {message}\n") - sys.exit(1) +class ReportFinding(NamedTuple): + """A report finding as `--prepare` reads it: its severity, and its record to hand on.""" + severity: Severity + record: JsonMap -def die_usage(message: str) -> NoReturn: - """A usage error: the arguments themselves are wrong. Exits 2.""" - sys.stderr.write(f"patch_artifacts.py: {message}\n") - sys.exit(2) + +class PatchError(Exception): + """A refusal; the message names what the caller must correct.""" def field(value: object, what: str) -> str: @@ -139,7 +203,7 @@ def field(value: object, what: str) -> str: def line_field(value: object, what: str) -> str: - """A record field for the patch's one-line "#" header; line breaks folded to spaces.""" + """A one-line record field; line breaks folded to spaces.""" return field(value, what).replace("\r", " ").replace("\n", " ") @@ -190,6 +254,84 @@ def build_claims(raw: object, unit_id: str, status: str) -> dict[str, Claim]: return out +def build_attack_path(item: object, what: str) -> AttackPath: + """One of the fresh reviewer's attack paths: a known kind and a non-empty text.""" + if not is_map(item): + msg = f"{what} is not an object with a kind and a text" + raise PatchError(msg) + try: + kind = PathKind(field(item.get("kind"), f"{what}.kind")) + except ValueError as error: + kinds = ", ".join(k.value for k in PathKind) + msg = f"{what} kind {item.get('kind')!r} is not one of {kinds}" + raise PatchError(msg) from error + text = line_field(item.get("text"), f"{what}.text").strip() + if not text: + msg = f"{what} has no text saying what the path is" + raise PatchError(msg) + return AttackPath(kind=kind, text=text) + + +def build_attack_paths(raw: object, unit_id: str, status: str) -> list[AttackPath]: + """Validate the fresh reviewer's attack paths; a written patch lists them, none blocking it.""" + written = status == "patch_written" + if raw is None: + if written: + msg = ( + f'{unit_id}: status is patch_written but "attack_paths" is missing -- it must ' + "list what the fresh reviewer reported, or be empty when it reported none." + ) + raise PatchError(msg) + return [] + if not is_list(raw): + msg = f"{unit_id}: attack_paths must be a list" + raise PatchError(msg) + paths = [build_attack_path(item, f"{unit_id} attack_paths[{i}]") for i, item in enumerate(raw)] + blocking = next((path for path in paths if path["kind"].blocks_patch), None) + if written and blocking is not None: + msg = ( + f"{unit_id}: status is patch_written but the fresh reviewer reported a path it did not " + f"set aside ({blocking['kind'].value}: {blocking['text']}) -- that blocks the " + "patch: record the unit as declined, or, if a later round's reviewer reported no " + "path that counts, leave this earlier round's path out of the record." + ) + raise PatchError(msg) + return paths + + +def build_attempts(raw: object, unit_id: str, status: str) -> int | None: + """The number of fix attempts made; None for a stale unit, whatever its record says.""" + if status == "skipped_stale": + return None + if raw is None: + msg = ( + f'{unit_id}: "attempts" is missing -- it must say how many fix attempts were made ' + "(1, or 2 for a unit that went through the revision round; 0 only when its workspace " + "could not be opened)." + ) + raise PatchError(msg) + if not is_int(raw) or raw < 0: + msg = f'{unit_id}: "attempts" must be a whole number of fix attempts made' + raise PatchError(msg) + if status == "patch_written" and raw == 0: + msg = f"{unit_id}: a written patch took at least one attempt; attempts cannot be 0" + raise PatchError(msg) + return raw + + +def build_confirmed(raw: object, unit_id: str, status: str) -> bool | None: + """The verifier's word on whether the finding is real; None if unstated or for a stale unit.""" + if raw is None or status == "skipped_stale": + return None + if not isinstance(raw, bool): + msg = f'{unit_id}: "confirmed" must be true or false' + raise PatchError(msg) + if not raw and status != "declined": + msg = f'{unit_id}: "confirmed" is false, so the unit must be declined: no patch for it' + raise PatchError(msg) + return raw + + def build_unit(item: object, index: int) -> Unit: """Validate one unit from patches.json into the shape the writers use.""" if not is_map(item): @@ -208,12 +350,23 @@ def build_unit(item: object, index: int) -> Unit: if status != "patch_written" and not decline_reason: msg = f"{unit_id}: status {status} needs a decline_reason saying why no patch was written" raise PatchError(msg) + attack_paths = build_attack_paths(item.get("attack_paths"), unit_id, status) + confirmed = build_confirmed(item.get("confirmed"), unit_id, status) + reachable = next((p for p in attack_paths if p["kind"] is PathKind.STILL_REACHABLE), None) + if confirmed is False and reachable is not None: + msg = ( + f'{unit_id}: "confirmed": false cannot sit beside a still_reachable path ' + f"({reachable['text']}) -- if that path reaches the function or line the finding " + 'names, the panel disagreed: drop "confirmed" and decline on that path; if it ' + "reaches only other code, the refutation stands: record that path's kind as set_aside" + ) + raise PatchError(msg) untested = item.get("untested") if untested is None and status == "patch_written": msg = ( f'{unit_id}: status is patch_written but "untested" is missing -- it must ' "say (true/false) whether the project's own tests exercise the patched " - "code, because the patch header tells the reader exactly that." + "code, because the patch header warns the reader when they do not." ) raise PatchError(msg) if untested is not None and not isinstance(untested, bool): @@ -228,16 +381,22 @@ def build_unit(item: object, index: int) -> Unit: untested=untested is True, tests_run=line_field(item.get("tests_run"), f"{unit_id} tests_run"), reviewed_paths=field_list(item.get("reviewed_paths"), f"{unit_id} reviewed_paths"), + attack_paths=attack_paths, + attempts=build_attempts(item.get("attempts"), unit_id, status), + confirmed=confirmed, decline_reason=decline_reason, recommendation=field(item.get("recommendation"), f"{unit_id} recommendation"), ) def load_units(patch_dir: Path) -> list[Unit]: - """Read and validate patches.json (an object with a `units` array).""" + """Read and validate patches.json (an object with a `units` array) against the prepared units. + + Every unit id must have the `findings/<id>.json` that `--prepare` laid out. + """ try: raw = strictjson.load(patch_dir / "patches.json") - except OSError as error: + except FileNotFoundError as error: msg = "patches.json is missing from the patch directory. Write it before running this." raise PatchError(msg) from error except ValueError as error: @@ -248,12 +407,26 @@ def load_units(patch_dir: Path) -> list[Unit]: msg = 'patches.json must be an object with a "units" array' raise PatchError(msg) units = [build_unit(item, i) for i, item in enumerate(units_raw)] - seen: set[str] = set() - for unit in units: - if unit["id"] in seen: - msg = f"{unit['id']} appears more than once in patches.json" - raise PatchError(msg) - seen.add(unit["id"]) + counted = Counter(unit["id"] for unit in units) + repeated = sorted( + (unit_id for unit_id, count in counted.items() if count > 1), key=finding_number + ) + if repeated: + msg = f"patches.json uses these unit ids more than once: {', '.join(repeated)}" + raise PatchError(msg) + findings_dir = patch_dir / FINDINGS_DIR_NAME + if not os.path.isdir(findings_dir): + msg = f"the patch dir has no {FINDINGS_DIR_NAME}/ folder; run --prepare first" + raise PatchError(msg) + prepared = {path.stem for path in findings_dir.glob("*.json") if FINDING_ID_RE.match(path.stem)} + unprepared = [unit["id"] for unit in units if unit["id"] not in prepared] + if unprepared: + msg = ( + f"patches.json names {', '.join(unprepared)}, which --prepare did not lay out; " + f"this run's units are {', '.join(sorted(prepared, key=finding_number)) or 'none'} " + "(the ids --prepare printed)" + ) + raise PatchError(msg) return units @@ -351,21 +524,7 @@ def numstat(diff: bytes) -> list[DiffStat]: def git_toplevel(scan_root: str) -> str | None: """The repository root containing scan_root, or None when git can't say.""" - try: - out = subprocess.run( - ["git", "-C", scan_root, "rev-parse", "--show-toplevel"], - env=GIT_ENV, - stdout=subprocess.PIPE, - stderr=subprocess.DEVNULL, - timeout=30, - check=False, - ) - except (OSError, subprocess.SubprocessError): - return None - if out.returncode != 0: - return None - top = out.stdout.decode("utf-8", "replace").rstrip("\r\n") - return top or None + return git.run(scan_root, "rev-parse", "--show-toplevel") or None def apply_check(top: str | None, patch_path: Path) -> str: @@ -375,7 +534,7 @@ def apply_check(top: str | None, patch_path: Path) -> str: try: out = subprocess.run( ["git", "-C", top, "apply", "--check", os.path.abspath(patch_path)], - env=GIT_ENV, + env=git.ENV, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=60, @@ -389,25 +548,42 @@ def apply_check(top: str | None, patch_path: Path) -> str: return "conflicts" + (f": {first[0]}" if first else "") +def line_counts(entry: DiffStat) -> str: + """A file's size in the diffstat: "(+a -d)", or "(binary)" where git counts no lines.""" + if entry["added"] == "-": + return "(binary)" + return f"(+{entry['added']} -{entry['deleted']})" + + def diffstat_lines(stats: list[DiffStat] | None) -> list[str]: """Diffstat as markdown bullets, or a one-line note when there is no diff to size.""" if stats is None: return ["- _(no attempt diff was saved)_"] if not stats: return ["- _(no file changes recorded)_"] - return [f"- `{s['path']}` (+{s['added']} -{s['deleted']})" for s in stats] + return [f"- `{s['path']}` {line_counts(s)}" for s in stats] + + +def attack_path_lines(paths: list[AttackPath]) -> list[str]: + """The fresh reviewer's attack paths as a note section; no lines when it reported none.""" + if not paths: + return [] + bullets = [f"- **{PATH_KIND_LABELS[path['kind']]}** -- {path['text']}" for path in paths] + return ["## What the fresh reviewer reported", "", *bullets, ""] def header_comment(unit: Unit, base: str, report_ref: str) -> str: """The comment block prepended above the first `diff --git`; git apply ignores it.""" + short = base[: plugin.SHORT_ID_CHARS] lines = [ f"# Claude Security -- suggested patch for {unit['id']}: {unit['title']}", - f"# Applies to revision {base[:12]} (the revision the scan report describes).", + f"# Applies to revision {short} (the revision these patches were built against).", "#", "# Verified by a panel of agents: an independent verifier reviewed this", - "# change against the finding, and a second, fresh reviewer re-challenged", - "# the bare diff for new vulnerabilities. The patch was written only", - "# because the panel stated all three of these with confidence:", + "# change against the finding, and a second, fresh reviewer challenged the", + "# diff for an attack path it opens, or a route it leaves open to the", + "# finding's exploit. The patch was written only because the panel stated", + "# all three of these with confidence:", ] for key in CLAIM_KEYS: claim = unit["claims"][key] @@ -415,9 +591,9 @@ def header_comment(unit: Unit, base: str, report_ref: str) -> str: if unit["untested"]: lines += [ "#", - "# NOTE: no test exercises the patched code. The claim that behaviour is", - "# unchanged rests on review of the change and its callers, not on a test", - "# run -- weigh it accordingly before applying.", + f"# NOTE: {UNTESTED_NOTICE}. The claim that", + "# behaviour is unchanged rests on review of the change and its callers,", + "# not on a test run -- weigh it accordingly before applying.", ] if unit["summary"]: lines += ["#", f"# {unit['summary']}"] @@ -442,9 +618,10 @@ def note_written(unit: Unit, stats: list[DiffStat] | None, check: str, report_re ( "**Verified by a panel of agents.** An independent verifier reviewed the " "change against the finding and stated the three claims below with " - "confidence, and a second, fresh reviewer re-challenged the bare diff " - "for new vulnerabilities. The patch was written only because the " - "panel could vouch for it; nothing here was applied for you." + "confidence, and a second, fresh reviewer challenged the diff for an " + "attack path it opens, or a route it leaves open to the finding's exploit. " + "The patch was written only because the panel could vouch for it; nothing " + "here was applied for you." ), "", ] @@ -458,14 +635,14 @@ def note_written(unit: Unit, stats: list[DiffStat] | None, check: str, report_re lines += [ "", ( - "**No test exercises the patched code.** The behaviour claim rests on " - "review of the change and its callers, not on a test run." + f"**{UNTESTED_NOTICE[:1].upper()}{UNTESTED_NOTICE[1:]}.** The behaviour claim " + "rests on review of the change and its callers, not on a test run." ), ] lines += ["", f"**Tests run:** {unit['tests_run'] or 'none recorded'}", ""] lines += ["## Change", ""] lines += diffstat_lines(stats) - lines += ["", "## Applying it", ""] + lines += ["", *attack_path_lines(unit["attack_paths"]), "## Applying it", ""] if check == "clean": lines.append("Applies cleanly to the working tree (checked with `git apply --check`).") elif check == "not_run": @@ -490,6 +667,24 @@ def note_written(unit: Unit, stats: list[DiffStat] | None, check: str, report_re return "\n".join(lines) +def decline_wording(unit: Unit) -> tuple[str, str] | None: + """A declined unit's outcome as (note sentence, index parenthesis); None for a stale unit.""" + count = unit["attempts"] + if count is None: + return None + if unit["confirmed"] is False: + return NOT_CONFIRMED, "finding not confirmed at this revision" + if count == 0: + sentence = "No fix for this finding could be attempted, so no patch was written." + return sentence, "no attempt possible" + made = "1 attempt" if count == 1 else f"{count} attempts" + sentence = ( + f"After {made}, no fix for this finding was produced that passed the panel's review, " + "so no patch was written." + ) + return sentence, f"no fix passed review in {made}" + + def note_declined(unit: Unit, stats: list[DiffStat] | None) -> str: """The F<n>.md note for a finding with no patch.""" lines = [ @@ -497,15 +692,17 @@ def note_declined(unit: Unit, stats: list[DiffStat] | None) -> str: "", "**Status:** no patch produced", "", + *([wording[0], ""] if (wording := decline_wording(unit)) else []), unit["decline_reason"], "", ] blocking = [(k, c) for k, c in unit["claims"].items() if c["state"] != "CONFIDENT"] if blocking: - lines += ["## The claim that could not be made with confidence", ""] + lines += ["## What could not be claimed with confidence", ""] for key, claim in blocking: lines.append(f"- **{CLAIM_LABELS[key]}** -- {claim['state']}: {claim['evidence']}") lines.append("") + lines += attack_path_lines(unit["attack_paths"]) if stats is not None: lines += ["## What the rejected attempt changed", ""] lines += diffstat_lines(stats) @@ -519,12 +716,13 @@ def index_markdown(units: list[Unit], base: str, report_dir_name: str, report_re """PATCHES.md: the one-page index of every unit's outcome.""" patched = [u for u in units if u["status"] == "patch_written"] declined = [u for u in units if u["status"] != "patch_written"] + short = base[: plugin.SHORT_ID_CHARS] lines = [ "# Suggested patches", "", ( f"Targeted patches for findings in `{report_dir_name}`, each written against " - f"revision `{base[:12]}` and verified by a panel of agents before it was " + f"revision `{short}` and verified by a panel of agents before it was " "written. Nothing here is applied, committed, or opened as a pull request " "until you choose to do so." ), @@ -533,14 +731,35 @@ def index_markdown(units: list[Unit], base: str, report_dir_name: str, report_re if patched: lines += ["## Patches written", ""] for unit in patched: - caveat = " _(no tests cover the patched code)_" if unit["untested"] else "" + caveat = f" _({UNTESTED_NOTICE})_" if unit["untested"] else "" lines.append(f"- **{unit['id']}** -- {unit['title']}: `{unit['id']}.patch`{caveat}") lines.append("") if declined: lines += ["## No patch produced", ""] for unit in declined: - lines.append(f"- **{unit['id']}** -- {unit['title']}: {unit['decline_reason']}") + wording = decline_wording(unit) + suffix = f" ({wording[1]})" if wording else "" + lines.append(f"- **{unit['id']}** -- {unit['title']}{suffix}: {unit['decline_reason']}") lines.append("") + aside = [ + (unit["id"], path) + for unit in units + for path in unit["attack_paths"] + if path["kind"] is PathKind.SET_ASIDE + ] + if aside: + lines += ["## Set aside by the reviewers", ""] + lines += [f"- while reviewing **{unit_id}** -- {path['text']}" for unit_id, path in aside] + lines += [ + "", + ( + "Each of these was seen while reviewing the finding named beside it and was " + "set aside as outside that finding, so nothing written for that finding " + "addresses it. Unless another finding here covers it, review it yourself, or " + "ask Claude Security to scan or patch it." + ), + "", + ] lines += [ "## Applying a patch", "", @@ -568,9 +787,8 @@ def jsonl( checks: dict[str, str], ) -> str: """patches.jsonl: one record per unit, machine-readable for tooling.""" - rows: list[str] = [] - for unit in units: - record: dict[str, object] = { + return "".join( + strictjson.text({ "id": unit["id"], "status": unit["status"], "base": base, @@ -580,12 +798,16 @@ def jsonl( "untested": unit["untested"], "tests_run": unit["tests_run"] or None, "reviewed_paths": unit["reviewed_paths"], + "attack_paths": unit["attack_paths"], + "attempts": unit["attempts"], + "confirmed": unit["confirmed"], "diffstat": stats_by_id.get(unit["id"]), "apply_check": checks.get(unit["id"]), "decline_reason": unit["decline_reason"] or None, - } - rows.append(strictjson.text(record)) - return "\n".join(rows) + ("\n" if rows else "") + }) + + "\n" + for unit in units + ) def clear_stale_products(patches_dir: Path, produced: set[str]) -> list[str]: @@ -645,7 +867,7 @@ def resolve_report_dir(patches_dir: Path) -> Path: f"report directory; got {patches_abs}" ) raise PatchError(msg) - if not REPORT_DIR_RE.match(report_dir.name): + if not plugin.REPORT_DIR_RE.match(report_dir.name): msg = ( "patches dir must live inside a CLAUDE-SECURITY-<timestamp> report " f"directory; its parent is {report_dir.name!r}. Refusing rather than " @@ -655,7 +877,136 @@ def resolve_report_dir(patches_dir: Path) -> Path: return report_dir -def run(patch_dir: Path, patches_dir: Path, scan_root: str, base: str) -> int: +def stamp_scan_prefix(report_dir: Path) -> str: + """The `scan_prefix` recorded in the report's one revision stamp.""" + stamps = [path for path in report_dir.iterdir() if plugin.is_revision_stamp(path)] + if len(stamps) != 1: + msg = ( + f"the report directory must hold exactly one {plugin.REVISION_PREFIX}*.json " + f"stamp; {report_dir.name} holds {len(stamps)}" + ) + raise PatchError(msg) + try: + stamp = strictjson.load(stamps[0]) + except ValueError as error: + msg = f"{stamps[0].name} is not valid JSON: {error}" + raise PatchError(msg) from error + prefix = stamp.get("scan_prefix") if is_map(stamp) else None + if not is_str(prefix) or not scan_prefix_shaped(prefix): + msg = f"{stamps[0].name} scan_prefix {prefix!r} is not a path prefix" + raise PatchError(msg) + return prefix + + +def report_findings(report_dir: Path, scan_prefix: str) -> dict[str, ReportFinding]: + """The report's findings by id, in report order, each `file` made repository-relative.""" + name = plugin.JSONL_NAME + try: + lines = (report_dir / name).read_text(encoding="utf-8").splitlines() + except FileNotFoundError as error: + msg = f"{name} is missing from the report directory" + raise PatchError(msg) from error + except ValueError as error: + msg = f"{name} is not UTF-8 text: {error}" + raise PatchError(msg) from error + findings: dict[str, ReportFinding] = {} + for number, line in enumerate(lines, 1): + if not line.strip(): + continue + try: + record = strictjson.loads(line) + except ValueError as error: + msg = f"{name} line {number} is not valid JSON: {error}" + raise PatchError(msg) from error + if not is_map(record): + msg = f"{name} line {number} is not a finding object" + raise PatchError(msg) + finding_id = field(record.get("id"), f"{name} line {number} id") + if not FINDING_ID_RE.match(finding_id): + msg = f"{name} line {number}: id {finding_id!r} is not a finding id" + raise PatchError(msg) + if finding_id in findings: + msg = f"{finding_id} appears more than once in {name}" + raise PatchError(msg) + severity = field(record.get("severity"), f"{finding_id} severity") + if severity not in Severity.__members__: + msg = f"{name} line {number}: {finding_id} severity {severity!r} is not a severity" + raise PatchError(msg) + declared = field(record.get("file"), f"{finding_id} file") + file = repository_file(scan_prefix, file=declared) + off_shape = not declared or declared.startswith("/") or "\\" in declared + if off_shape or file.split("/")[0] in {".", ".."}: + msg = f"{name} line {number}: {finding_id} file {declared!r} is not a repository path" + raise PatchError(msg) + findings[finding_id] = ReportFinding(Severity[severity], {**record, "file": file}) + return findings + + +def select_units(findings: dict[str, ReportFinding], selection: str) -> list[str]: + """The ids `selection` names -- `all`, `high`, or ids like `F1,F3` -- in report order.""" + if selection == "all": + chosen = set(findings) + elif selection == "high": + chosen = {i for i, finding in findings.items() if finding.severity >= Severity.HIGH} + else: + chosen = {part.strip() for part in selection.split(",")} + malformed = sorted(i for i in chosen if not FINDING_ID_RE.match(i)) + if malformed: + msg = ( + f"selection {selection!r}: {', '.join(map(repr, malformed))} is not a finding id " + "(F<number>, at most 9 digits); a selection is all, high, or ids like F1,F3" + ) + raise PatchError(msg) + unknown = sorted(chosen - findings.keys(), key=finding_number) + if unknown: + msg = f"{', '.join(unknown)} is not a finding in the report's {plugin.JSONL_NAME}" + raise PatchError(msg) + ids = [i for i in findings if i in chosen] + if not ids: + msg = f"nothing to patch: no finding in the report matches the selection {selection!r}" + raise PatchError(msg) + return ids + + +def prepare(report_dir: Path, *, selection: str, repo_root: str, base: str) -> int: + """Lay out a patch run for the selected findings; print its directories and unit ids.""" + report_dir = Path(os.path.abspath(report_dir)) + if not plugin.REPORT_DIR_RE.match(report_dir.name): + msg = f"{report_dir.name!r} is not a CLAUDE-SECURITY-<timestamp> report directory" + raise PatchError(msg) + top = git_toplevel(repo_root) + if top is None: + msg = f"--repo-root {repo_root!r}: git names no repository there" + raise PatchError(msg) + if not Path(repo_root).samefile(top): + msg = f"--repo-root {repo_root!r} is not the top level of its repository; git names {top}" + raise PatchError(msg) + if git.run(repo_root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}") is None: + msg = f"--base {base}: git cannot resolve it to a commit in {repo_root}" + raise PatchError(msg) + findings = report_findings(report_dir, stamp_scan_prefix(report_dir)) + ids = select_units(findings, selection) + started = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S") + patch_dir = report_dir / plugin.RUN_DIR_NAME / f"{PATCH_DIR_PREFIX}{started}" + try: + patch_dir.mkdir(parents=True) + except FileExistsError as error: + msg = f"{patch_dir} already exists (a run prepared this same second); run this again" + raise PatchError(msg) from error + findings_dir = patch_dir / FINDINGS_DIR_NAME + findings_dir.mkdir() + patches_dir = report_dir / PATCHES_DIR_NAME + patches_dir.mkdir(exist_ok=True) + for unit_id in ids: + text = strictjson.text(findings[unit_id].record, indent=2) + "\n" + (findings_dir / f"{unit_id}.json").write_bytes(text.encode()) + print(f"patch_dir: {patch_dir}") + print(f"patches_dir: {patches_dir}") + print(f"units: {strictjson.text(ids)}") + return 0 + + +def render(patch_dir: Path, patches_dir: Path, scan_root: str, base: str) -> int: units = load_units(patch_dir) report_dir = resolve_report_dir(patches_dir) top = git_toplevel(scan_root) @@ -671,7 +1022,7 @@ def run(patch_dir: Path, patches_dir: Path, scan_root: str, base: str) -> int: if written and diff is not None: patch_path = patches_dir / f"{unit['id']}.patch" header = header_comment(unit, base, report_ref) - patch_path.write_bytes(header.encode() + diff) + patch_path.write_bytes(header.encode("utf-8", "surrogateescape") + diff) check = apply_check(top, patch_path) checks[unit["id"]] = check note = note_written(unit, stats, check, report_ref) @@ -680,10 +1031,10 @@ def run(patch_dir: Path, patches_dir: Path, scan_root: str, base: str) -> int: else: note = note_declined(unit, stats) print(f"{unit['id']}: no patch ({unit['status']}) -> {unit['id']}.md") - (patches_dir / f"{unit['id']}.md").write_bytes(note.encode()) + (patches_dir / f"{unit['id']}.md").write_bytes(note.encode("utf-8", "surrogateescape")) produced.add(f"{unit['id']}.md") index = index_markdown(units, base, report_dir.name, report_ref) - (patches_dir / "PATCHES.md").write_bytes(index.encode()) + (patches_dir / "PATCHES.md").write_bytes(index.encode("utf-8", "surrogateescape")) (patches_dir / "patches.jsonl").write_bytes(jsonl(units, base, stats_by_id, checks).encode()) for name in clear_stale_products(patches_dir, produced): print(f"removed stale {name} (not produced by this run)") @@ -712,6 +1063,23 @@ def run(patch_dir: Path, patches_dir: Path, scan_root: str, base: str) -> int: return 0 +def misplaced_patch_run_reason(patch_dir: Path) -> str | None: + """Why `patch_dir` is not where a patch run lives, or None when it is: + `<report>/.claude-security-run/patch-<ts>`, none of the three a symbolic link.""" + run_dir = patch_dir.parent + report_dir = run_dir.parent + if not PATCH_DIR_RE.match(patch_dir.name): + return f"'{patch_dir.name}' is not named patch-<timestamp>" + if run_dir.name != plugin.RUN_DIR_NAME: + return f"'{patch_dir.name}' is not inside {plugin.RUN_DIR_NAME}/" + if not plugin.REPORT_DIR_RE.match(report_dir.name): + return f"'{report_dir.name}' is not a CLAUDE-SECURITY-<timestamp> report directory" + for directory in (patch_dir, run_dir, report_dir): + if is_link(directory): + return f"'{directory}' is a symbolic link" + return None + + def refuse_reason(path: Path) -> str | None: """Why `path` may NOT be deleted as a scratch workspace, or None when it may. @@ -719,30 +1087,47 @@ def refuse_reason(path: Path) -> str | None: own `.git` may be deleted; every other shape is refused. """ leaf = Path(os.path.abspath(path)) + if is_link(leaf): + return "it is a symbolic link" if not os.path.isdir(leaf): return "it is not a directory" if not SCRATCH_NAME_RE.match(leaf.name): return "its name is not scratch-F<n>" - if not PATCH_DIR_RE.match(leaf.parent.name): - return "it is not inside a patch-<timestamp> run directory" - if leaf.parents[1].name != plugin.RUN_DIR_NAME: - return f"its run directory is not inside {plugin.RUN_DIR_NAME}/" - if not os.path.isdir(leaf / ".git"): + if reason := misplaced_patch_run_reason(leaf.parent): + return reason + dot_git = leaf / ".git" + if is_link(dot_git) or not os.path.isdir(dot_git): return "it holds no .git directory of its own" return None -def clear_readonly( +def retry_removal( + root: str, func: Callable[..., object], path: str, exc_info: tuple[type[BaseException], BaseException, TracebackType], ) -> None: - """Make `path` writable and retry the removal rmtree could not do.""" - # Git writes read-only objects, which Windows will not delete. + """Retry a removal rmtree could not do, after making the entry deletable. + + On Windows that is the entry's read-only bit (never a symlink's); on POSIX the owner write bit + of its parent, granted only to a directory (never a symlink) inside `root`, the tree being + removed. An entry already gone counts as deleted. + """ + if isinstance(exc_info[1], FileNotFoundError): + return if func not in {os.unlink, os.rmdir}: raise exc_info[1] - Path(path).chmod(stat.S_IWRITE) - func(path) + with suppress(FileNotFoundError): + if os.name == "nt": + if not is_link(path): + Path(path).chmod(stat.S_IWRITE) + else: + parent = Path(os.path.abspath(path)).parent + if os.path.commonpath([root, parent]) == root and not is_link(parent): + mode = parent.stat().st_mode + if not mode & stat.S_IWUSR: + parent.chmod(mode | stat.S_IWUSR) + func(path) def remove_workspace(path: Path) -> None: @@ -751,8 +1136,9 @@ def remove_workspace(path: Path) -> None: if reason is not None: msg = f"refusing to remove '{path}': {reason}" raise PatchError(msg) + root = os.path.abspath(path) try: - shutil.rmtree(os.path.abspath(path), onerror=clear_readonly) + shutil.rmtree(root, onerror=functools.partial(retry_removal, root)) except OSError as error: detail = console.removal_failure_detail(error) msg = f"could not remove '{path}': {detail}" @@ -789,59 +1175,107 @@ def remove_patch_run(patch_dir: Path) -> tuple[list[Path], list[str]]: Returns (removed paths, warnings). Never raises; only the recipe's own `<report>/.claude-security-run/patch-<ts>` layout is deleted. """ - removed: list[Path] = [] target = Path(os.path.abspath(patch_dir)) run_dir = target.parent - if not PATCH_DIR_RE.match(target.name): - return removed, [f"left '{patch_dir}' in place: its name is not patch-<timestamp>"] - if run_dir.name != plugin.RUN_DIR_NAME: - return removed, [f"left '{patch_dir}' in place: it is not inside {plugin.RUN_DIR_NAME}/"] + if reason := misplaced_patch_run_reason(target): + return [], [f"left '{patch_dir}' in place: {reason}"] + root = str(target) try: - shutil.rmtree(str(target), onerror=clear_readonly) + shutil.rmtree(root, onerror=functools.partial(retry_removal, root)) except OSError as error: detail = console.removal_failure_detail(error) - return removed, [f"could not remove '{patch_dir}': {detail}"] - removed.append(target) + return [], [f"could not remove '{patch_dir}': {detail}"] try: run_dir.rmdir() except OSError: - return removed, [] - removed.append(run_dir) - return removed, [] + return [target], [] + return [target, run_dir], [] -def main(argv: list[str]) -> int: - if argv and argv[0] == "--remove-scratch": - if len(argv) != 2: - die_usage("--remove-scratch takes exactly one workspace path") - try: - remove_workspace(Path(argv[1])) - except PatchError as error: - die(str(error)) - print(f"removed workspace {argv[1]!r}") - return 0 +def remove_args(argv: list[str]) -> RemoveArgs: + """The `--remove-scratch` command line, parsed; a usage error exits 2.""" + parser = argparse.ArgumentParser( + prog="patch_artifacts.py --remove-scratch", + description="Delete one fenced scratch workspace.", + allow_abbrev=False, + ) + parser.add_argument("workspace", help="the scratch workspace a patch run made") + return parser.parse_args(argv, namespace=RemoveArgs()) + + +def prepare_args(argv: list[str]) -> PrepareArgs: + """The `--prepare` command line, parsed; a usage error exits 2.""" + parser = argparse.ArgumentParser( + prog="patch_artifacts.py --prepare", + description="Lay out a patch run for a report's selected findings.", + allow_abbrev=False, + ) + parser.add_argument("report_dir", help="the CLAUDE-SECURITY-<timestamp> report directory") + parser.add_argument("selection", help="all, high, or finding ids such as F1,F3") + parser.add_argument("--repo-root", required=True, help="the repository's top-level directory") + parser.add_argument("--base", required=True, help="the revision every patch is built against") + args = parser.parse_args(argv, namespace=PrepareArgs()) + if not os.path.isdir(args.report_dir): + parser.error(f"report dir is not a directory: {args.report_dir}") + if not plugin.SHA_RE.match(args.base): + parser.error(f"--base {args.base!r} is not a hex revision id") + return args + + +def render_args(argv: list[str]) -> RenderArgs: + """The render command line, parsed; a usage error exits 2.""" parser = argparse.ArgumentParser( prog="patch_artifacts.py", description="Render suggested-fix patch files and notes from a patch run directory.", - epilog="Also: --remove-scratch <workspace> deletes one fenced scratch workspace.", + epilog=( + "Also: --prepare <report_dir> <selection> --repo-root <dir> --base <sha> lays out " + "a patch run; --remove-scratch <workspace> deletes one fenced scratch workspace." + ), allow_abbrev=False, ) parser.add_argument("patch_dir", help="the patch run dir holding patches.json and F<n>.diff") parser.add_argument("patches_dir", help="the report's patches/ directory to write into") parser.add_argument("scan_root", help="the user's repository root (for git apply --check)") parser.add_argument("--base", required=True, help="the revision every patch applies to") - args = parser.parse_args(argv, namespace=Args()) + args = parser.parse_args(argv, namespace=RenderArgs()) for label, path in (("patch dir", args.patch_dir), ("patches dir", args.patches_dir)): if not os.path.isdir(path): - die_usage(f"{label} is not a directory: {path}") + parser.error(f"{label} is not a directory: {path}") if not plugin.SHA_RE.match(args.base): - die_usage(f"--base {args.base!r} is not a hex revision id") + parser.error(f"--base {args.base!r} is not a hex revision id") + return args + + +def dispatch(argv: list[str]) -> int: + """Run the form the first argument names. Raises PatchError; a usage error exits 2.""" + if argv and argv[0] == "--remove-scratch": + workspace = remove_args(argv[1:]).workspace + remove_workspace(Path(workspace)) + print(f"removed workspace {workspace!r}") + return 0 + if argv and argv[0] == "--prepare": + wanted = prepare_args(argv[1:]) + return prepare( + Path(wanted.report_dir), + selection=wanted.selection, + repo_root=wanted.repo_root, + base=wanted.base, + ) + args = render_args(argv) + return render(Path(args.patch_dir), Path(args.patches_dir), args.scan_root, args.base) + + +def main(argv: list[str]) -> int: try: - return run(Path(args.patch_dir), Path(args.patches_dir), args.scan_root, args.base) + return dispatch(argv) except PatchError as error: - die(str(error)) + sys.stderr.write(f"patch_artifacts.py: {error}\n") + return 1 except OSError as error: - die(f"could not read or write the report's files: {error}") + sys.stderr.write( + f"patch_artifacts.py: could not read or write the report's files: {error}\n" + ) + return 1 if __name__ == "__main__": diff --git a/plugins/claude-security/scripts/render_report.py b/plugins/claude-security/scripts/render_report.py index c00a8218..d02d3dd0 100755 --- a/plugins/claude-security/scripts/render_report.py +++ b/plugins/claude-security/scripts/render_report.py @@ -40,18 +40,22 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) from lib import absolute, console, cwe, plugin, sarif, secret, source, strictjson from lib.chain import chain_of, pending_ranks from lib.finding import ( - CONFIDENCES, PANEL_KEEP_QUORUM, PANEL_VOTER_COUNT, - SEVERITIES, + Confidence, Finding, FindingError, FindingPathError, Record, + Severity, build_finding, + finding_panels, panel_complete, + scan_prefix_fits, scan_prefix_shaped, + vote_rounds, ) +from lib.link import is_link from lib.strictjson import JsonMap, is_int, is_list, is_map, is_str if TYPE_CHECKING: @@ -93,7 +97,7 @@ class VerificationSummary(_ResearcherCounts, _RefusedFindings): class Meta(NamedTuple): - """The scan meta a render reads back: the scan itself, and the stamp fields beside it.""" + """The scan meta a render reads back: the scan itself, and the fields read beside it.""" scan: sarif.Scan scan_root: str @@ -101,19 +105,19 @@ class Meta(NamedTuple): revision_source: str model: object effort: object + asked_for_max: bool class Rendered(NamedTuple): - """A completed render: the findings, their verification, and the stamp's tag.""" + """A completed render: findings, verification, stamp tag, and whether `max` was asked for.""" findings: list[Record] verification: VerificationSummary tag: str + asked_for_max: bool -REVISION_PREFIX = "CLAUDE-SECURITY-REVISION-" -STAMP_ONLY = frozenset({"duration_s", "verification_runs", "reason_kind"}) -JSONL_NAME = "CLAUDE-SECURITY-RESULTS.jsonl" +STAMP_ONLY = frozenset({"duration_s", "verification_runs", "reason_kind", "pruned_buckets"}) SARIF_NAME = "CLAUDE-SECURITY-RESULTS.sarif" SANITIZED_REMOTE_RE = re.compile( r"https://[a-z0-9.-]+(?::[0-9]+)?/(?:[A-Za-z0-9._~/-]|%[0-9A-F]{2})+\Z" @@ -153,7 +157,8 @@ def read_votes(run_dir: Path) -> JsonMap | None: msg = f"votes.json is not valid JSON: {error}" raise RenderError(msg) from error if not is_map(raw): - raise RenderError("votes.json must be a JSON object mapping the vote record") + msg = "votes.json must be a JSON object mapping the vote record" + raise RenderError(msg) if raw.get("provenance") != plugin.VOTES_PROVENANCE: return None return raw @@ -177,15 +182,20 @@ def read_coverage(run_dir: Path) -> tuple[JsonMap | None, str]: COVERAGE_TEXT_CAP = 300 +COVERAGE_LIST_ITEM_CAP = 200 +COVERAGE_NAME_CAP = 100 + + +def capped(text: str, cap: int) -> str: + """`text` trimmed to `cap` characters, the cut marked with how many were dropped.""" + if len(text) > cap: + return text[:cap] + f"...[+{len(text) - cap} chars]" + return text def coverage_text(value: object, cap: int = COVERAGE_TEXT_CAP) -> str | None: """A coverage string, trimmed to `cap`, or None when the value is not a string.""" - if not is_str(value): - return None - if len(value) > cap: - return value[:cap] + f"...[+{len(value) - cap} chars]" - return value + return capped(value, cap) if is_str(value) else None def coverage_texts(raw: object, cap: int) -> list[str]: @@ -207,9 +217,12 @@ def tree_relative(path: str, scan_root: str) -> str | None: def skipped_component(item: JsonMap, scan_root: str) -> dict[str, object]: - paths = (tree_relative(path, scan_root) for path in coverage_texts(item.get("paths"), 200)) + paths = ( + tree_relative(path, scan_root) + for path in coverage_texts(item.get("paths"), COVERAGE_LIST_ITEM_CAP) + ) return { - "name": coverage_text(item.get("name"), 100) or "", + "name": coverage_text(item.get("name"), COVERAGE_NAME_CAP) or "", "paths": [path for path in paths if path is not None], "reason": coverage_text(item.get("reason")) or "", } @@ -222,6 +235,28 @@ def skipped_components(raw: object, scan_root: str) -> list[dict[str, object]] | return [skipped_component(entry, scan_root) for entry in raw if is_map(entry)] +class PrunedBucket(TypedDict): + """One stamp pruned_buckets entry: a group and the research lens it went without.""" + + group: str + lens: str + + +def pruned_buckets(raw: object) -> list[PrunedBucket] | None: + """coverage.prunedBuckets as [{group, lens}], or None when unusable; junk is dropped.""" + if not is_list(raw): + return None + parts = (text.rpartition(":") for text in raw if is_str(text)) + return [ + { + "group": capped(group, COVERAGE_LIST_ITEM_CAP), + "lens": capped(lens, COVERAGE_LIST_ITEM_CAP), + } + for group, sep, lens in parts + if sep and group and lens + ] + + def coverage_enum(value: object, allowed: tuple[str, ...]) -> str | None: """A coverage enum field, or None when absent or not one of the known values.""" return value if is_str(value) and value in allowed else None @@ -232,6 +267,11 @@ def coverage_count(value: object) -> int | None: return value if is_int(value) else None +def coverage_length(value: object) -> int | None: + """How many entries a coverage list field holds, or None when absent or not a list.""" + return len(value) if is_list(value) else None + + class ResearchCoverage(TypedDict): """The stamp's research_coverage: the coverage account's counts, and whether a list was cut.""" @@ -276,26 +316,30 @@ def run_shape( scan_root: str, research: ResearchCoverage | None, ) -> dict[str, object]: - """What shape actually ran, distinct from the effort tier that was asked.""" + """What shape actually ran, distinct from the effort tier that was recorded.""" shape: dict[str, object] = {"requested_effort": effort, "collapsed": None, "source": source} if coverage is None: return shape return { **shape, - "collapsed": coverage_enum(coverage.get("collapsed"), ("small-diff", "small-scope")), + "collapsed": coverage_enum(coverage.get("collapsed"), ("small-scope",)), "diff_files": coverage_count(coverage.get("diffFiles")), "diff_lines": coverage_count(coverage.get("diffLines")), + "pre_existing": coverage_length(coverage.get("preExisting")), "scope_files": coverage_count(coverage.get("scopeFiles")), "empty_diff": bool(coverage.get("emptyDiff")), "empty_scope": bool(coverage.get("emptyScope")), "researchers_dispatched": coverage_count(coverage.get("researchersDispatched")), "verification_runs": coverage_count(coverage.get("verificationRun")), "skipped_components": skipped_components(coverage.get("skippedComponents"), scan_root), + "pruned_buckets": pruned_buckets(coverage.get("prunedBuckets")), "completeness_check_outcome": coverage_enum( coverage.get("completenessCheckOutcome"), ("checked", "partial", "not-checkable", "not-applicable"), ), - "unaccounted_top_level_dirs": coverage_texts(coverage.get("unaccountedTopLevelDirs"), 200), + "unaccounted_top_level_dirs": coverage_texts( + coverage.get("unaccountedTopLevelDirs"), COVERAGE_LIST_ITEM_CAP + ), "inventory_fallback": coverage_enum( coverage.get("inventoryFallback"), ("inventory-failed", "empty-partition", "incomplete-partition"), @@ -323,9 +367,10 @@ def handed_on(votes: JsonMap) -> int: def verification_summary( findings: Sequence[Finding], votes: JsonMap, - votes_present: bool = True, - continuing: int = 0, - refused: Sequence[_RefusalRecord] = (), + *, + votes_present: bool, + continuing: int, + refused: Sequence[_RefusalRecord], ) -> VerificationSummary: """Compute the stamp's verification object from the vote record and the render's refusals. @@ -339,9 +384,8 @@ def verification_summary( that did not complete. `refused` lists the findings the render refused, which the summary repeats under `refused_findings`. """ - raw_rounds = votes.get("rounds") - rounds: JsonMap = raw_rounds if is_map(raw_rounds) else {} - panels = [(f["id"], panel_complete(rounds.get(f["id"]))) for f in findings] + rounds = vote_rounds(votes) + panels = finding_panels(rounds, [f["id"] for f in findings]) incomplete = sorted(finding_id for finding_id, panel in panels if panel is None) reviewed = [panel for _, panel in panels if panel is not None] quorum = sum(panel["true"] >= PANEL_KEEP_QUORUM for panel in reviewed) @@ -454,13 +498,13 @@ def revision_tag(revision: object) -> str: if not is_map(revision): msg = f"the run's revision {revision!r} is not an object, so it cannot name the stamp file" raise RenderError(msg) - sha = revision.get("commit") or revision.get("head") + sha = revision.get("commit") if not sha: return "UNVERSIONED" if not is_str(sha) or not plugin.SHA_RE.match(sha): msg = f"the run's revision {sha!r} is not a hex commit id, so it cannot name the stamp file" raise RenderError(msg) - return sha[:12] + ("" if revision.get("dirty") is False else "-dirty") + return sha[: plugin.SHORT_ID_CHARS] + ("" if revision.get("dirty") is False else "-dirty") def scan_of(meta: JsonMap) -> Meta: @@ -492,6 +536,17 @@ def scan_of(meta: JsonMap) -> Meta: f"scan-meta.json scan_prefix {prefix!r} is not a path prefix; rerun write_scan_meta.py" ) raise RenderError(msg) + try: + os.path.realpath(scan_root) + except (OSError, ValueError) as error: + msg = f"scan-meta.json scan_root {scan_root!r} cannot be resolved; rerun write_scan_meta.py" + raise RenderError(msg) from error + if not scan_prefix_fits(prefix, scan_root=scan_root): + msg = ( + f"scan-meta.json scan_prefix {prefix!r} is deeper than scan_root {scan_root!r}; " + "rerun write_scan_meta.py" + ) + raise RenderError(msg) remote = meta.get("remote") if remote is not None and (not is_str(remote) or not SANITIZED_REMOTE_RE.match(remote)): msg = ( @@ -529,7 +584,15 @@ def scan_of(meta: JsonMap) -> Meta: scope=tuple(entries), revision=clean_commit, ) - return Meta(scan, scan_root, revision, revision_source, meta.get("model"), meta.get("effort")) + return Meta( + scan, + scan_root, + revision, + revision_source, + meta.get("model"), + meta.get("effort"), + meta.get("asked_for_max") is True, + ) def elapsed_seconds(started_at: object, now: datetime) -> int | None: @@ -551,9 +614,9 @@ def jsonl_text(findings: Sequence[Record]) -> str: return "".join(strictjson.text(secret.withheld(item)) + "\n" for item in findings) -def strength(finding: Finding) -> tuple[int, int]: +def strength(finding: Finding) -> tuple[Severity, Confidence]: """A finding's rank among those at one site: severity first, then confidence.""" - return -SEVERITIES.index(finding["severity"]), CONFIDENCES.index(finding["confidence"]) + return Severity[finding["severity"]], Confidence[finding["confidence"]] def one_per_site(findings: Sequence[Record], scan: sarif.Scan) -> tuple[list[Record], list[str]]: @@ -571,14 +634,15 @@ def one_per_site(findings: Sequence[Record], scan: sarif.Scan) -> tuple[list[Rec for item, where in zip(findings, sites): if where is not None: by_site.setdefault(where, []).append(item) - kept = {where: max(group, key=strength) for where, group in by_site.items()} + strongest = {where: max(group, key=strength) for where, group in by_site.items()} merged = [ - f"finding {other['id']} names the same site as finding {kept[where]['id']}, " + f"finding {other['id']} names the same site as finding {strongest[where]['id']}, " f"{where.path}:{where.line} under rule {where.rule}; merged into it" for where, group in by_site.items() for other in group - if other is not kept[where] + if other is not strongest[where] ] + kept = {where: with_cwes_of(strongest[where], group) for where, group in by_site.items()} unmerged = [ item if where is None else kept[where] for item, where in zip(findings, sites) @@ -587,6 +651,17 @@ def one_per_site(findings: Sequence[Record], scan: sarif.Scan) -> tuple[list[Rec return unmerged, merged +def with_cwes_of(kept: Record, group: Sequence[Record]) -> Record: + """`kept` carrying, as further CWEs, every id the findings merged into it were filed under.""" + others = [ + cwe_id + for item in group + for cwe_id in (item["cwe_id"], *item["other_cwe_ids"]) + if cwe_id != kept["cwe_id"] + ] + return {**kept, "other_cwe_ids": list(dict.fromkeys([*kept["other_cwe_ids"], *others]))} + + def unrecognized_cwes(findings: Sequence[Finding]) -> list[str]: """One disclosure sentence per finding whose declared CWE the pinned release does not define.""" return [ @@ -702,10 +777,12 @@ def render(run_dir: Path, products_dir: Path) -> Rendered: """Read the run's records, validate them, build every product, then write them, stamp last.""" meta = read_json(run_dir, "scan-meta.json") if not is_map(meta): - raise RenderError("scan-meta.json must be a JSON object") + msg = "scan-meta.json must be a JSON object" + raise RenderError(msg) findings_in = read_json(run_dir, "findings.json") if not is_list(findings_in): - raise RenderError("findings.json must be a JSON array (use [] for no findings)") + msg = "findings.json must be a JSON array (use [] for no findings)" + raise RenderError(msg) coverage, coverage_source = read_coverage(run_dir) votes_raw = read_votes(run_dir) votes: JsonMap = {} if votes_raw is None else votes_raw @@ -717,7 +794,7 @@ def render(run_dir: Path, products_dir: Path) -> Rendered: msg = f"votes.json 'rounds' must be an object keyed by finding id, not {kind}" raise RenderError(msg) rounds_by_id = rounds_raw - scan, scan_root, revision, revision_source, model, effort = scan_of(meta) + scan, scan_root, revision, revision_source, model, effort, asked_for_max = scan_of(meta) tag = revision_tag(revision) outcomes = [ @@ -739,16 +816,17 @@ def render(run_dir: Path, products_dir: Path) -> Rendered: for path in {f["file"] for f in built} if (text := source.read(scan_root, path)) is not None } - refused_secrets = [e.snippet for e in path_errors if secret.is_credential_cwe(e.cwe)] + refused_secrets = [e.snippet for e in path_errors if any(map(secret.is_credential_cwe, e.cwes))] records = sarif.placed(built, scan, sources, refused_secrets=refused_secrets) findings, merged = one_per_site(records, scan) markdown_path = run_dir / "CLAUDE-SECURITY-RESULTS.md" if not os.path.isfile(markdown_path): - raise RenderError( + msg = ( "CLAUDE-SECURITY-RESULTS.md is missing. Write the human-readable " "report before running this script." ) + raise RenderError(msg) markdown = markdown_path.read_bytes() try: markdown.decode("utf-8") @@ -804,28 +882,28 @@ def render(run_dir: Path, products_dir: Path) -> Rendered: refusal_lines = [f"refused {error.finding_id}: {error}" for error in path_errors] for text in merged + unrecognized + unfinished + refusal_lines: sys.stderr.write(f"render_report.py: {text}\n") - symlinks = coverage_texts(meta.get("unfollowed_symlinks"), 200) + symlinks = coverage_texts(meta.get("unfollowed_symlinks"), COVERAGE_LIST_ITEM_CAP) notifications = notifications_of( shape, research, verification, merged, unrecognized, symlinks, revision, continuing, refused ) sarif_log = sarif.log(findings, scan, plugin.version(), run_properties, panels, notifications) sarif_doc = strictjson.text(sarif_log, indent=2) + "\n" for stale in products_dir.iterdir(): - if stale.name.startswith(REVISION_PREFIX) and stale.suffix == ".json": + if plugin.is_revision_stamp(stale): stale.unlink() - (products_dir / JSONL_NAME).write_bytes(jsonl.encode()) + (products_dir / plugin.JSONL_NAME).write_bytes(jsonl.encode()) (products_dir / SARIF_NAME).write_bytes(sarif_doc.encode()) markdown_out = products_dir / "CLAUDE-SECURITY-RESULTS.md" # realpath, not Path.resolve(): on 3.9 for Windows resolve() raises on volumes realpath accepts. relocated = os.path.realpath(markdown_path) != os.path.realpath(markdown_out) if relocated: markdown_out.write_bytes(markdown) - stamp_path = products_dir / f"{REVISION_PREFIX}{tag}.json" + stamp_path = products_dir / f"{plugin.REVISION_PREFIX}{tag}.json" stamp_path.write_bytes((strictjson.text(stamp, indent=2) + "\n").encode()) if relocated: markdown_path.unlink() - return Rendered(findings, verification, tag) + return Rendered(findings, verification, tag, asked_for_max) def remove_run_dir(run_dir: Path, products_dir: Path) -> str: @@ -836,6 +914,11 @@ def remove_run_dir(run_dir: Path, products_dir: Path) -> str: return f"kept {run_dir} (not a {plugin.RUN_DIR_NAME} run directory)" if os.path.realpath(target) == os.path.realpath(products_dir): return f"kept {run_dir} (it holds the products)" + if not plugin.REPORT_DIR_RE.match(target.parent.name): + return f"kept {run_dir} (not inside a CLAUDE-SECURITY-<timestamp> report directory)" + for directory in (target, target.parent): + if is_link(directory): + return f"kept {run_dir} ('{directory}' is a symbolic link)" try: shutil.rmtree(str(target)) except OSError as error: @@ -877,9 +960,9 @@ def main(argv: list[str]) -> int: return 1 removal = remove_run_dir(run_dir, products_dir) count = len(rendered.findings) - stamp_name = f"{REVISION_PREFIX}{rendered.tag}.json" + stamp_name = f"{plugin.REVISION_PREFIX}{rendered.tag}.json" print( - f"wrote {JSONL_NAME}, {SARIF_NAME} ({count} finding{'' if count == 1 else 's'}) " + f"wrote {plugin.JSONL_NAME}, {SARIF_NAME} ({count} finding{'' if count == 1 else 's'}) " f"and {stamp_name} into {products_dir}" ) print(f"stamp: {stamp_name}") @@ -887,6 +970,8 @@ def main(argv: list[str]) -> int: if reason := rendered.verification["reason"]: print(f"verification.reason: {reason}") print(removal) + if rendered.asked_for_max: + print(plugin.RETIRED_MAX_RELAY) return 0 diff --git a/plugins/claude-security/scripts/save_result.py b/plugins/claude-security/scripts/save_result.py index 1056c848..55314255 100755 --- a/plugins/claude-security/scripts/save_result.py +++ b/plugins/claude-security/scripts/save_result.py @@ -5,10 +5,12 @@ Reads the JSON file the Claude Code runtime writes when a workflow task completes, folds the result's findings, votes and coverage into findings.json, votes.json and coverage.json in the run directory (appending to an earlier run's when this result continues one), writes the candidate -files a further verification run loads, and prints one `next:` line: the -Workflow call that continues the verification, or the instruction to write -the report. Each finding is recorded at the line of its file that its quoted -code is on, with the line the researcher declared kept beside it. +files a further verification run loads, and prints a summary line with the +count at each severity, a `votes:` line with each finding's panel tally, and +a `next:` line: the Workflow call that continues the verification, or the +instruction to write the report. Each finding is recorded at the line of its +file that its quoted code is on, with the line the researcher declared kept +beside it. Usage: save_result.py <output_file> <run_dir> @@ -24,6 +26,7 @@ import argparse import os import re import sys +from collections import Counter from pathlib import Path from typing import NamedTuple @@ -33,13 +36,19 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) from lib import console, plugin, source, strictjson from lib.chain import Chain, chain_of, pending_ranks from lib.finding import ( - CONFIDENCE_RANK, - SEVERITIES, + Confidence, FindingError, + Panel, + Severity, file_field, + finding_panels, line_number, + link_field, + scan_prefix_fits, scan_prefix_shaped, + vote_rounds, ) +from lib.revision import change_range from lib.strictjson import JsonMap, is_int, is_list, is_map, is_str # Rows per candidate file; workflows/scan.js derives each file's ranks from the same number. @@ -60,6 +69,17 @@ class Records(NamedTuple): coverage: JsonMap chain: Chain + @property + def rounds(self) -> JsonMap: + return vote_rounds(self.votes) + + def severity_counts(self) -> Counter[Severity]: + """How many findings carry each severity; a word that names no Severity is not counted.""" + return Counter(s for s in map(Severity.of, self.findings) if s is not None) + + def panels(self) -> list[tuple[str, Panel | None]]: + return finding_panels(self.rounds, [str(f["id"]) for f in self.findings]) + class Args(argparse.Namespace): """The parsed command line.""" @@ -246,13 +266,10 @@ def checked(coverage: JsonMap, meta: JsonMap, run_dir: Path) -> JsonMap: def placed(finding: JsonMap, meta: JsonMap) -> JsonMap: - """`finding` at the line of its file that its quoted snippet is on, its declared line kept. + """`finding` with its file, change link and line as the render will carry them. - `line` becomes the line of the finding's file under the scan root that - places it (source.placed_line) and the line as it arrived moves to - `declared_line`; both hold the arriving line when the file cannot be - read or nothing in it places the finding. A finding whose line or snippet - is not a shape the render accepts is returned as it is. + `line` becomes the line of the file its quoted snippet is on, and the line as it arrived + moves to `declared_line`. Fields the render would refuse are left as they are. """ finding_id, line, snippet = ( finding["id"], @@ -267,24 +284,28 @@ def placed(finding: JsonMap, meta: JsonMap) -> JsonMap: or not is_str(scan_root) or not is_str(prefix) or not scan_prefix_shaped(prefix) + or not scan_prefix_fits(prefix, scan_root=scan_root) ): return finding try: file = file_field(finding, finding_id, scan_root, prefix, meta.get("mode") == "scan") - text = source.read(scan_root, file) + via_change = link_field(finding, finding_id, scan_root, prefix) except FindingError: - text = None - return {**finding, "line": source.placed_line(text, line, snippet or ""), "declared_line": line} + return {**finding, "line": line, "declared_line": line} + return { + **finding, + **({"file": file} if file == file.strip() else {}), + **({"via_change": via_change} if via_change else {}), + "line": source.placed_line(source.read(scan_root, file), line, snippet or ""), + "declared_line": line, + } def report_order(finding: JsonMap) -> tuple[int, int]: """Sort key: severity, then confidence, strongest first; unknown values last.""" - severity = str(finding.get("severity", "")).upper() + severity = Severity.of(finding) confidence = str(finding.get("confidence", "")).lower() - return ( - SEVERITIES.index(severity) if severity in SEVERITIES else len(SEVERITIES), - -CONFIDENCE_RANK.get(confidence, 0), - ) + return -(severity.value if severity else 0), -Confidence.__members__.get(confidence, 0) def merged(scan: Records, run: Records) -> Records: @@ -343,6 +364,9 @@ def merged(scan: Records, run: Records) -> Records: + texts(run.coverage, "lostCandidates"), "severityLowered": texts(scan.coverage, "severityLowered") + texts(run.coverage, "severityLowered"), + "preExisting": texts(scan.coverage, "preExisting") + texts(run.coverage, "preExisting"), + "outsideScope": texts(scan.coverage, "outsideScope") + + texts(run.coverage, "outsideScope"), "dispatchRefusals": count(scan.coverage, "dispatchRefusals") + count(run.coverage, "dispatchRefusals"), "continued": run.coverage.get("continued"), @@ -377,25 +401,35 @@ def write_records(run_dir: Path, records: Records, rows: dict[int, JsonMap]) -> def summary(records: Records) -> str: - """One line on where the scan stands.""" - rounds = records.votes.get("rounds") + """Two lines: where the scan stands, with the count at each severity, then each + finding's tally, or "?" when its panel is not complete, in findings.json's order. + """ + counts = records.severity_counts() + by_severity = ", ".join(f"{counts[severity]} {severity.name}" for severity in Severity) + tallies = [f"{i} {p['true']}/{p['voters']}" if p else f"{i} ?" for i, p in records.panels()] return ( - f"recorded verification run {records.chain['shard']}: {len(records.findings)} findings, " - f"{len(rounds) if is_map(rounds) else 0} rounds, " + f"recorded verification run {records.chain['shard']}: {len(records.findings)} findings " + f"({by_severity}), " + f"{len(records.rounds)} rounds, " f"{len(pending_ranks(records.chain))} pending, " - f"{len(texts(records.coverage, 'lostCandidates'))} lost" + f"{len(texts(records.coverage, 'lostCandidates'))} lost\n" + f"votes: {', '.join(tallies) or 'no findings'}" ) -def next_step(run_dir: Path, meta: JsonMap, chain: Chain) -> str: +def next_step(run_dir: Path, meta: JsonMap, records: Records) -> str: """The `next:` line: the Workflow call that panels what is pending, or the report.""" + chain = records.chain if not pending_ranks(chain): return WRITE_REPORT + scope, reviewed_range = meta.get("scope"), records.coverage.get("range") args = { "scanRoot": meta.get("scan_root"), "runDir": str(run_dir), "mode": meta.get("mode"), "effort": meta.get("effort"), + "scope": scope if is_list(scope) and scope else None, + "range": reviewed_range if is_str(reviewed_range) else None, "verify": { "shard": chain["shard"] + 1, "idBase": chain["next_id"], @@ -432,6 +466,16 @@ def standing(run_dir: Path, meta: JsonMap, scan: Records | None, result: JsonMap if not is_str(made_for) or os.path.abspath(made_for) != str(run_dir): msg = f"the result names {made_for!r} as its run directory, not this one" raise CannotContinueError(msg) + revision = meta.get("revision") + reviewed_range = run.coverage.get("range") + recorded_range = change_range(revision) if is_map(revision) else None + if is_str(reviewed_range) and reviewed_range != recorded_range: + msg = ( + f"the result reviewed {reviewed_range} but this scan recorded " + f"{recorded_range or 'no change'}, so it is not a review of the change that was " + "listed: run the scan again with the range: line write_scan_meta.py prints" + ) + raise CannotContinueError(msg) if scan is None and run.chain["shard"] != 1: msg = f"this is run {run.chain['shard']} but nothing is recorded yet" raise CannotContinueError(msg) @@ -451,7 +495,7 @@ def save(output_file: Path, run_dir: Path) -> None: meta = scan_settings(run_dir) records = standing(run_dir, meta, recorded(run_dir), result_in(output_file)) print(summary(records)) - print(next_step(run_dir, meta, records.chain)) + print(next_step(run_dir, meta, records)) def argument_parser() -> argparse.ArgumentParser: diff --git a/plugins/claude-security/scripts/write_scan_meta.py b/plugins/claude-security/scripts/write_scan_meta.py index 0ff642bf..f5e77f2e 100755 --- a/plugins/claude-security/scripts/write_scan_meta.py +++ b/plugins/claude-security/scripts/write_scan_meta.py @@ -9,13 +9,25 @@ the tree's top-level directories, printed as a JSON array on a symbolic links left out of them. For a codebase scan it also lists the scan target's tracked files into target-files.json beside the meta file and prints their count on a `file_count:` line and, for a whole-repository scan, the -count under each top-level directory on a `dir_file_counts:` line. +count under each top-level directory on a `dir_file_counts:` line. For a +changes or commit scan it writes the files the change touches into numbered +changed-files.<n>.json chunks beside the meta file and prints the change as its +two commit ids on a `range:` line, the count of those files on a +`changed_file_count:` line, their added-plus-deleted line count on a +`diff_line_count:` line and, last, the list itself on a `changed_files:` +line when it is short enough to hand over (null when it is not). + +`--effort max` is recorded as `high`, and a `relay:` line carries the note +that tells the user so. Usage: write_scan_meta.py <run_dir> <scan_root> --mode scan|changes|commit --effort low|medium|high|max [--scope a,b] [--base <ref>] [--merge-base <sha>] [--commit <sha>] +A changes scan names its `--merge-base`; a commit scan names its `--commit`, +which must be the checked-out commit. + Exits 0 on success, 1 on a refusal naming what is wrong (a run directory that already holds a scan-meta.json is one), 2 on a usage error; the file is written only on success. @@ -28,35 +40,30 @@ import argparse import os import re import stat -import subprocess import sys import uuid from collections import Counter from datetime import datetime, timezone +from enum import Enum from pathlib import Path -from typing import Literal, NamedTuple, TypedDict +from typing import NamedTuple, TypedDict from urllib.parse import quote, unquote, urlsplit # The lib/ package lives next to this script. Python normally adds a script's own # directory to the import path, but not under -P or PYTHONSAFEPATH, so we add it here. sys.path.insert(0, str(Path(__file__).resolve().parent)) from lib import absolute, console, plugin, strictjson - -GIT_ENV = dict(os.environ, GIT_TERMINAL_PROMPT="0") +from lib.git import run as git +from lib.revision import Revision, change_range -class Revision(TypedDict, total=False): - """What was scanned. `versioned` is always present; the rest when in git.""" +class Effort(Enum): + """An effort tier, as `--effort` spells it.""" - versioned: bool - commit: str | None - parent: str | None - branch: str | None - dirty: bool | None - sparse: Literal[True] - not_checked_out_dirs: list[str] - base: str | None - merge_base: str | None + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + MAX = "max" class Args(argparse.Namespace): @@ -65,7 +72,7 @@ class Args(argparse.Namespace): run_dir: str = "" scan_root: str = "" mode: str = "" - effort: str = "" + effort: Effort = Effort.MEDIUM scope: str = "" base: str | None = None merge_base: str | None = None @@ -76,22 +83,27 @@ class MetaError(Exception): """A refusal: the command line was well-formed but the run cannot be recorded.""" -def git(cwd: str, *args: str) -> str | None: - """One read-only git call, prompts suppressed. None on any failure.""" - try: - out = subprocess.run( - ["git", "-C", cwd, *args], - env=GIT_ENV, - stdout=subprocess.PIPE, - stderr=subprocess.DEVNULL, - timeout=30, - check=False, - ) - except (OSError, subprocess.SubprocessError): - return None - if out.returncode != 0: - return None - return out.stdout.decode("utf-8", "surrogateescape").rstrip("\r\n") +# Paths per changed-files.<n>.json; workflows/scan.js derives the chunk count from the same size. +CHANGED_FILES_CHUNK = 100 +CHANGED_FILES_INLINE_CHARS = 25_000 + + +class ChangedFiles(TypedDict): + """One changed-files.<n>.json chunk: its number, the whole change's file count, its files.""" + + chunk: int + total_files: int + files: list[str] + + +class Change(NamedTuple): + """A change: its two commits as the `<base>..<commit>` range the scan diffs, + the files it touches and its added-plus-deleted line count, None when a + binary file leaves the count unknown.""" + + range: str + files: list[str] + lines: int | None class Extent(NamedTuple): @@ -170,6 +182,48 @@ def target_files(scan_root: str, scope: list[str]) -> list[str] | None: }) +def changed_files(scan_root: str, scope: list[str], *, commits: str) -> Change: + """The change `commits` names (`<base>..<commit>`) within `scope`, from `git diff-tree`.""" + numstat = ("diff-tree", "-r", "--no-commit-id", "--numstat", "-z", "-M", "--relative") + listing = git(scan_root, *numstat, commits, "--", *scope) + if listing is None: + msg = f"git could not diff {commits} in {scan_root!r}" + raise MetaError(msg) + lines: dict[str, int | None] = {} + records = iter(listing.split("\0")) + for record in records: + if not record: + continue + added, deleted, path = record.split("\t", 2) + if not path: + next(records, "") + path = next(records, "") + if path and not path.startswith(plugin.REPORT_DIR_PREFIX): + lines[path] = None if "-" in {added, deleted} else int(added) + int(deleted) + known = [count for count in lines.values() if count is not None] + total = sum(known) if len(known) == len(lines) else None + return Change(commits, sorted(lines), total) + + +def change_lines(change: Change | None) -> list[str]: + """The range, changed_file_count, diff_line_count and changed_files lines record() prints.""" + if change is None: + return [ + "range: null", + "changed_file_count: null", + "diff_line_count: null", + "changed_files: null", + ] + listed = strictjson.text(change.files) + handed = listed if len(listed) <= CHANGED_FILES_INLINE_CHARS else "null" + return [ + f"range: {strictjson.text(change.range)}", + f"changed_file_count: {len(change.files)}", + f"diff_line_count: {strictjson.text(change.lines)}", + f"changed_files: {handed}", + ] + + def regular_file(path: str) -> bool: """Whether `path` is a regular file, judged without following a symbolic link.""" try: @@ -237,43 +291,89 @@ def worktree_dirty(scan_root: str) -> bool | None: def capture_revision(scan_root: str, opts: Args) -> Revision: versioned = git(scan_root, "rev-parse", "--is-inside-work-tree") == "true" + if opts.mode != "scan" and not versioned: + msg = f"--mode {opts.mode} needs a git repository; {scan_root!r} is not one" + raise MetaError(msg) if opts.mode == "commit": - if not versioned: - msg = f"--mode commit needs a git repository; {scan_root!r} is not one" - raise MetaError(msg) commit_arg = opts.commit or "" sha = git(scan_root, "rev-parse", "--verify", "--quiet", commit_arg + "^{commit}") if not sha: msg = f"--commit {commit_arg!r} does not resolve to a commit" raise MetaError(msg) + short = sha[: plugin.SHORT_ID_CHARS] + parent = git(scan_root, "rev-parse", "--verify", "--quiet", sha + "^") or None + if parent is None: + msg = ( + f"the parent of commit {short} is not in this clone (a shallow checkout); " + "fetch more history before scanning the commit" + if names_a_parent(scan_root, sha) + else f"commit {short} is the repository's first and has no parent to " + "diff against; scan the codebase at that commit instead" + ) + raise MetaError(msg) + if sha != git(scan_root, "rev-parse", "--verify", "--quiet", "HEAD"): + msg = ( + f"commit {short} is not checked out, and a commit scan runs only on the " + f"checked-out commit (HEAD); tell the user to check {short} out and ask again, " + "and stop: never check it out or add a worktree yourself" + ) + raise MetaError(msg) return { "versioned": True, "commit": sha, - "parent": git(scan_root, "rev-parse", "--verify", "--quiet", sha + "^") or None, + "parent": parent, "branch": git(scan_root, "rev-parse", "--abbrev-ref", "HEAD"), "dirty": False, } if not versioned: return {"versioned": False} + head = git(scan_root, "rev-parse", "--verify", "--quiet", "HEAD") revision: Revision = { "versioned": True, - "commit": git(scan_root, "rev-parse", "HEAD"), + "commit": head, "branch": git(scan_root, "rev-parse", "--abbrev-ref", "HEAD"), "dirty": worktree_dirty(scan_root), } if opts.mode == "changes": + if not head: + msg = "HEAD names no commit yet, so there is no change to scan" + raise MetaError(msg) + base_arg = opts.merge_base or "" + merge_base = git(scan_root, "rev-parse", "--verify", "--quiet", base_arg + "^{commit}") + if not merge_base: + msg = ( + f"--merge-base {opts.merge_base!r} does not resolve to a commit " + "(a shallow clone may not hold it: fetch more history)" + ) + raise MetaError(msg) + if git(scan_root, "merge-base", "--is-ancestor", merge_base, head) is None: + msg = ( + f"--merge-base {opts.merge_base!r} is not an ancestor of HEAD, so it is not " + "this branch's merge base (a shallow clone cannot compute one: fetch more history)" + ) + raise MetaError(msg) revision["base"] = opts.base - revision["merge_base"] = opts.merge_base + revision["merge_base"] = merge_base return revision +def names_a_parent(scan_root: str, sha: str) -> bool: + """Whether the commit object itself records a parent, whatever the clone holds of it.""" + body = git(scan_root, "cat-file", "commit", sha) + if body is None: + msg = f"git could not read commit {sha[: plugin.SHORT_ID_CHARS]}, so its parent is unknown" + raise MetaError(msg) + return any(line.startswith("parent ") for line in body.split("\n\n", 1)[0].splitlines()) + + def scoped(entry: str, scan_root: str) -> str: """A scope entry relative to the scan root; an absolute spelling of anything else is refused.""" if not absolute.spelled(entry): return entry - msg = f"--scope entry {entry!r} is not inside the scan root {scan_root!r}" + outside = f"--scope entry {entry!r} is not inside the scan root {scan_root!r}" if not os.path.isabs(entry): - raise MetaError(f"{msg}; write ./{entry} to name a directory in the tree") + msg = f"{outside}; write ./{entry} to name a directory in the tree" + raise MetaError(msg) literal = os.path.abspath(entry) parent, name = os.path.split(literal) try: @@ -287,30 +387,45 @@ def scoped(entry: str, scan_root: str) -> str: for resolved in resolutions: if (relative := absolute.relative(resolved, scan_root)) is not None: return relative - raise MetaError(msg) + raise MetaError(outside) + + +def tier(word: str) -> Effort: + """The tier a word names, whatever its case or the spaces around it; any other is refused.""" + try: + return Effort(word.strip().lower()) + except ValueError: + offered = ", ".join(effort.value for effort in Effort if effort is not Effort.MAX) + msg = ( + f"{word!r} is not an effort tier; the tiers are {offered}. " + "Tell the user so and start no scan; do not choose a tier for them" + ) + raise argparse.ArgumentTypeError(msg) from None def parse_options(argv: list[str]) -> Args: """The parsed command line; anything wrong with it is argparse's exit 2.""" - ap = argparse.ArgumentParser(prog="write_scan_meta", allow_abbrev=False) - ap.add_argument("run_dir") - ap.add_argument("scan_root") - ap.add_argument("--mode", required=True, choices=plugin.MODES) - ap.add_argument("--effort", required=True, choices=["low", "medium", "high", "max"]) - ap.add_argument("--scope") - ap.add_argument("--base") - ap.add_argument("--merge-base", dest="merge_base") - ap.add_argument("--commit") - opts = ap.parse_args(argv, namespace=Args()) + parser = argparse.ArgumentParser(prog="write_scan_meta.py", allow_abbrev=False) + parser.add_argument("run_dir") + parser.add_argument("scan_root") + parser.add_argument("--mode", required=True, choices=plugin.MODES) + parser.add_argument("--effort", required=True, type=tier) + parser.add_argument("--scope") + parser.add_argument("--base") + parser.add_argument("--merge-base", dest="merge_base") + parser.add_argument("--commit") + opts = parser.parse_args(argv, namespace=Args()) if opts.mode == "commit" and not opts.commit: - ap.error("--mode commit requires --commit <sha>") + parser.error("--mode commit requires --commit <sha>") + if opts.mode == "changes" and not opts.merge_base: + parser.error("--mode changes requires --merge-base <sha>") if not os.path.isdir(opts.run_dir): - ap.error(f"run directory does not exist: {opts.run_dir}") + parser.error(f"run directory does not exist: {opts.run_dir}") return opts -def main(argv: list[str]) -> int: - opts = parse_options(argv) +def record(opts: Args) -> None: + """Record what is scanned into the run directory's scan-meta.json and print its summary.""" # abspath first: "x/.." is x's parent as typed, where realpath alone would follow a symlink x. run_dir = Path(os.path.realpath(os.path.abspath(opts.run_dir))) scan_root = os.path.realpath(os.path.abspath(opts.scan_root)) @@ -335,9 +450,18 @@ def main(argv: list[str]) -> int: tracked = opts.mode == "scan" and extent is not None and extent.tracked files = target_files(scan_root, scope) if tracked else None if tracked and files is None: - sys.stderr.write(f"write_scan_meta: could not list {scan_root}; file_count unknown\n") + sys.stderr.write(f"write_scan_meta.py: could not list {scan_root}; file_count unknown\n") + change = None + if opts.mode != "scan": + commits = change_range(revision) + if commits is None: + msg = "the change's endpoints are unknown" + raise MetaError(msg) + change = changed_files(scan_root, scope, commits=commits) if whole_repo and extent is None: - sys.stderr.write(f"write_scan_meta: could not list {scan_root}; top_level_dirs unknown\n") + sys.stderr.write( + f"write_scan_meta.py: could not list {scan_root}; top_level_dirs unknown\n" + ) top_level, symlinks = (extent.dirs, extent.symlinks) if whole_repo and extent else (None, None) dir_file_counts = None if top_level is not None and files is not None: @@ -345,9 +469,11 @@ def main(argv: list[str]) -> int: dir_file_counts = {name: per_dir[name] for name in top_level} if symlinks: sys.stderr.write( - "write_scan_meta: root-level symbolic links not followed, " + "write_scan_meta.py: root-level symbolic links not followed, " f"left out of top_level_dirs: {', '.join(symlinks)}\n" ) + retired = opts.effort is Effort.MAX + effort = Effort.HIGH if retired else opts.effort meta: dict[str, object] = { "scan_id": str(uuid.uuid4()), "started_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat(), @@ -359,7 +485,8 @@ def main(argv: list[str]) -> int: "agent": f"{plugin.NAME}:{plugin.NAME}", "mode": opts.mode, "scope": scope, - "effort": opts.effort, + "effort": effort.value, + "asked_for_max": retired, "model": None, "revision": revision, "revision_source": "self-reported", @@ -371,7 +498,9 @@ def main(argv: list[str]) -> int: try: with path.open("x", encoding="utf-8", newline="\n") as out: out.write(strictjson.text(meta, indent=2) + "\n") - except FileExistsError as error: + except (FileExistsError, PermissionError) as error: + if isinstance(error, PermissionError) and not path.is_dir(): + raise msg = ( f"{run_dir} already holds a scan's scan-meta.json, so another scan is using this " "report directory; make a new report directory named for the current time and " @@ -380,24 +509,42 @@ def main(argv: list[str]) -> int: raise MetaError(msg) from error if files is not None: (run_dir / plugin.TARGET_FILES_NAME).write_bytes((strictjson.text(files) + "\n").encode()) - sys.stdout.write(f"scan-meta.json written: {path}\n") - sys.stdout.write(f"revision: {revision.get('commit') or 'UNVERSIONED'}\n") + if change is not None: + for number, start in enumerate(range(0, len(change.files), CHANGED_FILES_CHUNK), start=1): + chunk: ChangedFiles = { + "chunk": number, + "total_files": len(change.files), + "files": change.files[start : start + CHANGED_FILES_CHUNK], + } + (run_dir / f"changed-files.{number}.json").write_bytes( + (strictjson.text(chunk, indent=1) + "\n").encode() + ) + print(f"scan-meta.json written: {path}") + print(f"revision: {revision.get('commit') or 'UNVERSIONED'}") if absent is not None: - listed = strictjson.text(absent) - sys.stdout.write(f"sparse checkout: top-level directories not checked out: {listed}\n") - sys.stdout.write(f"top_level_dirs: {strictjson.text(top_level)}\n") - sys.stdout.write(f"file_count: {strictjson.text(None if files is None else len(files))}\n") - sys.stdout.write(f"dir_file_counts: {strictjson.text(dir_file_counts)}\n") - return 0 + print(f"sparse checkout: top-level directories not checked out: {strictjson.text(absent)}") + if retired: + print(plugin.RETIRED_MAX_RELAY) + print(f"top_level_dirs: {strictjson.text(top_level)}") + print(f"file_count: {strictjson.text(None if files is None else len(files))}") + print(f"dir_file_counts: {strictjson.text(dir_file_counts)}") + for line in change_lines(change): + print(line) -if __name__ == "__main__": - console.tolerate_undecodable_names() +def main(argv: list[str]) -> int: + opts = parse_options(argv) try: - sys.exit(main(sys.argv[1:])) + record(opts) except MetaError as error: - sys.stderr.write(f"write_scan_meta: {error}\n") - sys.exit(1) + sys.stderr.write(f"write_scan_meta.py: {error}\n") + return 1 except OSError as error: - sys.stderr.write(f"write_scan_meta: could not write the run's output: {error}\n") - sys.exit(1) + sys.stderr.write(f"write_scan_meta.py: could not write the run's output: {error}\n") + return 1 + return 0 + + +if __name__ == "__main__": + console.tolerate_undecodable_names() + sys.exit(main(sys.argv[1:])) |
