@openai/codex-security 0.1.0
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.
- package/LICENSE +201 -0
- package/README.md +306 -0
- package/_bundled_plugin/.app.json +20 -0
- package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
- package/_bundled_plugin/.mcp.json +20 -0
- package/_bundled_plugin/assets/logo.png +0 -0
- package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
- package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
- package/_bundled_plugin/mcp/server.mjs +24 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
- package/_bundled_plugin/references/config-preflight.md +115 -0
- package/_bundled_plugin/references/final-report.md +205 -0
- package/_bundled_plugin/references/finding-detail-fields.md +162 -0
- package/_bundled_plugin/references/sarif-adapter.md +26 -0
- package/_bundled_plugin/references/scan-artifacts.md +116 -0
- package/_bundled_plugin/references/scan-contract.md +164 -0
- package/_bundled_plugin/references/security-guidance.md +15 -0
- package/_bundled_plugin/references/shared-hard-rules.md +15 -0
- package/_bundled_plugin/references/static-finding-assessment.md +75 -0
- package/_bundled_plugin/schemas/coverage.schema.json +228 -0
- package/_bundled_plugin/schemas/findings.schema.json +359 -0
- package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
- package/_bundled_plugin/scripts/config_preflight.py +901 -0
- package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
- package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
- package/_bundled_plugin/scripts/finding_preview.py +270 -0
- package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
- package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
- package/_bundled_plugin/scripts/rank_preview.py +968 -0
- package/_bundled_plugin/scripts/report_projection.py +844 -0
- package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
- package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
- package/_bundled_plugin/scripts/validate_report_format.py +138 -0
- package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
- package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
- package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
- package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
- package/_bundled_plugin/scripts/workbench_cli.py +325 -0
- package/_bundled_plugin/scripts/workbench_constants.py +81 -0
- package/_bundled_plugin/scripts/workbench_db.py +3728 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
- package/_bundled_plugin/scripts/workbench_progress.py +226 -0
- package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
- package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
- package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
- package/_bundled_plugin/scripts/workbench_schema.py +714 -0
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
- package/_bundled_plugin/scripts/workbench_target.py +469 -0
- package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
- package/_bundled_plugin/scripts/workbench_validation.py +294 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
- package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
- package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
- package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
- package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
- package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
- package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
- package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
- package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
- package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
- package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
- package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
- package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
- package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
- package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
- package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
- package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
- package/_bundled_plugin/skills/validation/SKILL.md +110 -0
- package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
- package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
- package/bin/codex-security.mjs +26 -0
- package/dist/api.d.ts +112 -0
- package/dist/api.d.ts.map +1 -0
- package/dist/api.js +1051 -0
- package/dist/api.js.map +1 -0
- package/dist/auth.d.ts +29 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +246 -0
- package/dist/auth.js.map +1 -0
- package/dist/bulk-scan-discovery.d.ts +35 -0
- package/dist/bulk-scan-discovery.d.ts.map +1 -0
- package/dist/bulk-scan-discovery.js +217 -0
- package/dist/bulk-scan-discovery.js.map +1 -0
- package/dist/cli.d.ts +67 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +2128 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +19 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +199 -0
- package/dist/config.js.map +1 -0
- package/dist/contract.d.ts +21 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +848 -0
- package/dist/contract.js.map +1 -0
- package/dist/cost.d.ts +30 -0
- package/dist/cost.d.ts.map +1 -0
- package/dist/cost.js +280 -0
- package/dist/cost.js.map +1 -0
- package/dist/errors.d.ts +38 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +52 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/knowledge-base.d.ts +7 -0
- package/dist/knowledge-base.d.ts.map +1 -0
- package/dist/knowledge-base.js +181 -0
- package/dist/knowledge-base.js.map +1 -0
- package/dist/models.d.ts +231 -0
- package/dist/models.d.ts.map +1 -0
- package/dist/models.js +3 -0
- package/dist/models.js.map +1 -0
- package/dist/multiscan.d.ts +30 -0
- package/dist/multiscan.d.ts.map +1 -0
- package/dist/multiscan.js +397 -0
- package/dist/multiscan.js.map +1 -0
- package/dist/result.d.ts +39 -0
- package/dist/result.d.ts.map +1 -0
- package/dist/result.js +71 -0
- package/dist/result.js.map +1 -0
- package/dist/runtime.d.ts +69 -0
- package/dist/runtime.d.ts.map +1 -0
- package/dist/runtime.js +997 -0
- package/dist/runtime.js.map +1 -0
- package/dist/scan-comparison.d.ts +42 -0
- package/dist/scan-comparison.d.ts.map +1 -0
- package/dist/scan-comparison.js +153 -0
- package/dist/scan-comparison.js.map +1 -0
- package/dist/scan-history-renderer.d.ts +13 -0
- package/dist/scan-history-renderer.d.ts.map +1 -0
- package/dist/scan-history-renderer.js +297 -0
- package/dist/scan-history-renderer.js.map +1 -0
- package/dist/targets.d.ts +39 -0
- package/dist/targets.d.ts.map +1 -0
- package/dist/targets.js +295 -0
- package/dist/targets.js.map +1 -0
- package/dist/trusted-executable.d.ts +6 -0
- package/dist/trusted-executable.d.ts.map +1 -0
- package/dist/trusted-executable.js +77 -0
- package/dist/trusted-executable.js.map +1 -0
- package/dist/version.d.ts +6 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +42 -0
- package/dist/version.js.map +1 -0
- package/dist/worker-progress.d.ts +13 -0
- package/dist/worker-progress.d.ts.map +1 -0
- package/dist/worker-progress.js +113 -0
- package/dist/worker-progress.js.map +1 -0
- package/package.json +74 -0
|
@@ -0,0 +1,844 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Project canonical Codex Security scan JSON into the standard reports."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import importlib.util
|
|
8
|
+
import re
|
|
9
|
+
from collections import Counter
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from types import ModuleType
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}
|
|
15
|
+
CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
|
|
16
|
+
REPORTABLE_SEVERITIES = {"critical", "high", "medium", "low"}
|
|
17
|
+
DISPOSITION_LABELS = {
|
|
18
|
+
"reported": "Reported",
|
|
19
|
+
"no_issue_found": "No issue found",
|
|
20
|
+
"rejected": "Rejected",
|
|
21
|
+
"not_applicable": "Not applicable",
|
|
22
|
+
"needs_follow_up": "Needs follow-up",
|
|
23
|
+
}
|
|
24
|
+
WRITEUP_REPORT_PATH_RE = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class ReportProjectionError(ValueError):
|
|
28
|
+
"""Raised when a canonical scan cannot be projected into a valid report."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _load_script(name: str) -> ModuleType:
|
|
32
|
+
path = Path(__file__).resolve().parent / f"{name}.py"
|
|
33
|
+
spec = importlib.util.spec_from_file_location(f"codex_security_{name}", path)
|
|
34
|
+
if spec is None or spec.loader is None:
|
|
35
|
+
raise ReportProjectionError(f"could not load report helper: {path}")
|
|
36
|
+
module = importlib.util.module_from_spec(spec)
|
|
37
|
+
spec.loader.exec_module(module)
|
|
38
|
+
return module
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _text(value: Any, fallback: str) -> str:
|
|
42
|
+
candidate = value if isinstance(value, str) and value.strip() else fallback
|
|
43
|
+
normalized = " ".join(candidate.split())
|
|
44
|
+
if not normalized:
|
|
45
|
+
return ""
|
|
46
|
+
if re.match(r"^(?:#{1,6}\s|[-*+]\s|>\s|```|\d+\.\s|\|)", normalized):
|
|
47
|
+
normalized = f"Text: {normalized}"
|
|
48
|
+
rendered: list[str] = []
|
|
49
|
+
cursor = 0
|
|
50
|
+
for match in re.finditer(r"(?<!`)`([^`\n]+)`(?!`)", normalized):
|
|
51
|
+
rendered.append(_escape_markdown_text(normalized[cursor : match.start()]))
|
|
52
|
+
rendered.append(f"`{match.group(1)}`")
|
|
53
|
+
cursor = match.end()
|
|
54
|
+
rendered.append(_escape_markdown_text(normalized[cursor:]))
|
|
55
|
+
return "".join(rendered)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _escape_markdown_text(value: str) -> str:
|
|
59
|
+
return re.sub(r"([\\`*\[\]<>])", r"\\\1", value)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _strings(value: Any) -> list[str]:
|
|
63
|
+
if not isinstance(value, list):
|
|
64
|
+
return []
|
|
65
|
+
normalized: list[str] = []
|
|
66
|
+
for item in value:
|
|
67
|
+
text = _text(item, "")
|
|
68
|
+
if text:
|
|
69
|
+
normalized.append(text)
|
|
70
|
+
return normalized
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _cell(value: Any) -> str:
|
|
74
|
+
return _text(value, "none").replace("|", "\\|").replace("\n", "<br>")
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _link_label(value: Any, fallback: str) -> str:
|
|
78
|
+
return _cell(value) or _cell(fallback)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _deep_report_id(finding: dict[str, Any]) -> str:
|
|
82
|
+
extensions = finding.get("extensions")
|
|
83
|
+
if isinstance(extensions, dict):
|
|
84
|
+
report_id = extensions.get("reportId")
|
|
85
|
+
if isinstance(report_id, str) and report_id.strip():
|
|
86
|
+
return report_id
|
|
87
|
+
ledger_row_id = extensions.get("ledgerRowId")
|
|
88
|
+
if isinstance(ledger_row_id, str) and ledger_row_id.strip():
|
|
89
|
+
return ledger_row_id
|
|
90
|
+
identity = finding.get("identity")
|
|
91
|
+
if isinstance(identity, dict):
|
|
92
|
+
instance = identity.get("instance")
|
|
93
|
+
if isinstance(instance, str) and instance.strip():
|
|
94
|
+
return instance
|
|
95
|
+
occurrence_id = finding.get("occurrenceId")
|
|
96
|
+
return (
|
|
97
|
+
occurrence_id
|
|
98
|
+
if isinstance(occurrence_id, str) and occurrence_id.strip()
|
|
99
|
+
else "Unidentified report"
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _deep_candidate_id(finding: dict[str, Any]) -> str:
|
|
104
|
+
extensions = finding.get("extensions")
|
|
105
|
+
if isinstance(extensions, dict):
|
|
106
|
+
candidate_id = extensions.get("candidateId")
|
|
107
|
+
if isinstance(candidate_id, str) and candidate_id.strip():
|
|
108
|
+
return candidate_id
|
|
109
|
+
return _deep_report_id(finding)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _has_deep_child_metadata(finding: dict[str, Any]) -> bool:
|
|
113
|
+
extensions = finding.get("extensions")
|
|
114
|
+
if not isinstance(extensions, dict):
|
|
115
|
+
return False
|
|
116
|
+
return any(
|
|
117
|
+
isinstance(extensions.get(field), str) and extensions[field].strip()
|
|
118
|
+
for field in ("candidateId", "reportId")
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _uses_deep_presentation(coverage: dict[str, Any], findings: list[dict[str, Any]]) -> bool:
|
|
123
|
+
if coverage.get("mode") == "deep_repository":
|
|
124
|
+
return True
|
|
125
|
+
if coverage.get("mode") != "scoped_path":
|
|
126
|
+
return False
|
|
127
|
+
# Scoped deep scans can arrive as scoped_path artifacts. The child ids are
|
|
128
|
+
# the stable deep-scan signal; ordinary scoped scans do not emit them.
|
|
129
|
+
return any(_has_deep_child_metadata(finding) for finding in findings)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _deep_title_parts(finding: dict[str, Any]) -> tuple[str, str | None]:
|
|
133
|
+
title = finding.get("title")
|
|
134
|
+
if not isinstance(title, str):
|
|
135
|
+
return "Untitled finding", None
|
|
136
|
+
normalized = " ".join(title.split())
|
|
137
|
+
match = re.fullmatch(r"(.+?)\s+\[([^\[\]\n]+)\]", normalized)
|
|
138
|
+
if match is None:
|
|
139
|
+
return normalized, None
|
|
140
|
+
annotation = match.group(2)
|
|
141
|
+
extensions = finding.get("extensions")
|
|
142
|
+
recognized_ids = [_deep_report_id(finding)]
|
|
143
|
+
if isinstance(extensions, dict):
|
|
144
|
+
ledger_row_id = extensions.get("ledgerRowId")
|
|
145
|
+
if isinstance(ledger_row_id, str) and ledger_row_id.strip():
|
|
146
|
+
recognized_ids.append(ledger_row_id)
|
|
147
|
+
if any(
|
|
148
|
+
annotation == report_id or annotation.startswith(f"{report_id};")
|
|
149
|
+
for report_id in recognized_ids
|
|
150
|
+
):
|
|
151
|
+
return match.group(1), annotation
|
|
152
|
+
return normalized, None
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _deep_finding_title(finding: dict[str, Any]) -> str:
|
|
156
|
+
return _deep_title_parts(finding)[0]
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def _deep_finding_groups(
|
|
160
|
+
findings: list[dict[str, Any]], writeup_paths: list[str | None]
|
|
161
|
+
) -> list[list[tuple[int, dict[str, Any], str | None]]]:
|
|
162
|
+
groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
|
|
163
|
+
for number, (finding, report_path) in enumerate(zip(findings, writeup_paths, strict=True), 1):
|
|
164
|
+
groups.setdefault(_deep_candidate_id(finding), []).append((number, finding, report_path))
|
|
165
|
+
return list(groups.values())
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _deep_group_titles(group: list[tuple[int, dict[str, Any], str | None]]) -> str:
|
|
169
|
+
titles: list[str] = []
|
|
170
|
+
for _, finding, _ in group:
|
|
171
|
+
title = _cell(_deep_finding_title(finding))
|
|
172
|
+
if title not in titles:
|
|
173
|
+
titles.append(title)
|
|
174
|
+
return "<br>".join(titles)
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _deep_group_levels(
|
|
178
|
+
group: list[tuple[int, dict[str, Any], str | None]],
|
|
179
|
+
field: str,
|
|
180
|
+
order: dict[str, int],
|
|
181
|
+
) -> str:
|
|
182
|
+
levels = {finding[field]["level"] for _, finding, _ in group}
|
|
183
|
+
return "<br>".join(sorted(levels, key=lambda level: order.get(level, len(order))))
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def _deep_group_report_labels(
|
|
187
|
+
group: list[tuple[int, dict[str, Any], str | None]],
|
|
188
|
+
) -> list[str]:
|
|
189
|
+
report_ids = [_deep_report_id(finding) for _, finding, _ in group]
|
|
190
|
+
report_id_counts = Counter(report_ids)
|
|
191
|
+
labels = [
|
|
192
|
+
(_deep_title_parts(finding)[1] if report_id_counts[report_id] > 1 else report_id)
|
|
193
|
+
or report_id
|
|
194
|
+
for report_id, (_, finding, _) in zip(report_ids, group, strict=True)
|
|
195
|
+
]
|
|
196
|
+
label_counts = Counter(labels)
|
|
197
|
+
return [
|
|
198
|
+
(
|
|
199
|
+
finding.get("identity", {}).get("instance")
|
|
200
|
+
if label_counts[label] > 1 and isinstance(finding.get("identity"), dict)
|
|
201
|
+
else label
|
|
202
|
+
)
|
|
203
|
+
or _deep_report_id(finding)
|
|
204
|
+
for label, (_, finding, _) in zip(labels, group, strict=True)
|
|
205
|
+
]
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def _deep_group_report_links(group: list[tuple[int, dict[str, Any], str | None]]) -> str:
|
|
209
|
+
labels = _deep_group_report_labels(group)
|
|
210
|
+
return "<br>".join(
|
|
211
|
+
f"[{_link_label(label, 'Unidentified report')}](#finding-{number})"
|
|
212
|
+
for label, (number, _, _) in zip(labels, group, strict=True)
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def _deep_group_writeup_links(group: list[tuple[int, dict[str, Any], str | None]]) -> str:
|
|
217
|
+
labels = _deep_group_report_labels(group)
|
|
218
|
+
links: list[str] = []
|
|
219
|
+
for label, (_, _, report_path) in zip(labels, group, strict=True):
|
|
220
|
+
report_id = _link_label(label, "Unidentified report")
|
|
221
|
+
links.append(
|
|
222
|
+
f"[Open {report_id}]({report_path})" if report_path else f"{report_id}: inline below"
|
|
223
|
+
)
|
|
224
|
+
return "<br>".join(links)
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _writeup_report_path(finding: dict[str, Any]) -> str | None:
|
|
228
|
+
writeup = finding.get("writeup")
|
|
229
|
+
if writeup is None:
|
|
230
|
+
return None
|
|
231
|
+
if not isinstance(writeup, dict):
|
|
232
|
+
raise ReportProjectionError("finding writeup must be an object")
|
|
233
|
+
report_path = writeup.get("reportPath")
|
|
234
|
+
if not isinstance(report_path, str) or not WRITEUP_REPORT_PATH_RE.fullmatch(report_path):
|
|
235
|
+
raise ReportProjectionError("finding writeup has an invalid reportPath")
|
|
236
|
+
return report_path
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def _hardening_portfolio_path(scan: dict[str, Any]) -> str | None:
|
|
240
|
+
hardening = scan.get("hardening")
|
|
241
|
+
if hardening is None:
|
|
242
|
+
return None
|
|
243
|
+
if not isinstance(hardening, dict):
|
|
244
|
+
raise ReportProjectionError("scan hardening must be an object")
|
|
245
|
+
portfolio_path = hardening.get("portfolioPath")
|
|
246
|
+
if portfolio_path != "hardening/hardening.md":
|
|
247
|
+
raise ReportProjectionError("scan hardening has an invalid portfolioPath")
|
|
248
|
+
return portfolio_path
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _bullets(items: list[str], fallback: str) -> list[str]:
|
|
252
|
+
return [f"- {item}" for item in (items or [fallback])]
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _code_evidence_catalog(finding: dict[str, Any]) -> dict[str, dict[str, Any]]:
|
|
256
|
+
raw = finding.get("codeEvidence", finding.get("code_evidence", []))
|
|
257
|
+
if not isinstance(raw, list):
|
|
258
|
+
return {}
|
|
259
|
+
return {
|
|
260
|
+
item["id"]: item
|
|
261
|
+
for item in raw
|
|
262
|
+
if isinstance(item, dict)
|
|
263
|
+
and isinstance(item.get("id"), str)
|
|
264
|
+
and isinstance(item.get("code"), str)
|
|
265
|
+
and item["code"].strip()
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def _section_code_evidence(
|
|
270
|
+
finding: dict[str, Any], section: dict[str, Any]
|
|
271
|
+
) -> list[dict[str, Any]]:
|
|
272
|
+
catalog = _code_evidence_catalog(finding)
|
|
273
|
+
refs = section.get("evidenceRefs", section.get("evidence_refs", []))
|
|
274
|
+
resolved = (
|
|
275
|
+
[catalog[ref] for ref in refs if isinstance(ref, str) and ref in catalog]
|
|
276
|
+
if isinstance(refs, list)
|
|
277
|
+
else []
|
|
278
|
+
)
|
|
279
|
+
embedded = section.get("codeEvidence", section.get("code_evidence", []))
|
|
280
|
+
if isinstance(embedded, list):
|
|
281
|
+
resolved.extend(
|
|
282
|
+
item
|
|
283
|
+
for item in embedded
|
|
284
|
+
if isinstance(item, dict) and isinstance(item.get("code"), str) and item["code"].strip()
|
|
285
|
+
)
|
|
286
|
+
unique: list[dict[str, Any]] = []
|
|
287
|
+
seen: set[tuple[str, str]] = set()
|
|
288
|
+
for item in resolved:
|
|
289
|
+
key = (str(item.get("id", "")), item["code"])
|
|
290
|
+
if key in seen:
|
|
291
|
+
continue
|
|
292
|
+
seen.add(key)
|
|
293
|
+
unique.append(item)
|
|
294
|
+
return unique
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def _root_cause_code_evidence(
|
|
298
|
+
finding: dict[str, Any], root_cause: dict[str, Any]
|
|
299
|
+
) -> list[dict[str, Any]]:
|
|
300
|
+
evidence = _section_code_evidence(finding, root_cause)
|
|
301
|
+
legacy_code = root_cause.get("code")
|
|
302
|
+
if not isinstance(legacy_code, str) or not legacy_code.strip():
|
|
303
|
+
return evidence
|
|
304
|
+
if any(item["code"] == legacy_code for item in evidence):
|
|
305
|
+
return evidence
|
|
306
|
+
root_location = next(
|
|
307
|
+
(
|
|
308
|
+
location
|
|
309
|
+
for location in finding.get("locations", [])
|
|
310
|
+
if isinstance(location, dict) and location.get("role") == "root_control"
|
|
311
|
+
),
|
|
312
|
+
{},
|
|
313
|
+
)
|
|
314
|
+
return [
|
|
315
|
+
*evidence,
|
|
316
|
+
{
|
|
317
|
+
"code": legacy_code,
|
|
318
|
+
"label": "Broken control",
|
|
319
|
+
"language": root_cause.get("language", ""),
|
|
320
|
+
"location": root_location,
|
|
321
|
+
},
|
|
322
|
+
]
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _code_evidence_location(item: dict[str, Any]) -> str:
|
|
326
|
+
location = item.get("location")
|
|
327
|
+
if isinstance(location, str):
|
|
328
|
+
return location
|
|
329
|
+
if isinstance(location, dict):
|
|
330
|
+
item = location
|
|
331
|
+
path = item.get("path")
|
|
332
|
+
start = item.get("startLine")
|
|
333
|
+
end = item.get("endLine", start)
|
|
334
|
+
if not isinstance(path, str) or not path:
|
|
335
|
+
return ""
|
|
336
|
+
if not isinstance(start, int):
|
|
337
|
+
return path
|
|
338
|
+
return f"{path}:{start}" if end == start else f"{path}:{start}-{end}"
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def _code_fence(code: str) -> str:
|
|
342
|
+
longest_run = max((len(match.group(0)) for match in re.finditer(r"`+", code)), default=0)
|
|
343
|
+
return "`" * max(3, longest_run + 1)
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
def _code_evidence_lines(evidence: list[dict[str, Any]]) -> list[str]:
|
|
347
|
+
lines: list[str] = []
|
|
348
|
+
for index, item in enumerate(evidence):
|
|
349
|
+
label = _text(item.get("label"), f"Code evidence {index + 1}")
|
|
350
|
+
location = _text(_code_evidence_location(item), "")
|
|
351
|
+
explanation = _text(item.get("explanation"), "")
|
|
352
|
+
language = item.get("language") if isinstance(item.get("language"), str) else ""
|
|
353
|
+
language = language if re.fullmatch(r"[A-Za-z0-9_+.-]*", language) else ""
|
|
354
|
+
code = item["code"]
|
|
355
|
+
fence = _code_fence(code)
|
|
356
|
+
heading = f"**{label}**"
|
|
357
|
+
if location:
|
|
358
|
+
heading += f" — `{location}`"
|
|
359
|
+
lines.extend(["", heading])
|
|
360
|
+
if explanation:
|
|
361
|
+
lines.extend(["", explanation])
|
|
362
|
+
lines.extend(["", f"{fence}{language}", code, fence])
|
|
363
|
+
return lines
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def _severity_mix(findings: list[dict[str, Any]]) -> str:
|
|
367
|
+
counts = Counter(finding["severity"]["level"] for finding in findings)
|
|
368
|
+
return (
|
|
369
|
+
", ".join(f"{level}: {counts[level]}" for level in SEVERITY_ORDER if counts[level])
|
|
370
|
+
or "none"
|
|
371
|
+
)
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
def _confidence_mix(findings: list[dict[str, Any]]) -> str:
|
|
375
|
+
counts = Counter(finding["confidence"]["level"] for finding in findings)
|
|
376
|
+
return (
|
|
377
|
+
", ".join(
|
|
378
|
+
f"{level}: {counts[level]}" for level in ("high", "medium", "low") if counts[level]
|
|
379
|
+
)
|
|
380
|
+
or "none"
|
|
381
|
+
)
|
|
382
|
+
|
|
383
|
+
|
|
384
|
+
def _locations(finding: dict[str, Any]) -> str:
|
|
385
|
+
rendered = []
|
|
386
|
+
for location in finding["locations"]:
|
|
387
|
+
start = location["startLine"]
|
|
388
|
+
end = location.get("endLine", start)
|
|
389
|
+
suffix = f":{start}" if end == start else f":{start}-{end}"
|
|
390
|
+
rendered.append(f"{location['path']}{suffix}")
|
|
391
|
+
return ", ".join(rendered)
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def _finding_sort_key(finding: dict[str, Any]) -> tuple[int, str, str]:
|
|
395
|
+
return (
|
|
396
|
+
SEVERITY_ORDER.get(finding["severity"]["level"], len(SEVERITY_ORDER)),
|
|
397
|
+
finding.get("occurrenceId", ""),
|
|
398
|
+
finding["title"],
|
|
399
|
+
)
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def _target_scope_lines(target: dict[str, Any]) -> list[str]:
|
|
403
|
+
lines = [
|
|
404
|
+
f"- Target kind: {_text(target.get('kind'), 'not recorded')}",
|
|
405
|
+
f"- Target ID: {_text(target.get('targetId'), 'not recorded')}",
|
|
406
|
+
]
|
|
407
|
+
base_revision = _text(target.get("baseRevision"), "")
|
|
408
|
+
head_revision = _text(target.get("headRevision"), "")
|
|
409
|
+
if base_revision or head_revision:
|
|
410
|
+
lines.append(
|
|
411
|
+
f"- Revision range: {base_revision or 'unknown'}...{head_revision or 'unknown'}"
|
|
412
|
+
)
|
|
413
|
+
revision = _text(target.get("revision"), "")
|
|
414
|
+
if revision:
|
|
415
|
+
lines.append(f"- Revision: {revision}")
|
|
416
|
+
snapshot_digest = _text(target.get("snapshotDigest"), "")
|
|
417
|
+
if snapshot_digest:
|
|
418
|
+
lines.append(f"- Snapshot digest: {snapshot_digest}")
|
|
419
|
+
return lines
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def _surface_notes(surface: dict[str, Any]) -> str:
|
|
423
|
+
notes = surface.get("notes", "No additional canonical notes were recorded.")
|
|
424
|
+
receipt_refs = surface.get("receiptRefs", [])
|
|
425
|
+
if not isinstance(receipt_refs, list) or not receipt_refs:
|
|
426
|
+
return _cell(notes)
|
|
427
|
+
evidence = ", ".join(item for item in receipt_refs if isinstance(item, str))
|
|
428
|
+
if not evidence:
|
|
429
|
+
return _cell(notes)
|
|
430
|
+
return _cell(f"{notes} Evidence: {evidence}")
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
|
|
434
|
+
validation = finding.get("validation") if isinstance(finding.get("validation"), dict) else {}
|
|
435
|
+
raw_root_cause = finding.get("rootCause")
|
|
436
|
+
root_cause = raw_root_cause if isinstance(raw_root_cause, dict) else {}
|
|
437
|
+
attack_path = finding.get("attackPath") if isinstance(finding.get("attackPath"), dict) else {}
|
|
438
|
+
dataflow = attack_path.get("dataflow") if isinstance(attack_path.get("dataflow"), dict) else {}
|
|
439
|
+
reachability = (
|
|
440
|
+
attack_path.get("reachability") if isinstance(attack_path.get("reachability"), dict) else {}
|
|
441
|
+
)
|
|
442
|
+
severity = finding["severity"]
|
|
443
|
+
validation_summary = _text(
|
|
444
|
+
validation.get("summary"),
|
|
445
|
+
f"{finding['confidence']['rationale']} Validation details were not recorded separately.",
|
|
446
|
+
)
|
|
447
|
+
validation_evidence = _strings(validation.get("evidence"))
|
|
448
|
+
validation_counterevidence = _strings(validation.get("counterEvidence"))
|
|
449
|
+
root_cause_summary = _text(
|
|
450
|
+
raw_root_cause if isinstance(raw_root_cause, str) else root_cause.get("summary"),
|
|
451
|
+
"",
|
|
452
|
+
)
|
|
453
|
+
root_cause_code_evidence = _root_cause_code_evidence(finding, root_cause)
|
|
454
|
+
validation_code_evidence = _section_code_evidence(finding, validation)
|
|
455
|
+
attack_path_code_evidence = _section_code_evidence(finding, attack_path)
|
|
456
|
+
dataflow_summary = _text(
|
|
457
|
+
dataflow.get("summary"),
|
|
458
|
+
f"The canonical finding records the affected path at {_locations(finding)}, but no expanded source-to-sink narrative was recorded.",
|
|
459
|
+
)
|
|
460
|
+
reachability_summary = _text(
|
|
461
|
+
reachability.get("summary"),
|
|
462
|
+
"Reachability was not recorded beyond the canonical finding summary and affected locations.",
|
|
463
|
+
)
|
|
464
|
+
severity_rationale = _text(
|
|
465
|
+
severity.get("rationale"),
|
|
466
|
+
f"The scan assigned {severity['level']} severity; no separate canonical severity rationale was recorded.",
|
|
467
|
+
)
|
|
468
|
+
severity_change = _text(
|
|
469
|
+
severity.get("changeConditions"),
|
|
470
|
+
"Additional runtime or deployment evidence could raise or lower this severity.",
|
|
471
|
+
)
|
|
472
|
+
remediation_tests = _strings(finding.get("remediationTests"))
|
|
473
|
+
preventive_controls = _strings(finding.get("preventiveControls"))
|
|
474
|
+
cwes = ", ".join(finding["taxonomy"]["cwe"]) or "none"
|
|
475
|
+
title = _text(finding["title"], "Untitled finding")
|
|
476
|
+
lines = [
|
|
477
|
+
f'<a id="finding-{number}"></a>',
|
|
478
|
+
"",
|
|
479
|
+
f"### [{number}] {title}",
|
|
480
|
+
"",
|
|
481
|
+
"| Field | Value |",
|
|
482
|
+
"| --- | --- |",
|
|
483
|
+
f"| Severity | {_cell(severity['level'])} |",
|
|
484
|
+
f"| Confidence | {_cell(finding['confidence']['level'])} |",
|
|
485
|
+
f"| Confidence rationale | {_cell(finding['confidence']['rationale'])} |",
|
|
486
|
+
f"| Category | {_cell(finding['taxonomy']['category'])} |",
|
|
487
|
+
f"| CWE | {_cell(cwes)} |",
|
|
488
|
+
f"| Affected lines | {_cell(_locations(finding))} |",
|
|
489
|
+
"",
|
|
490
|
+
"#### Summary",
|
|
491
|
+
"",
|
|
492
|
+
_text(finding["summary"], "No canonical finding summary was recorded."),
|
|
493
|
+
]
|
|
494
|
+
if root_cause_summary or root_cause_code_evidence:
|
|
495
|
+
lines.extend(["", "#### Root Cause", ""])
|
|
496
|
+
if root_cause_summary:
|
|
497
|
+
lines.append(root_cause_summary)
|
|
498
|
+
lines.extend(_code_evidence_lines(root_cause_code_evidence))
|
|
499
|
+
lines.extend(["", "#### Validation", "", validation_summary])
|
|
500
|
+
if validation.get("method"):
|
|
501
|
+
lines.extend(["", f"Validation method: {_text(validation['method'], 'not recorded')}"])
|
|
502
|
+
lines.extend(_code_evidence_lines(validation_code_evidence))
|
|
503
|
+
if validation_evidence:
|
|
504
|
+
lines.extend(["", "Evidence:", *_bullets(validation_evidence, "No evidence recorded.")])
|
|
505
|
+
if validation_counterevidence:
|
|
506
|
+
lines.extend(
|
|
507
|
+
[
|
|
508
|
+
"",
|
|
509
|
+
"Counterevidence and remaining uncertainty:",
|
|
510
|
+
*_bullets(validation_counterevidence, "None recorded."),
|
|
511
|
+
]
|
|
512
|
+
)
|
|
513
|
+
lines.extend(["", "#### Dataflow", "", dataflow_summary])
|
|
514
|
+
for label, key in (("Source", "source"), ("Sink", "sink"), ("Outcome", "outcome")):
|
|
515
|
+
if dataflow.get(key):
|
|
516
|
+
lines.extend(["", f"- **{label}:** {_text(dataflow[key], 'not recorded')}"])
|
|
517
|
+
transformations = _strings(dataflow.get("transformations"))
|
|
518
|
+
if transformations:
|
|
519
|
+
lines.extend(["", "Transformations:", *_bullets(transformations, "None recorded.")])
|
|
520
|
+
lines.extend(_code_evidence_lines(attack_path_code_evidence))
|
|
521
|
+
lines.extend(["", "#### Reachability", "", reachability_summary])
|
|
522
|
+
for label, key in (
|
|
523
|
+
("Attacker", "attacker"),
|
|
524
|
+
("Entry point", "entrypoint"),
|
|
525
|
+
("Outcome", "outcome"),
|
|
526
|
+
):
|
|
527
|
+
if reachability.get(key):
|
|
528
|
+
lines.extend(["", f"- **{label}:** {_text(reachability[key], 'not recorded')}"])
|
|
529
|
+
preconditions = _strings(reachability.get("preconditions"))
|
|
530
|
+
if preconditions:
|
|
531
|
+
lines.extend(["", "Preconditions:", *_bullets(preconditions, "None recorded.")])
|
|
532
|
+
lines.extend(
|
|
533
|
+
[
|
|
534
|
+
"",
|
|
535
|
+
"#### Severity",
|
|
536
|
+
"",
|
|
537
|
+
f"**{severity['level'].capitalize()}** — {severity_rationale}",
|
|
538
|
+
"",
|
|
539
|
+
severity_change,
|
|
540
|
+
"",
|
|
541
|
+
"#### Remediation",
|
|
542
|
+
"",
|
|
543
|
+
_text(finding["remediation"], "No canonical remediation was recorded."),
|
|
544
|
+
]
|
|
545
|
+
)
|
|
546
|
+
if remediation_tests:
|
|
547
|
+
lines.extend(["", "Tests:", *_bullets(remediation_tests, "No tests recorded.")])
|
|
548
|
+
if preventive_controls:
|
|
549
|
+
lines.extend(["", "Preventive controls:", *_bullets(preventive_controls, "None recorded.")])
|
|
550
|
+
return lines
|
|
551
|
+
|
|
552
|
+
|
|
553
|
+
def _linked_finding_section(number: int, finding: dict[str, Any], report_path: str) -> list[str]:
|
|
554
|
+
cwes = ", ".join(finding["taxonomy"]["cwe"]) or "none"
|
|
555
|
+
title = _text(finding["title"], "Untitled finding")
|
|
556
|
+
link = f"[detailed technical write-up]({report_path})"
|
|
557
|
+
lines = [
|
|
558
|
+
f'<a id="finding-{number}"></a>',
|
|
559
|
+
"",
|
|
560
|
+
f"### [{number}] {title}",
|
|
561
|
+
"",
|
|
562
|
+
"| Field | Value |",
|
|
563
|
+
"| --- | --- |",
|
|
564
|
+
f"| Severity | {_cell(finding['severity']['level'])} |",
|
|
565
|
+
f"| Confidence | {_cell(finding['confidence']['level'])} |",
|
|
566
|
+
f"| Confidence rationale | {_cell(finding['confidence']['rationale'])} |",
|
|
567
|
+
f"| Category | {_cell(finding['taxonomy']['category'])} |",
|
|
568
|
+
f"| CWE | {_cell(cwes)} |",
|
|
569
|
+
f"| Affected lines | {_cell(_locations(finding))} |",
|
|
570
|
+
]
|
|
571
|
+
for heading in ("Summary", "Validation", "Dataflow", "Reachability", "Severity", "Remediation"):
|
|
572
|
+
lines.extend(["", f"#### {heading}", "", f"See the {link}."])
|
|
573
|
+
return lines
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
def build_report_markdown(
|
|
577
|
+
manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
|
|
578
|
+
) -> str:
|
|
579
|
+
scan = manifest["scan"]
|
|
580
|
+
target = scan["target"]
|
|
581
|
+
scope = scan["scope"]
|
|
582
|
+
threat_model = scan.get("threatModel") if isinstance(scan.get("threatModel"), dict) else {}
|
|
583
|
+
findings = sorted(
|
|
584
|
+
(
|
|
585
|
+
finding
|
|
586
|
+
for finding in findings_document["findings"]
|
|
587
|
+
if finding["severity"]["level"] in REPORTABLE_SEVERITIES
|
|
588
|
+
),
|
|
589
|
+
key=_finding_sort_key,
|
|
590
|
+
)
|
|
591
|
+
writeup_paths = [_writeup_report_path(finding) for finding in findings]
|
|
592
|
+
duplicate_writeup_paths = sorted(
|
|
593
|
+
path
|
|
594
|
+
for path, count in Counter(path for path in writeup_paths if path is not None).items()
|
|
595
|
+
if count > 1
|
|
596
|
+
)
|
|
597
|
+
if duplicate_writeup_paths:
|
|
598
|
+
raise ReportProjectionError(
|
|
599
|
+
"reportable findings have duplicate writeup reportPath values: "
|
|
600
|
+
+ ", ".join(duplicate_writeup_paths)
|
|
601
|
+
)
|
|
602
|
+
deep_presentation = _uses_deep_presentation(coverage, findings)
|
|
603
|
+
deep_finding_groups = _deep_finding_groups(findings, writeup_paths) if deep_presentation else []
|
|
604
|
+
hardening_portfolio_path = _hardening_portfolio_path(scan)
|
|
605
|
+
include_paths = _strings(coverage.get("includePaths", scope.get("includePaths", [])))
|
|
606
|
+
exclude_paths = _strings(coverage.get("excludePaths", scope.get("excludePaths", [])))
|
|
607
|
+
limitations = _strings(scope.get("limitations"))
|
|
608
|
+
explicit_exclusions = coverage.get("explicitExclusions", [])
|
|
609
|
+
lines = [
|
|
610
|
+
f"# Security Review: {_text(target['displayName'], 'Unknown target')}",
|
|
611
|
+
"",
|
|
612
|
+
"## Scope",
|
|
613
|
+
"",
|
|
614
|
+
_text(
|
|
615
|
+
scope.get("summary"),
|
|
616
|
+
"The scan reviewed the canonical include paths and exclusions listed below.",
|
|
617
|
+
),
|
|
618
|
+
"",
|
|
619
|
+
f"- Scan mode: {coverage['mode']}",
|
|
620
|
+
*_target_scope_lines(target),
|
|
621
|
+
f"- Inventory strategy: {coverage['inventoryStrategy']}",
|
|
622
|
+
f"- Included paths: {', '.join(include_paths) or 'none'}",
|
|
623
|
+
f"- Excluded paths: {', '.join(exclude_paths) or 'none'}",
|
|
624
|
+
f"- Runtime or test status: {_text(scope.get('runtimeStatus'), 'not recorded')}",
|
|
625
|
+
]
|
|
626
|
+
artifacts_reviewed = _strings(scope.get("artifactsReviewed"))
|
|
627
|
+
if artifacts_reviewed:
|
|
628
|
+
lines.extend(["- Artifacts reviewed: " + ", ".join(artifacts_reviewed)])
|
|
629
|
+
context = _text(scope.get("context"), "")
|
|
630
|
+
if context:
|
|
631
|
+
lines.extend([f"- Scan context: {context}"])
|
|
632
|
+
for exclusion in explicit_exclusions:
|
|
633
|
+
if isinstance(exclusion, dict):
|
|
634
|
+
limitations.append(
|
|
635
|
+
f"Excluded {_text(exclusion.get('pattern'), 'unspecified')}: "
|
|
636
|
+
f"{_text(exclusion.get('reason'), 'reason not recorded')}"
|
|
637
|
+
)
|
|
638
|
+
if limitations:
|
|
639
|
+
lines.extend(["", "Limitations and exclusions:", *_bullets(limitations, "None recorded.")])
|
|
640
|
+
summary_count_lines = (
|
|
641
|
+
[
|
|
642
|
+
f"| Reportable DSS findings | {len(deep_finding_groups)} |",
|
|
643
|
+
f"| Report instances | {len(findings)} |",
|
|
644
|
+
f"| Report severity mix | {_severity_mix(findings)} |",
|
|
645
|
+
f"| Report confidence mix | {_confidence_mix(findings)} |",
|
|
646
|
+
]
|
|
647
|
+
if deep_presentation
|
|
648
|
+
else [
|
|
649
|
+
f"| Reportable findings | {len(findings)} |",
|
|
650
|
+
f"| Severity mix | {_severity_mix(findings)} |",
|
|
651
|
+
f"| Confidence mix | {_confidence_mix(findings)} |",
|
|
652
|
+
]
|
|
653
|
+
)
|
|
654
|
+
lines.extend(
|
|
655
|
+
[
|
|
656
|
+
"",
|
|
657
|
+
"### Scan Summary",
|
|
658
|
+
"",
|
|
659
|
+
"| Field | Value |",
|
|
660
|
+
"| --- | --- |",
|
|
661
|
+
*summary_count_lines,
|
|
662
|
+
f"| Coverage | {coverage['completeness']} |",
|
|
663
|
+
f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
|
|
664
|
+
"",
|
|
665
|
+
"Canonical artifacts: `scan-manifest.json`, `findings.json`, and `coverage.json`. This report is a deterministic projection of those files.",
|
|
666
|
+
"",
|
|
667
|
+
"## Threat Model",
|
|
668
|
+
"",
|
|
669
|
+
_text(
|
|
670
|
+
threat_model.get("summary"),
|
|
671
|
+
"No explicit canonical threat-model summary was recorded.",
|
|
672
|
+
),
|
|
673
|
+
]
|
|
674
|
+
)
|
|
675
|
+
for heading, key, fallback in (
|
|
676
|
+
("Assets", "assets", "No assets were recorded."),
|
|
677
|
+
("Trust Boundaries", "trustBoundaries", "No trust boundaries were recorded."),
|
|
678
|
+
(
|
|
679
|
+
"Attacker Capabilities",
|
|
680
|
+
"attackerCapabilities",
|
|
681
|
+
"No attacker capabilities were recorded.",
|
|
682
|
+
),
|
|
683
|
+
("Security Objectives", "securityObjectives", "No security objectives were recorded."),
|
|
684
|
+
("Assumptions", "assumptions", "No assumptions were recorded."),
|
|
685
|
+
):
|
|
686
|
+
values = _strings(threat_model.get(key))
|
|
687
|
+
if values:
|
|
688
|
+
lines.extend(["", f"### {heading}", "", *_bullets(values, fallback)])
|
|
689
|
+
lines.extend(["", "## Findings", ""])
|
|
690
|
+
if findings:
|
|
691
|
+
if deep_presentation:
|
|
692
|
+
lines.extend(
|
|
693
|
+
[
|
|
694
|
+
"| Findings | Reports | Severity | Confidence | Detailed write-up |",
|
|
695
|
+
"| --- | --- | --- | --- | --- |",
|
|
696
|
+
]
|
|
697
|
+
)
|
|
698
|
+
for group in deep_finding_groups:
|
|
699
|
+
lines.append(
|
|
700
|
+
f"| {_deep_group_titles(group)} | {_deep_group_report_links(group)} "
|
|
701
|
+
f"| {_deep_group_levels(group, 'severity', SEVERITY_ORDER)} "
|
|
702
|
+
f"| {_deep_group_levels(group, 'confidence', CONFIDENCE_ORDER)} "
|
|
703
|
+
f"| {_deep_group_writeup_links(group)} |"
|
|
704
|
+
)
|
|
705
|
+
else:
|
|
706
|
+
lines.extend(
|
|
707
|
+
[
|
|
708
|
+
"| Finding | Severity | Confidence | Detailed write-up |",
|
|
709
|
+
"| --- | --- | --- | --- |",
|
|
710
|
+
]
|
|
711
|
+
)
|
|
712
|
+
for number, (finding, report_path) in enumerate(
|
|
713
|
+
zip(findings, writeup_paths, strict=True), 1
|
|
714
|
+
):
|
|
715
|
+
title = _link_label(finding["title"], "Untitled finding")
|
|
716
|
+
finding_link = f"[{title}](#finding-{number})"
|
|
717
|
+
writeup_link = f"[Open report]({report_path})" if report_path else "inline below"
|
|
718
|
+
lines.append(
|
|
719
|
+
f"| {finding_link} | {finding['severity']['level']} "
|
|
720
|
+
f"| {finding['confidence']['level']} | {writeup_link} |"
|
|
721
|
+
)
|
|
722
|
+
lines.extend(
|
|
723
|
+
[
|
|
724
|
+
"",
|
|
725
|
+
"### Confidence Scale",
|
|
726
|
+
"",
|
|
727
|
+
"| Label | Meaning |",
|
|
728
|
+
"| --- | --- |",
|
|
729
|
+
"| high | Direct evidence supports the finding with no material unresolved blocker. |",
|
|
730
|
+
"| medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |",
|
|
731
|
+
"| low | Evidence is incomplete and the item is retained only for explicit follow-up. |",
|
|
732
|
+
]
|
|
733
|
+
)
|
|
734
|
+
for number, (finding, report_path) in enumerate(
|
|
735
|
+
zip(findings, writeup_paths, strict=True), 1
|
|
736
|
+
):
|
|
737
|
+
if report_path is not None:
|
|
738
|
+
lines.extend(["", *_linked_finding_section(number, finding, report_path)])
|
|
739
|
+
else:
|
|
740
|
+
lines.extend(["", *_finding_section(number, finding)])
|
|
741
|
+
else:
|
|
742
|
+
lines.extend(
|
|
743
|
+
[
|
|
744
|
+
"### No findings",
|
|
745
|
+
"",
|
|
746
|
+
"No reportable findings survived the canonical discovery, validation, and reportability gates.",
|
|
747
|
+
]
|
|
748
|
+
)
|
|
749
|
+
if hardening_portfolio_path is not None:
|
|
750
|
+
lines.extend(
|
|
751
|
+
[
|
|
752
|
+
"",
|
|
753
|
+
"## Structural Hardening",
|
|
754
|
+
"",
|
|
755
|
+
"The scan also produced derived, unsealed design guidance based on the complete finding collection. These proposals describe options and tradeoffs; they do not indicate that any finding has been remediated.",
|
|
756
|
+
"",
|
|
757
|
+
f"[Open the structural hardening portfolio]({hardening_portfolio_path})",
|
|
758
|
+
]
|
|
759
|
+
)
|
|
760
|
+
surfaces = coverage.get("surfaces", [])
|
|
761
|
+
if surfaces:
|
|
762
|
+
lines.extend(
|
|
763
|
+
[
|
|
764
|
+
"",
|
|
765
|
+
"## Reviewed Surfaces",
|
|
766
|
+
"",
|
|
767
|
+
"| Surface | Risk Area | Outcome | Notes |",
|
|
768
|
+
"| --- | --- | --- | --- |",
|
|
769
|
+
]
|
|
770
|
+
)
|
|
771
|
+
for surface in surfaces:
|
|
772
|
+
if not isinstance(surface, dict):
|
|
773
|
+
continue
|
|
774
|
+
lines.append(
|
|
775
|
+
"| "
|
|
776
|
+
+ " | ".join(
|
|
777
|
+
(
|
|
778
|
+
_cell(surface.get("label", surface.get("id"))),
|
|
779
|
+
_cell(surface.get("riskArea", "not recorded")),
|
|
780
|
+
_cell(
|
|
781
|
+
DISPOSITION_LABELS.get(
|
|
782
|
+
surface.get("disposition"), surface.get("disposition")
|
|
783
|
+
)
|
|
784
|
+
),
|
|
785
|
+
_surface_notes(surface),
|
|
786
|
+
)
|
|
787
|
+
)
|
|
788
|
+
+ " |"
|
|
789
|
+
)
|
|
790
|
+
open_questions = coverage.get("openQuestions", [])
|
|
791
|
+
questions = list(open_questions) if isinstance(open_questions, list) else []
|
|
792
|
+
deferred = coverage.get("deferred", [])
|
|
793
|
+
if isinstance(deferred, list):
|
|
794
|
+
questions.extend(
|
|
795
|
+
{
|
|
796
|
+
"question": item.get("reason", "Deferred review requires follow-up."),
|
|
797
|
+
"followUpPrompt": " ".join(
|
|
798
|
+
(
|
|
799
|
+
f"Review deferred unit {item.get('id', 'unknown')} and close its stated proof gap.",
|
|
800
|
+
f"Paths: {', '.join(item.get('paths', []))}." if item.get("paths") else "",
|
|
801
|
+
(
|
|
802
|
+
f"Surfaces: {', '.join(item.get('surfaceIds', []))}."
|
|
803
|
+
if item.get("surfaceIds")
|
|
804
|
+
else ""
|
|
805
|
+
),
|
|
806
|
+
)
|
|
807
|
+
).strip(),
|
|
808
|
+
}
|
|
809
|
+
for item in deferred
|
|
810
|
+
if isinstance(item, dict)
|
|
811
|
+
)
|
|
812
|
+
if questions:
|
|
813
|
+
lines.extend(["", "## Open Questions And Follow Up", ""])
|
|
814
|
+
for question in questions:
|
|
815
|
+
if not isinstance(question, dict):
|
|
816
|
+
continue
|
|
817
|
+
lines.append(f"- {_text(question.get('question'), 'Unspecified open question.')}")
|
|
818
|
+
prompt = _text(question.get("followUpPrompt"), "")
|
|
819
|
+
if prompt:
|
|
820
|
+
lines.append(f" - Follow-up prompt: {prompt}")
|
|
821
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
def generate_report_markdown(
|
|
825
|
+
manifest: dict[str, Any],
|
|
826
|
+
findings: dict[str, Any],
|
|
827
|
+
coverage: dict[str, Any],
|
|
828
|
+
) -> bytes:
|
|
829
|
+
markdown = build_report_markdown(manifest, findings, coverage)
|
|
830
|
+
validator = _load_script("validate_report_format")
|
|
831
|
+
errors = validator.validate_report(markdown)
|
|
832
|
+
if errors:
|
|
833
|
+
raise ReportProjectionError("generated report failed validation: " + "; ".join(errors))
|
|
834
|
+
return markdown.encode("utf-8")
|
|
835
|
+
|
|
836
|
+
|
|
837
|
+
def main() -> int:
|
|
838
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
839
|
+
parser.parse_args()
|
|
840
|
+
return 0
|
|
841
|
+
|
|
842
|
+
|
|
843
|
+
if __name__ == "__main__":
|
|
844
|
+
raise SystemExit(main())
|