summaryrefslogtreecommitdiff
path: root/plugins/claude-security/scripts/lib/finding.py
blob: 0a14e4d39616e2e5ada0c16891ff38b0389f8e54 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
"""The Finding every product is built from, and build_finding, which validates a raw one."""

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
from .strictjson import JsonMap, has_lone_surrogate, is_int, is_list, is_map, is_str


class Panel(TypedDict):
    """A validated panel round: the vote counts and the fixed voter count."""

    true: int
    false: int
    voters: int


class Finding(TypedDict):
    """One validated finding, in the JSONL record's field order; the record adds the id (Record)."""

    id: str
    title: str
    impact: str
    file: str
    line: int
    description: str
    exploit_scenario: str
    preconditions: list[str]
    category: str
    severity: str
    confidence: str
    recommendation: str
    cwe_id: str
    snippet: str
    symbol: str
    declared_line: int
    via_change: str | None
    other_cwe_ids: list[str]


class Record(Finding):
    """A finding as every product carries it: placed on its line (sarif.placed), its id last."""

    claudeSecurityPluginFindingId: str


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

# \Z, not $: `$` also matches before a trailing newline, and this names a file.
FINDING_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}\Z")


class FindingError(Exception):
    """A refusal; the message names what a findings.json record got wrong."""


class FindingPathError(FindingError):
    """A refusal of one finding's model-written path; the rest of a report can still carry.

    The message names the finding and quotes the declared path; `finding_id`
    and `wrong` (what is wrong with the path, without the path) are what a
    caller surviving the refusal may record in a product.
    """

    finding_id: str
    wrong: str
    cwes: tuple[int, ...] = ()
    snippet: str = ""

    def __init__(self, finding_id: str, *, declared: str, wrong: str) -> None:
        super().__init__(f"finding {finding_id} file {declared!r} {wrong}")
        self.finding_id = finding_id
        self.wrong = wrong


def cwe_number(item: JsonMap, finding_id: str) -> int:
    """A finding's CWE number; a cwe_id missing, unreadable or malformed is refused.

    A well-formed id is accepted as declared, whether or not the pinned CWE
    release defines it; one the release does not define files the finding
    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} {field} {declared!r} is not a CWE id such as CWE-89"
        raise FindingError(msg)
    return int(matched[1])


# 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.__members__:
            return Confidence[word]
    msg = f"confidence {raw!r} is not one of {'/'.join(Confidence.__members__)}"
    raise FindingError(msg)


def panel_complete(record: object) -> Panel | None:
    """One round record's panel when the full voter count returned an integer tally, else None."""
    if not is_map(record):
        return None
    panel = record.get("panel")
    if not is_map(panel):
        return None
    panel_true = panel.get("true")
    if not is_int(panel_true):
        return None
    if panel.get("voters") != PANEL_VOTER_COUNT:
        return None
    false_votes = panel.get("false")
    return {
        "true": panel_true,
        "false": false_votes if is_int(false_votes) else 0,
        "voters": PANEL_VOTER_COUNT,
    }


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 Confidence.high if panel["true"] >= PANEL_VOTER_COUNT else Confidence.medium


def line_number(raw: object) -> int | None:
    """A findings.json line value as an integer: an int, or digits in a string; None otherwise."""
    if is_str(raw) and re.fullmatch(r"\s*-?[0-9]{1,15}\s*", raw):
        return int(raw)
    return raw if is_int(raw) else None


def line_field(item: JsonMap, key: str, finding_id: str, default: int) -> int:
    """One of a finding's line fields as an integer (line_number); absent reads as `default`."""
    line = line_number(item.get(key, default))
    if line is None:
        msg = f"finding {finding_id} {key} {item.get(key)!r} is not an integer"
        raise FindingError(msg)
    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:
        return True
    return (
        prefix.endswith("/")
        and "\\" not in prefix
        and not ntpath.splitdrive(prefix)[0]
        and all(segment not in {"", ".", ".."} for segment in prefix.split("/")[:-1])
    )


def text_field(item: JsonMap, key: str, finding_id: str, required: bool = False) -> str:
    """One of a finding's text fields; absent or null reads as empty unless it is required."""
    value = item.get(key)
    if value is None:
        text = ""
    elif is_str(value):
        text = value
    else:
        msg = f"finding {finding_id} {key} is {type(value).__name__}, not a string"
        raise FindingError(msg)
    if has_lone_surrogate(text):
        msg = f"finding {finding_id} {key} contains an unpaired surrogate"
        raise FindingError(msg)
    if required and not text.strip():
        msg = f"finding {finding_id} is missing required field {key!r}"
        raise FindingError(msg)
    return text


def leaked_spelling(path: str, *, first: str, scan_root: str) -> bool:
    """Whether a path's cross-platform absolute spelling names the machine, not the repository."""
    if not absolute.spelled(path):
        return False
    if os.name == "nt":
        return True
    return not os.path.lexists(os.path.join(scan_root, first))


def file_field(
    item: JsonMap, finding_id: str, scan_root: str, scan_prefix: str, must_exist: bool
) -> 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).
    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'}"
    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 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 (
        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=elsewhere)
    return relative


def build_finding(
    raw: object,
    index: int,
    rounds_by_id: JsonMap,
    scan_root: str,
    scan_prefix: str,
    must_exist: bool,
) -> Finding:
    """Validate one raw findings.json record into a Finding."""
    if not is_map(raw):
        msg = f"findings.json item {index} is not an object"
        raise FindingError(msg)
    numbered = f"F{index + 1}"
    finding_id = text_field(raw, "id", numbered) or numbered
    if not FINDING_ID_RE.match(finding_id):
        msg = f"finding id {finding_id!r} is not a valid id"
        raise FindingError(msg)

    severity = Severity.of(raw)
    if severity is None:
        msg = (
            f"finding {finding_id} severity {raw.get('severity')!r} is not one of "
            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:
        confidence = min(confidence, ceiling)

    line = line_field(raw, "line", finding_id, 0)
    declared_line = line_field(raw, "declared_line", finding_id, line)

    preconditions: list[str] = []
    declared = raw.get("preconditions")
    if declared is not None:
        if not is_list(declared):
            msg = f"finding {finding_id} preconditions must be a list"
            raise FindingError(msg)
        preconditions = [item for item in declared if is_str(item)]
        if len(preconditions) != len(declared) or any(map(has_lone_surrogate, preconditions)):
            msg = f"finding {finding_id} preconditions must be a list of strings"
            raise FindingError(msg)

    number = cwe_number(raw, finding_id)
    category = cwe.catalog.category(number)
    title = text_field(raw, "title", finding_id, required=True)
    impact = text_field(raw, "impact", finding_id)
    description = text_field(raw, "description", finding_id, required=True)
    exploit_scenario = text_field(raw, "exploit_scenario", finding_id, required=True)
    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.cwes, error.snippet = (number, *further), snippet
        raise

    return {
        "id": finding_id,
        "title": title,
        "impact": impact,
        "file": file,
        "line": line,
        "description": description,
        "exploit_scenario": exploit_scenario,
        "preconditions": preconditions,
        "category": category.name if category is not None else cwe.UNCATEGORIZED,
        "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],
    }