openfix-cli 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
openfix/engine.py ADDED
@@ -0,0 +1,477 @@
1
+ """Orchestration: findings -> policy decision -> isolated fix -> independent verification -> receipt -> PR."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import sys
8
+ from collections.abc import Callable
9
+ from dataclasses import dataclass, field
10
+ from datetime import datetime, timezone
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ from . import providers
15
+ from .agent import Workspace, run_agent
16
+ from .console import finding_line, result_line
17
+ from .deps import try_bump
18
+ from .findings import Finding
19
+ from .github import PublishError, open_pull_request
20
+ from .gitutil import changed_files, diff_against, exclude_locally, file_at, head_commit, is_dirty, repo_root, worktree
21
+ from .policy import Action, Command, Decision, Policy
22
+ from .receipt import make_receipt, sha256, write_receipt
23
+ from .report import pr_body, summary_markdown
24
+ from .sandbox import Sandbox, make_sandbox
25
+ from .sarif_out import to_sarif
26
+ from .scanners import SCAN_DIR, Scanner, preset_for
27
+ from .verify import (
28
+ Check,
29
+ check_regression_test,
30
+ check_rescan,
31
+ check_review,
32
+ check_tests,
33
+ detect_setup_command,
34
+ detect_test_command,
35
+ overall,
36
+ scan_target,
37
+ )
38
+
39
+
40
+ @dataclass
41
+ class Options:
42
+ out: Path | None = None
43
+ author: str | None = None
44
+ reviewer: str | None = None
45
+ sandbox: str | None = None
46
+ open_prs: bool = False
47
+ base_branch: str | None = None
48
+ sign: bool = False
49
+ dry_run: bool = False
50
+ keep_worktrees: bool = False
51
+ max_findings: int | None = None
52
+
53
+
54
+ @dataclass
55
+ class Outcome:
56
+ finding: Finding
57
+ decision: Decision
58
+ status: str # skipped | not_reproduced | verified | unverified | failed | no_fix | disputed | error
59
+ detail: str = ""
60
+ checks: list[Check] = field(default_factory=list)
61
+ out_dir: Path | None = None
62
+ pr_url: str | None = None
63
+ cost_usd: float | None = None
64
+ tokens: int = 0
65
+ files: dict[str, tuple[str, str]] = field(default_factory=dict)
66
+ summary: str = ""
67
+
68
+ def to_dict(self) -> dict[str, Any]:
69
+ return {
70
+ "id": self.finding.id,
71
+ "label": self.finding.short(),
72
+ "action": self.decision.action.value,
73
+ "rule": self.decision.rule,
74
+ "status": self.status,
75
+ "detail": self.detail,
76
+ "checks": [c.to_dict() for c in self.checks],
77
+ "out_dir": str(self.out_dir or ""),
78
+ "pr_url": self.pr_url,
79
+ "cost_usd": self.cost_usd,
80
+ "tokens": self.tokens,
81
+ }
82
+
83
+
84
+ Log = Callable[[str], None]
85
+
86
+
87
+ def _default_log(msg: str) -> None:
88
+ print(msg, file=sys.stderr, flush=True)
89
+
90
+
91
+ def scanner_spec(spec: Any, f: Finding) -> Any:
92
+ """``verify.scanner`` may map scanner presets to commands; other tools fall back to their preset."""
93
+ if isinstance(spec, dict):
94
+ spec = spec.get(preset_for(f) or f.tool.lower())
95
+ return spec
96
+
97
+
98
+ class Engine:
99
+ def __init__(
100
+ self, repo: Path, policy: Policy, options: Options, policy_path: Path | None = None, log: Log = _default_log
101
+ ) -> None:
102
+ self.repo = repo_root(repo)
103
+ # Monorepos: findings, tests and scans are relative to the project directory, patches to the repo root.
104
+ self.subdir = Path(repo).resolve().relative_to(self.repo.resolve()).as_posix()
105
+ self.project = self.repo if self.subdir == "." else self.repo / self.subdir
106
+ self.policy = policy
107
+ self.opt = options
108
+ self.log = log
109
+ self.base = head_commit(self.repo)
110
+ self.run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
111
+ self.out = options.out or (self.project / ".openfix" / "runs" / self.run_id)
112
+ self.policy_digest = sha256(policy_path.read_bytes()) if policy_path else sha256(policy.model_dump_json())
113
+ self._providers: dict[str, providers.Provider] = {}
114
+ self._sandbox: Sandbox | None = None
115
+ self.spent_usd = 0.0
116
+ self.spent_tokens = 0
117
+
118
+ # ---------------------------------------------------------------- helpers
119
+
120
+ def provider(self, ref: str) -> providers.Provider:
121
+ if ref not in self._providers:
122
+ self._providers[ref] = providers.create(ref, effort=self.policy.models.effort)
123
+ return self._providers[ref]
124
+
125
+ @property
126
+ def sandbox(self) -> Sandbox:
127
+ if self._sandbox is None:
128
+ sb = self.policy.sandbox
129
+ self._sandbox = make_sandbox(self.opt.sandbox or sb.backend, self.project, sb.image, sb.memory, sb.cpus)
130
+ return self._sandbox
131
+
132
+ def to_repo(self, p: str) -> str:
133
+ return p if self.subdir == "." else f"{self.subdir}/{p}"
134
+
135
+ def to_project(self, p: str) -> str:
136
+ if self.subdir == ".":
137
+ return p
138
+ prefix = self.subdir + "/"
139
+ return p[len(prefix) :] if p.startswith(prefix) else "../" * len(Path(self.subdir).parts) + p
140
+
141
+ def plan(self, findings: list[Finding]) -> list[tuple[Finding, Decision]]:
142
+ ordered = sorted(findings, key=lambda f: (-f.severity.rank, f.tool, f.rule_id))
143
+ return [(f, self.policy.decide(f)) for f in ordered]
144
+
145
+ # ---------------------------------------------------------------- run
146
+
147
+ def run(self, findings: list[Finding]) -> list[Outcome]:
148
+ if is_dirty(self.repo):
149
+ self.log(f"note: uncommitted changes are ignored; OpenFix works from the last commit ({self.base[:12]}).")
150
+ if self.subdir != "." and file_at(self.repo, self.base, self.subdir) is None:
151
+ raise ValueError(
152
+ f"{self.subdir}/ is not in the last commit ({self.base[:12]}). OpenFix works from committed code; "
153
+ "commit the project first."
154
+ )
155
+ plan = self.plan(findings)
156
+ if not self.opt.dry_run:
157
+ # Fail fast on a missing SDK or credential, before any worktree is created.
158
+ refs = {self.opt.author or d.author for f, d in plan if d.action is not Action.skip and not f.package}
159
+ for ref in sorted(refs):
160
+ self.provider(ref)
161
+ outcomes: list[Outcome] = []
162
+ attempted = 0
163
+ author_ref = self.opt.author or self.policy.models.author
164
+ for f, d in plan:
165
+ if self.opt.author:
166
+ d.author = self.opt.author
167
+ if d.action is Action.skip:
168
+ outcomes.append(Outcome(f, d, "skipped", d.reason or f"policy rule '{d.rule}'"))
169
+ continue
170
+ if self.opt.max_findings is not None and attempted >= self.opt.max_findings:
171
+ outcomes.append(Outcome(f, d, "skipped", "--max limit reached"))
172
+ continue
173
+ limit = self.policy.budgets.max_usd_per_run
174
+ if limit is not None and self.spent_usd >= limit:
175
+ outcomes.append(Outcome(f, d, "skipped", f"run budget of ${limit:.2f} spent"))
176
+ continue
177
+ attempted += 1
178
+ self.log(finding_line(f))
179
+ try:
180
+ o = self.fix_one(f, d)
181
+ except Exception as exc: # noqa: BLE001 - one bad finding must not stop the run
182
+ o = Outcome(f, d, "error", f"{type(exc).__name__}: {exc}")
183
+ self.spent_usd += o.cost_usd or 0.0
184
+ self.spent_tokens += o.tokens
185
+ self.log(result_line(o.status, o.detail, [(c.name, c.status) for c in o.checks], o.pr_url))
186
+ outcomes.append(o)
187
+ self.write_summary(outcomes, author_ref)
188
+ return outcomes
189
+
190
+ def fix_one(self, f: Finding, d: Decision) -> Outcome:
191
+ out_dir = (self.out / f.id).resolve()
192
+ if out_dir.parent != self.out.resolve():
193
+ raise ValueError(f"unsafe finding id {f.id!r}")
194
+ required = list(d.require)
195
+ if self.opt.dry_run:
196
+ return Outcome(f, d, "skipped", "dry run")
197
+ with worktree(self.repo, self.base, keep=self.opt.keep_worktrees) as work:
198
+ proj = work if self.subdir == "." else work / self.subdir
199
+ for pattern in (f"{SCAN_DIR}/", "node_modules/", ".venv/", "__pycache__/"):
200
+ exclude_locally(work, pattern)
201
+ vcfg = self.policy.verify
202
+ setup = vcfg.setup.command if vcfg.setup else detect_setup_command(proj)
203
+ test_cmd = vcfg.tests.command if vcfg.tests else detect_test_command(proj)
204
+ spec = scanner_spec(vcfg.scanner, f)
205
+ scanner = Scanner(spec.model_dump() if isinstance(spec, Command) else spec, f)
206
+
207
+ # 1. Baseline on the original code.
208
+ base_scan = scan_target(scanner, proj, f) if scanner.available else None
209
+ if base_scan and not base_scan[0].error and not base_scan[1] and "rescan" in required:
210
+ return Outcome(
211
+ f,
212
+ d,
213
+ "not_reproduced",
214
+ f"{scanner.description} does not report this finding at {self.base[:12]}; "
215
+ "nothing to fix (stale or environment-specific finding).",
216
+ checks=[check_rescan(base_scan, base_scan, scanner)],
217
+ )
218
+ if setup and test_cmd:
219
+ res = self.sandbox.run(setup, proj, timeout=vcfg.setup.timeout if vcfg.setup else 1200, network=True)
220
+ if not res.ok:
221
+ self.log(f" setup failed (exit {res.exit_code}); tests may fail")
222
+ base_tests = self.sandbox.run(test_cmd, proj, timeout=900) if test_cmd else None
223
+
224
+ # 2. Produce a change.
225
+ author_info: dict[str, Any] | None = None
226
+ summary, regression_test, fixer = "", None, "agent"
227
+ dep = try_bump(proj, f) if f.package else None
228
+ cost, tokens = None, 0
229
+ if dep:
230
+ fixer = "deterministic"
231
+ summary = f"Upgrade `{dep.package}` from `{dep.old}` to `{dep.new}` in `{dep.manifest}`."
232
+ if dep.lockfile_note and setup and "npm" in setup:
233
+ self.sandbox.run(
234
+ "npm install --package-lock-only --ignore-scripts --no-audit --no-fund",
235
+ proj,
236
+ timeout=900,
237
+ network=True,
238
+ )
239
+ elif dep.lockfile_note:
240
+ summary += f" Note: {dep.lockfile_note}."
241
+ else:
242
+ if d.local_only and not self.provider(d.author).local:
243
+ return Outcome(
244
+ f,
245
+ d,
246
+ "skipped",
247
+ f"policy limits {f.location.path if f.location else 'this code'} "
248
+ "to local models; configure a local provider (e.g. ollama:...)",
249
+ )
250
+ provider = self.provider(d.author)
251
+ ws = Workspace(proj, self.base, f, self.policy, self.sandbox, test_cmd, scanner)
252
+ b = self.policy.budgets
253
+ remaining = None if b.max_usd_per_run is None else max(0.0, b.max_usd_per_run - self.spent_usd)
254
+ cap = (
255
+ min(x for x in (b.max_usd_per_fix, remaining) if x is not None)
256
+ if (b.max_usd_per_fix is not None or remaining is not None)
257
+ else None
258
+ )
259
+ agent = run_agent(provider, ws, b.max_turns, b.max_tokens_per_fix, cap, self.policy.pricing)
260
+ cost, tokens = agent.cost_usd, agent.usage.total
261
+ author_info = {
262
+ "model": d.author,
263
+ "served_by": agent.models_used,
264
+ "turns": agent.turns,
265
+ "usage": {
266
+ "input_tokens": agent.usage.input_tokens,
267
+ "output_tokens": agent.usage.output_tokens,
268
+ "cache_read_tokens": agent.usage.cache_read_tokens,
269
+ },
270
+ "cost_usd": cost,
271
+ "duration_s": agent.duration_s,
272
+ "status": agent.status,
273
+ }
274
+ out_dir.mkdir(parents=True, exist_ok=True)
275
+ (out_dir / "agent-log.json").write_text(
276
+ json.dumps(
277
+ {
278
+ "author": author_info,
279
+ "tools": agent.tool_log,
280
+ "final_text": agent.final_text,
281
+ "error": agent.error,
282
+ },
283
+ indent=2,
284
+ )
285
+ )
286
+ if agent.status != "submitted":
287
+ reason = ws.submission.summary if ws.submission else (agent.error or agent.final_text[:300])
288
+ status = (
289
+ "disputed" if agent.status == "disputed" else ("error" if agent.status == "error" else "no_fix")
290
+ )
291
+ return Outcome(
292
+ f, d, status, f"{agent.status}: {reason}", out_dir=out_dir, cost_usd=cost, tokens=tokens
293
+ )
294
+ assert ws.submission is not None
295
+ summary = ws.submission.summary + (
296
+ f"\n\nRoot cause: {ws.submission.root_cause}" if ws.submission.root_cause else ""
297
+ )
298
+ regression_test = ws.submission.regression_test
299
+
300
+ # 3. Collect the exact patch and re-check guards (defence in depth).
301
+ patch = diff_against(work, self.base)
302
+ files = changed_files(work, self.base)
303
+ if not patch.strip():
304
+ return Outcome(f, d, "no_fix", "no change was produced", out_dir=out_dir, cost_usd=cost, tokens=tokens)
305
+ violations = self.guard_violations(work, files, f)
306
+ if violations:
307
+ return Outcome(
308
+ f,
309
+ d,
310
+ "failed",
311
+ "policy guard: " + "; ".join(violations),
312
+ out_dir=out_dir,
313
+ cost_usd=cost,
314
+ tokens=tokens,
315
+ )
316
+
317
+ # 4. Independent verification on the patched code.
318
+ # Keyed by project-relative path, like the finding and the scanner output.
319
+ base_sources = {self.to_project(p): file_at(self.repo, self.base, p) or "" for p, _, _ in files}
320
+ if f.location and f.location.path not in base_sources:
321
+ base_sources[f.location.path] = file_at(self.repo, self.base, self.to_repo(f.location.path)) or ""
322
+ head_scan = scan_target(scanner, proj, f, base_sources) if base_scan else None
323
+ head_tests = self.sandbox.run(test_cmd, proj, timeout=900) if test_cmd else None
324
+ checks = [check_rescan(base_scan, head_scan, scanner), check_tests(base_tests, head_tests, test_cmd)]
325
+ checks.append(
326
+ check_regression_test(
327
+ self.repo,
328
+ self.base,
329
+ proj,
330
+ regression_test,
331
+ test_cmd,
332
+ self.sandbox,
333
+ setup,
334
+ head_tests,
335
+ base_tests,
336
+ subdir=self.subdir,
337
+ )
338
+ )
339
+ reviewer_ref = self.opt.reviewer or self.policy.models.reviewer
340
+ if "review" in required or reviewer_ref:
341
+ reviewer = None
342
+ if reviewer_ref:
343
+ try:
344
+ reviewer = self.provider(reviewer_ref)
345
+ except providers.ProviderError as exc:
346
+ self.log(f" reviewer unavailable: {exc}")
347
+ checks.append(check_review(reviewer, f, patch, summary, d.author))
348
+ status = overall(checks, required)
349
+
350
+ # 5. Receipt.
351
+ after = {
352
+ self.to_project(p): (work / p).read_text(encoding="utf-8", errors="replace")
353
+ if (work / p).exists()
354
+ else ""
355
+ for p, _, _ in files
356
+ }
357
+ file_pairs = {p: (base_sources.get(p, ""), text) for p, text in after.items()}
358
+ receipt = make_receipt(
359
+ finding=f.model_dump(mode="json", exclude={"raw"}),
360
+ decision=d.model_dump(mode="json"),
361
+ repo={"root": self.repo.name, "base_commit": self.base},
362
+ patch=patch,
363
+ files=files,
364
+ author=author_info,
365
+ checks=[c.to_dict() for c in checks],
366
+ status=status,
367
+ summary=summary,
368
+ fixer=fixer,
369
+ policy_digest=self.policy_digest,
370
+ )
371
+ paths = write_receipt(out_dir, receipt, patch, sign=self.opt.sign)
372
+ receipt_digest = sha256(paths["receipt"].read_bytes())
373
+ o = Outcome(
374
+ f,
375
+ d,
376
+ status,
377
+ _status_detail(checks, required),
378
+ checks,
379
+ out_dir,
380
+ cost_usd=cost,
381
+ tokens=tokens,
382
+ files=file_pairs,
383
+ summary=summary,
384
+ )
385
+
386
+ # 6. Pull request (autofix + verified only).
387
+ if self.opt.open_prs and d.action is Action.autofix and status == "verified":
388
+ pr = self.policy.pull_requests
389
+ body = pr_body(receipt, receipt_digest)
390
+ try:
391
+ o.pr_url = open_pull_request(
392
+ work,
393
+ branch=f"{pr.branch_prefix}{f.id}",
394
+ title=f"fix(security): {f.display_title()}"[:120],
395
+ body=body,
396
+ commit_message=f"fix(security): {f.display_title()}\n\n{summary}\n\nOpenFix-Receipt: "
397
+ f"sha256:{receipt_digest}",
398
+ labels=pr.labels,
399
+ draft=pr.draft,
400
+ base_branch=self.opt.base_branch,
401
+ )
402
+ except PublishError as exc:
403
+ o.detail += f" (PR not opened: {exc})"
404
+ elif self.opt.open_prs and status == "verified":
405
+ o.detail += " (policy says propose: patch written, no PR)"
406
+ (out_dir / "pr-body.md").write_text(pr_body(receipt, receipt_digest), encoding="utf-8")
407
+ return o
408
+
409
+ def guard_violations(self, work: Path, files: list[tuple[str, int, int]], f: Finding) -> list[str]:
410
+ g = self.policy.guards
411
+ v = []
412
+ if len(files) > g.max_files_changed:
413
+ v.append(f"{len(files)} files changed (limit {g.max_files_changed})")
414
+ lines = sum(a + r for _, a, r in files)
415
+ if lines > g.max_lines_changed:
416
+ v.append(f"{lines} lines changed (limit {g.max_lines_changed})")
417
+ for p, _, _ in files:
418
+ if self.policy.is_protected(p):
419
+ v.append(f"protected path modified: {p}")
420
+ if not g.allow_new_dependencies:
421
+ for p, _, _ in files:
422
+ if Path(p).name == "package.json":
423
+ added = _new_npm_deps(file_at(self.repo, self.base, p), work / p)
424
+ if added:
425
+ v.append(f"new dependencies added to {p}: {', '.join(sorted(added))}")
426
+ return v
427
+
428
+ def write_summary(self, outcomes: list[Outcome], author: str) -> None:
429
+ self.out.mkdir(parents=True, exist_ok=True)
430
+ meta = {
431
+ "run_id": self.run_id,
432
+ "repo": str(self.repo),
433
+ "base_commit": self.base,
434
+ "author": author,
435
+ "reviewer": self.opt.reviewer or self.policy.models.reviewer,
436
+ "totals": {"tokens": self.spent_tokens, "cost_usd": round(self.spent_usd, 4)},
437
+ }
438
+ rows = [o.to_dict() for o in outcomes]
439
+ (self.out / "summary.json").write_text(json.dumps({"meta": meta, "outcomes": rows}, indent=2))
440
+ (self.out / "summary.md").write_text(summary_markdown(rows, meta))
441
+ entries = [
442
+ {
443
+ "finding": o.finding,
444
+ "status": o.status,
445
+ "summary": o.summary,
446
+ "files": o.files,
447
+ "receipt": str(o.out_dir / "receipt.json") if o.out_dir else None,
448
+ }
449
+ for o in outcomes
450
+ if o.status not in ("skipped",)
451
+ ]
452
+ (self.out / "openfix.sarif").write_text(json.dumps(to_sarif(entries), indent=2))
453
+
454
+
455
+ def _status_detail(checks: list[Check], required: list[str]) -> str:
456
+ missing = [c.name for c in checks if c.name in required and c.status != "passed"]
457
+ if not missing:
458
+ return "all required checks passed (" + ", ".join(required) + ")"
459
+ return "; ".join(f"{c.name}: {c.status}" for c in checks if c.name in missing)
460
+
461
+
462
+ def _new_npm_deps(before: str | None, after_path: Path) -> set[str]:
463
+ def names(text: str | None) -> set[str]:
464
+ if not text:
465
+ return set()
466
+ try:
467
+ data = json.loads(text)
468
+ except json.JSONDecodeError:
469
+ return set()
470
+ return {k for s in ("dependencies", "devDependencies", "optionalDependencies") for k in (data.get(s) or {})}
471
+
472
+ after = after_path.read_text(encoding="utf-8") if after_path.exists() else None
473
+ return names(after) - names(before)
474
+
475
+
476
+ def digest(obj: Any) -> str:
477
+ return hashlib.sha256(json.dumps(obj, sort_keys=True, default=str).encode()).hexdigest()
openfix/findings.py ADDED
@@ -0,0 +1,140 @@
1
+ """Normalized finding model shared by every importer, the policy engine and the agent."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import re
8
+ from enum import Enum
9
+ from typing import Any
10
+
11
+ from pydantic import BaseModel, Field
12
+
13
+ SAFE_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
14
+
15
+
16
+ class Severity(str, Enum):
17
+ critical = "critical"
18
+ high = "high"
19
+ medium = "medium"
20
+ low = "low"
21
+ info = "info"
22
+
23
+ @property
24
+ def rank(self) -> int:
25
+ return ["info", "low", "medium", "high", "critical"].index(self.value)
26
+
27
+
28
+ class Category(str, Enum):
29
+ sast = "sast" # first-party code
30
+ sca = "sca" # vulnerable dependency
31
+ secrets = "secrets"
32
+ iac = "iac"
33
+ container = "container"
34
+ other = "other"
35
+
36
+
37
+ class Location(BaseModel):
38
+ path: str
39
+ start_line: int | None = None
40
+ end_line: int | None = None
41
+ snippet: str | None = None
42
+
43
+
44
+ class Package(BaseModel):
45
+ name: str
46
+ version: str | None = None
47
+ ecosystem: str | None = None # npm, pypi, go, maven, ...
48
+ fixed_versions: list[str] = Field(default_factory=list)
49
+ manifest: str | None = None # e.g. package.json
50
+
51
+
52
+ class Finding(BaseModel):
53
+ """One security result, independent of the tool that produced it.
54
+
55
+ Everything here except ``id`` is copied from scanner output and must be
56
+ treated as untrusted data when it is shown to a model.
57
+ """
58
+
59
+ id: str = ""
60
+ tool: str
61
+ rule_id: str
62
+ title: str
63
+ message: str = ""
64
+ severity: Severity = Severity.medium
65
+ category: Category = Category.sast
66
+ cwe: list[str] = Field(default_factory=list)
67
+ advisories: list[str] = Field(default_factory=list) # CVE / GHSA / tool ids
68
+ location: Location | None = None
69
+ package: Package | None = None
70
+ help_uri: str | None = None
71
+ source_format: str = "unknown"
72
+ raw: dict[str, Any] = Field(default_factory=dict, repr=False)
73
+
74
+ def model_post_init(self, __context: Any) -> None:
75
+ # Ids become directory and branch names, and reports are untrusted: only allow a safe charset.
76
+ if not self.id or not SAFE_ID.fullmatch(self.id):
77
+ self.id = self.fingerprint()
78
+
79
+ def fingerprint(self) -> str:
80
+ """Stable id: same tool + rule + place (or package) -> same id across runs."""
81
+ place: Any
82
+ if self.package:
83
+ place = [self.package.name, self.package.version, sorted(self.advisories)]
84
+ elif self.location:
85
+ place = [self.location.path, self.location.start_line]
86
+ else:
87
+ place = [self.title]
88
+ blob = json.dumps([self.tool.lower(), self.rule_id, place], sort_keys=True)
89
+ return "of-" + hashlib.sha256(blob.encode()).hexdigest()[:12]
90
+
91
+ def display_title(self) -> str:
92
+ """The title, unless the scanner only filled in a placeholder (Semgrep: "Semgrep Finding: <rule>")."""
93
+ generic = f"{self.tool.split()[0].lower()} finding" if self.tool else ""
94
+ if not self.title or (generic and self.title.lower().startswith(generic)):
95
+ return self.rule_id
96
+ return self.title
97
+
98
+ def short(self) -> str:
99
+ where = ""
100
+ if self.location:
101
+ where = self.location.path + (f":{self.location.start_line}" if self.location.start_line else "")
102
+ elif self.package:
103
+ where = f"{self.package.name}@{self.package.version or '?'}"
104
+ return f"[{self.severity.value}] {self.rule_id} {where}".strip()
105
+
106
+
107
+ SEVERITY_WORDS = {
108
+ "critical": Severity.critical,
109
+ "high": Severity.high,
110
+ "error": Severity.high,
111
+ "medium": Severity.medium,
112
+ "moderate": Severity.medium,
113
+ "warning": Severity.medium,
114
+ "low": Severity.low,
115
+ "note": Severity.low,
116
+ "info": Severity.info,
117
+ "informational": Severity.info,
118
+ "none": Severity.info,
119
+ "unknown": Severity.medium,
120
+ }
121
+
122
+
123
+ def severity_from(value: Any = None, score: Any = None) -> Severity:
124
+ """Map a CVSS-like score or a tool's severity word onto Severity."""
125
+ if score not in (None, ""):
126
+ try:
127
+ s = float(score)
128
+ except (TypeError, ValueError):
129
+ s = -1
130
+ if s >= 9:
131
+ return Severity.critical
132
+ if s >= 7:
133
+ return Severity.high
134
+ if s >= 4:
135
+ return Severity.medium
136
+ if s > 0:
137
+ return Severity.low
138
+ if s == 0:
139
+ return Severity.info
140
+ return SEVERITY_WORDS.get(str(value or "unknown").strip().lower(), Severity.medium)