summaryrefslogtreecommitdiff
path: root/plugins/claude-security/scripts/lib/finding.py
diff options
context:
space:
mode:
Diffstat (limited to 'plugins/claude-security/scripts/lib/finding.py')
-rw-r--r--plugins/claude-security/scripts/lib/finding.py258
1 files changed, 202 insertions, 56 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],
}