@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,158 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Concatenate the SECURITY.md files that apply to a scan path."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import stat
|
|
10
|
+
import sys
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
MAX_SECURITY_MD_BYTES = 1024 * 1024
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class ResolutionError(ValueError):
|
|
17
|
+
"""Raised when a SECURITY.md chain cannot be resolved."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _inside(path: Path, root: Path, label: str) -> Path:
|
|
21
|
+
try:
|
|
22
|
+
return path.relative_to(root)
|
|
23
|
+
except ValueError as exc:
|
|
24
|
+
raise ResolutionError(f"{label} is outside the scan root: {path}") from exc
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _resolve_root(repo: Path) -> Path:
|
|
28
|
+
try:
|
|
29
|
+
root = repo.expanduser().resolve(strict=True)
|
|
30
|
+
except OSError as exc:
|
|
31
|
+
raise ResolutionError(f"scan root does not exist: {repo}") from exc
|
|
32
|
+
if not root.is_dir():
|
|
33
|
+
raise ResolutionError(f"scan root is not a directory: {root}")
|
|
34
|
+
return root
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def list_security_md(repo: Path) -> list[str]:
|
|
38
|
+
"""Return a stable, safely framed inventory without traversing Git metadata."""
|
|
39
|
+
root = _resolve_root(repo)
|
|
40
|
+
|
|
41
|
+
def raise_walk_error(error: OSError) -> None:
|
|
42
|
+
raise error
|
|
43
|
+
|
|
44
|
+
policies: list[str] = []
|
|
45
|
+
for directory, subdirectories, filenames in os.walk(
|
|
46
|
+
root, onerror=raise_walk_error, followlinks=False
|
|
47
|
+
):
|
|
48
|
+
safe_subdirectories: list[str] = []
|
|
49
|
+
for name in sorted(subdirectories):
|
|
50
|
+
if name == ".git":
|
|
51
|
+
continue
|
|
52
|
+
directory_stat = (Path(directory) / name).stat(follow_symlinks=False)
|
|
53
|
+
if not stat.S_ISDIR(directory_stat.st_mode):
|
|
54
|
+
continue
|
|
55
|
+
reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
|
|
56
|
+
if getattr(directory_stat, "st_file_attributes", 0) & reparse_point:
|
|
57
|
+
continue
|
|
58
|
+
safe_subdirectories.append(name)
|
|
59
|
+
subdirectories[:] = safe_subdirectories
|
|
60
|
+
if "SECURITY.md" not in filenames:
|
|
61
|
+
continue
|
|
62
|
+
policy = Path(directory) / "SECURITY.md"
|
|
63
|
+
if policy.is_file() or policy.is_symlink():
|
|
64
|
+
policies.append(policy.relative_to(root).as_posix())
|
|
65
|
+
return sorted(policies)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def resolve_security_md(repo: Path, scope: Path) -> str:
|
|
69
|
+
"""Return applicable SECURITY.md files, concatenated root to leaf."""
|
|
70
|
+
root = _resolve_root(repo)
|
|
71
|
+
|
|
72
|
+
requested_scope = scope.expanduser()
|
|
73
|
+
if not requested_scope.is_absolute():
|
|
74
|
+
requested_scope = root / requested_scope
|
|
75
|
+
try:
|
|
76
|
+
resolved_scope = requested_scope.resolve(strict=True)
|
|
77
|
+
except OSError as exc:
|
|
78
|
+
raise ResolutionError(f"scan scope does not exist: {requested_scope}") from exc
|
|
79
|
+
_inside(resolved_scope, root, "scan scope")
|
|
80
|
+
|
|
81
|
+
target_directory = resolved_scope if resolved_scope.is_dir() else resolved_scope.parent
|
|
82
|
+
relative_directory = _inside(target_directory, root, "scan scope")
|
|
83
|
+
directories = [root]
|
|
84
|
+
current = root
|
|
85
|
+
for part in relative_directory.parts:
|
|
86
|
+
current /= part
|
|
87
|
+
directories.append(current)
|
|
88
|
+
|
|
89
|
+
sections: list[str] = []
|
|
90
|
+
for directory in directories:
|
|
91
|
+
policy = directory / "SECURITY.md"
|
|
92
|
+
if not policy.is_file():
|
|
93
|
+
continue
|
|
94
|
+
resolved_policy = policy.resolve(strict=True)
|
|
95
|
+
_inside(resolved_policy, root, "SECURITY.md")
|
|
96
|
+
try:
|
|
97
|
+
with resolved_policy.open("rb") as policy_file:
|
|
98
|
+
policy_bytes = policy_file.read(MAX_SECURITY_MD_BYTES + 1)
|
|
99
|
+
if len(policy_bytes) > MAX_SECURITY_MD_BYTES:
|
|
100
|
+
raise ResolutionError(f"SECURITY.md exceeds 1 MiB: {policy}")
|
|
101
|
+
content = policy_bytes.decode("utf-8")
|
|
102
|
+
except UnicodeDecodeError as exc:
|
|
103
|
+
raise ResolutionError(f"SECURITY.md is not valid UTF-8: {policy}") from exc
|
|
104
|
+
if not content.strip():
|
|
105
|
+
continue
|
|
106
|
+
|
|
107
|
+
source = policy.relative_to(root).as_posix()
|
|
108
|
+
section = f"## SECURITY.md source: {json.dumps(source)}\n\n{content}"
|
|
109
|
+
if not section.endswith("\n"):
|
|
110
|
+
section += "\n"
|
|
111
|
+
sections.append(section)
|
|
112
|
+
|
|
113
|
+
return "\n".join(sections)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def parse_args() -> argparse.Namespace:
|
|
117
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
118
|
+
parser.add_argument("--repo", required=True, type=Path, help="scan root directory")
|
|
119
|
+
parser.add_argument(
|
|
120
|
+
"--list",
|
|
121
|
+
action="store_true",
|
|
122
|
+
help="write a JSON inventory of repository policy paths",
|
|
123
|
+
)
|
|
124
|
+
parser.add_argument(
|
|
125
|
+
"--scope",
|
|
126
|
+
type=Path,
|
|
127
|
+
help="existing file or directory within the scan root",
|
|
128
|
+
)
|
|
129
|
+
parser.add_argument("--out", default=Path("-"), type=Path, help="output path, or - for stdout")
|
|
130
|
+
args = parser.parse_args()
|
|
131
|
+
if args.list and args.scope is not None:
|
|
132
|
+
parser.error("--list cannot be combined with --scope")
|
|
133
|
+
if not args.list and args.scope is None:
|
|
134
|
+
parser.error("--scope is required unless --list is specified")
|
|
135
|
+
return args
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def main() -> int:
|
|
139
|
+
args = parse_args()
|
|
140
|
+
try:
|
|
141
|
+
guidance = (
|
|
142
|
+
json.dumps(list_security_md(args.repo), ensure_ascii=True) + "\n"
|
|
143
|
+
if args.list
|
|
144
|
+
else resolve_security_md(args.repo, args.scope)
|
|
145
|
+
)
|
|
146
|
+
if args.out == Path("-"):
|
|
147
|
+
sys.stdout.buffer.write(guidance.encode("utf-8"))
|
|
148
|
+
else:
|
|
149
|
+
args.out.parent.mkdir(parents=True, exist_ok=True)
|
|
150
|
+
args.out.write_text(guidance, encoding="utf-8")
|
|
151
|
+
except (OSError, ResolutionError) as exc:
|
|
152
|
+
print(f"resolve_security_md.py: error: {exc}", file=sys.stderr)
|
|
153
|
+
return 2
|
|
154
|
+
return 0
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
if __name__ == "__main__":
|
|
158
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Create a transactionally consistent SQLite database snapshot."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import sqlite3
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def main() -> None:
|
|
12
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
13
|
+
parser.add_argument("source", type=Path)
|
|
14
|
+
parser.add_argument("destination", type=Path)
|
|
15
|
+
args = parser.parse_args()
|
|
16
|
+
source = args.source.expanduser().resolve(strict=True)
|
|
17
|
+
destination = args.destination.expanduser().absolute()
|
|
18
|
+
destination.parent.mkdir(parents=True, exist_ok=True)
|
|
19
|
+
with sqlite3.connect(f"{source.as_uri()}?mode=ro", uri=True) as source_connection:
|
|
20
|
+
with sqlite3.connect(destination) as destination_connection:
|
|
21
|
+
source_connection.backup(destination_connection)
|
|
22
|
+
destination.chmod(0o600)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
if __name__ == "__main__":
|
|
26
|
+
main()
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate the shared Codex Security final report shape."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import re
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
REQUIRED_SECTIONS = ("## Scope", "## Threat Model", "## Findings")
|
|
12
|
+
REQUIRED_FINDING_FIELDS = (
|
|
13
|
+
"Severity",
|
|
14
|
+
"Confidence",
|
|
15
|
+
"Confidence rationale",
|
|
16
|
+
"Category",
|
|
17
|
+
"CWE",
|
|
18
|
+
"Affected lines",
|
|
19
|
+
)
|
|
20
|
+
REQUIRED_FINDING_SUBSECTIONS = (
|
|
21
|
+
"#### Summary",
|
|
22
|
+
"#### Validation",
|
|
23
|
+
"#### Dataflow",
|
|
24
|
+
"#### Reachability",
|
|
25
|
+
"#### Severity",
|
|
26
|
+
"#### Remediation",
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$", re.MULTILINE)
|
|
30
|
+
FINDING_RE = re.compile(r"^### \[(\d+)\]\s+(.+?)\s*$", re.MULTILINE)
|
|
31
|
+
FIELD_ROW_RE = re.compile(r"^\|\s*((?:\\.|[^|])+?)\s*\|\s*((?:\\.|[^|])*?)\s*\|\s*$", re.MULTILINE)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def line_number(text: str, offset: int) -> int:
|
|
35
|
+
return text.count("\n", 0, offset) + 1
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def top_level_headings(text: str) -> list[str]:
|
|
39
|
+
return [match.group(0) for match in HEADING_RE.finditer(text) if match.group(1) in {"#", "##"}]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def validate_required_sections(text: str, errors: list[str]) -> None:
|
|
43
|
+
headings = top_level_headings(text)
|
|
44
|
+
if not headings or not headings[0].startswith("# Security Review:"):
|
|
45
|
+
errors.append("line 1: report must start with '# Security Review: <repo_or_target_name>'")
|
|
46
|
+
|
|
47
|
+
section_positions: list[int] = []
|
|
48
|
+
for section in REQUIRED_SECTIONS:
|
|
49
|
+
match = re.search(rf"^{re.escape(section)}\s*$", text, re.MULTILINE)
|
|
50
|
+
if not match:
|
|
51
|
+
errors.append(f"missing required section: {section}")
|
|
52
|
+
continue
|
|
53
|
+
section_positions.append(match.start())
|
|
54
|
+
|
|
55
|
+
if len(section_positions) == len(REQUIRED_SECTIONS) and section_positions != sorted(
|
|
56
|
+
section_positions
|
|
57
|
+
):
|
|
58
|
+
errors.append("required sections must appear in order: Scope, Threat Model, Findings")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def finding_body(text: str, finding: re.Match[str], next_finding: re.Match[str] | None) -> str:
|
|
62
|
+
start = finding.end()
|
|
63
|
+
end = next_finding.start() if next_finding else len(text)
|
|
64
|
+
return text[start:end]
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def validate_finding_metadata(body: str, line: int, errors: list[str]) -> None:
|
|
68
|
+
first_subsection = body.find("\n#### ")
|
|
69
|
+
metadata_region = body[: first_subsection if first_subsection != -1 else len(body)]
|
|
70
|
+
fields = {
|
|
71
|
+
match.group(1).strip().rstrip(":") for match in FIELD_ROW_RE.finditer(metadata_region)
|
|
72
|
+
}
|
|
73
|
+
missing = [field for field in REQUIRED_FINDING_FIELDS if field not in fields]
|
|
74
|
+
if missing:
|
|
75
|
+
errors.append(f"line {line}: finding metadata table missing fields: {', '.join(missing)}")
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def validate_finding_subsections(body: str, line: int, errors: list[str]) -> None:
|
|
79
|
+
positions: list[int] = []
|
|
80
|
+
for subsection in REQUIRED_FINDING_SUBSECTIONS:
|
|
81
|
+
match = re.search(rf"^{re.escape(subsection)}\s*$", body, re.MULTILINE)
|
|
82
|
+
if not match:
|
|
83
|
+
errors.append(f"line {line}: finding missing subsection: {subsection}")
|
|
84
|
+
continue
|
|
85
|
+
positions.append(match.start())
|
|
86
|
+
if len(positions) == len(REQUIRED_FINDING_SUBSECTIONS) and positions != sorted(positions):
|
|
87
|
+
errors.append(f"line {line}: finding subsections are not in the required order")
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def validate_findings(text: str, errors: list[str]) -> None:
|
|
91
|
+
findings = list(FINDING_RE.finditer(text))
|
|
92
|
+
if not findings:
|
|
93
|
+
if not re.search(r"^###?\s+No findings\s*$", text, re.IGNORECASE | re.MULTILINE):
|
|
94
|
+
errors.append("missing finding entries or a 'No findings' section under Findings")
|
|
95
|
+
return
|
|
96
|
+
|
|
97
|
+
expected_number = 1
|
|
98
|
+
for index, finding in enumerate(findings):
|
|
99
|
+
number = int(finding.group(1))
|
|
100
|
+
line = line_number(text, finding.start())
|
|
101
|
+
if number != expected_number:
|
|
102
|
+
errors.append(f"line {line}: finding number should be {expected_number}, got {number}")
|
|
103
|
+
expected_number += 1
|
|
104
|
+
|
|
105
|
+
body = finding_body(
|
|
106
|
+
text, finding, findings[index + 1] if index + 1 < len(findings) else None
|
|
107
|
+
)
|
|
108
|
+
validate_finding_metadata(body, line, errors)
|
|
109
|
+
validate_finding_subsections(body, line, errors)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def validate_report(text: str) -> list[str]:
|
|
113
|
+
errors: list[str] = []
|
|
114
|
+
validate_required_sections(text, errors)
|
|
115
|
+
validate_findings(text, errors)
|
|
116
|
+
return errors
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def main() -> int:
|
|
120
|
+
parser = argparse.ArgumentParser(description="Validate the Codex Security report format.")
|
|
121
|
+
parser.add_argument("--report-md", required=True, help="Path to report.md")
|
|
122
|
+
args = parser.parse_args()
|
|
123
|
+
|
|
124
|
+
report_path = Path(args.report_md)
|
|
125
|
+
text = report_path.read_text(encoding="utf-8")
|
|
126
|
+
|
|
127
|
+
errors = validate_report(text)
|
|
128
|
+
if errors:
|
|
129
|
+
for error in errors:
|
|
130
|
+
print(error, file=sys.stderr)
|
|
131
|
+
return 1
|
|
132
|
+
|
|
133
|
+
print(f"validated report format: {report_path}")
|
|
134
|
+
return 0
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
if __name__ == "__main__":
|
|
138
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate a sealed Codex Security scan contract without mutating it."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import importlib.util
|
|
8
|
+
import json
|
|
9
|
+
import sys
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from types import ModuleType
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _load_finalizer() -> ModuleType:
|
|
16
|
+
script = Path(__file__).resolve().with_name("finalize_scan_contract.py")
|
|
17
|
+
spec = importlib.util.spec_from_file_location("codex_security_scan_contract", script)
|
|
18
|
+
if spec is None or spec.loader is None:
|
|
19
|
+
raise RuntimeError(f"could not load scan contract validator: {script}")
|
|
20
|
+
module = importlib.util.module_from_spec(spec)
|
|
21
|
+
spec.loader.exec_module(module)
|
|
22
|
+
return module
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
FINALIZER = _load_finalizer()
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def validate_contract(scan_dir: Path) -> dict[str, Any]:
|
|
29
|
+
"""Return validated canonical documents for one sealed scan."""
|
|
30
|
+
|
|
31
|
+
scan_dir = FINALIZER._require_scan_directory(scan_dir.expanduser().resolve(strict=True))
|
|
32
|
+
schema_dir = Path(__file__).resolve().parents[1] / "schemas"
|
|
33
|
+
manifest, _ = FINALIZER._read_scan_local_json_bytes(
|
|
34
|
+
scan_dir,
|
|
35
|
+
"scan-manifest.json",
|
|
36
|
+
"scan-manifest.json",
|
|
37
|
+
)
|
|
38
|
+
FINALIZER._validate_manifest(manifest)
|
|
39
|
+
FINALIZER.validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
|
|
40
|
+
|
|
41
|
+
scan = FINALIZER._require_dict(manifest, "scan", "manifest")
|
|
42
|
+
findings_ref = scan["findingsRef"]
|
|
43
|
+
coverage_ref = scan["coverageRef"]
|
|
44
|
+
findings, findings_bytes = FINALIZER._read_scan_local_json_bytes(
|
|
45
|
+
scan_dir,
|
|
46
|
+
findings_ref,
|
|
47
|
+
findings_ref,
|
|
48
|
+
)
|
|
49
|
+
coverage, coverage_bytes = FINALIZER._read_scan_local_json_bytes(
|
|
50
|
+
scan_dir,
|
|
51
|
+
coverage_ref,
|
|
52
|
+
coverage_ref,
|
|
53
|
+
)
|
|
54
|
+
FINALIZER._validate_existing_seal(
|
|
55
|
+
scan_dir,
|
|
56
|
+
scan,
|
|
57
|
+
artifact_contents={
|
|
58
|
+
findings_ref: findings_bytes,
|
|
59
|
+
coverage_ref: coverage_bytes,
|
|
60
|
+
},
|
|
61
|
+
)
|
|
62
|
+
FINALIZER._validate_findings(manifest, findings)
|
|
63
|
+
FINALIZER._validate_derived_finding_identities(manifest, findings)
|
|
64
|
+
FINALIZER._validate_coverage(manifest, coverage, scan_dir)
|
|
65
|
+
FINALIZER._validate_sealed_coverage_receipts(scan, coverage)
|
|
66
|
+
FINALIZER.validate_against_schema(findings, schema_dir / "findings.schema.json")
|
|
67
|
+
FINALIZER.validate_against_schema(coverage, schema_dir / "coverage.schema.json")
|
|
68
|
+
FINALIZER._require_scan_local_file(scan_dir, "report.md", "report.md")
|
|
69
|
+
return {
|
|
70
|
+
"scanDir": str(scan_dir),
|
|
71
|
+
"manifest": manifest,
|
|
72
|
+
"findings": findings,
|
|
73
|
+
"coverage": coverage,
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def receipt(validated: dict[str, Any]) -> dict[str, Any]:
|
|
78
|
+
scan_dir = Path(validated["scanDir"])
|
|
79
|
+
scan = validated["manifest"]["scan"]
|
|
80
|
+
return {
|
|
81
|
+
"status": "valid",
|
|
82
|
+
"scanDir": str(scan_dir),
|
|
83
|
+
"manifestPath": str(scan_dir / "scan-manifest.json"),
|
|
84
|
+
"findingsPath": str(scan_dir / scan["findingsRef"]),
|
|
85
|
+
"coveragePath": str(scan_dir / scan["coverageRef"]),
|
|
86
|
+
"reportPath": str(scan_dir / "report.md"),
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _parse_args(argv: list[str]) -> argparse.Namespace:
|
|
91
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
92
|
+
parser.add_argument("--scan-dir", required=True, type=Path)
|
|
93
|
+
return parser.parse_args(argv)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def main(argv: list[str] | None = None) -> int:
|
|
97
|
+
args = _parse_args(sys.argv[1:] if argv is None else argv)
|
|
98
|
+
try:
|
|
99
|
+
validated = validate_contract(args.scan_dir)
|
|
100
|
+
except (OSError, ValueError, RecursionError) as exc:
|
|
101
|
+
print(f"scan contract validation failed: {exc}", file=sys.stderr)
|
|
102
|
+
return 2
|
|
103
|
+
print(json.dumps(receipt(validated), sort_keys=True))
|
|
104
|
+
return 0
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
if __name__ == "__main__":
|
|
108
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate a sealed scan and list or select findings for tracking."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import importlib.util
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from types import ModuleType
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _load_scan_contract_validator() -> ModuleType:
|
|
15
|
+
script = Path(__file__).resolve().with_name("validate_scan_contract.py")
|
|
16
|
+
spec = importlib.util.spec_from_file_location("codex_security_scan_validator", script)
|
|
17
|
+
if spec is None or spec.loader is None:
|
|
18
|
+
raise RuntimeError(f"could not load scan contract validator: {script}")
|
|
19
|
+
module = importlib.util.module_from_spec(spec)
|
|
20
|
+
spec.loader.exec_module(module)
|
|
21
|
+
return module
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
SCAN_CONTRACT = _load_scan_contract_validator()
|
|
25
|
+
FINALIZER = SCAN_CONTRACT.FINALIZER
|
|
26
|
+
validate_contract = SCAN_CONTRACT.validate_contract
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _select_findings(
|
|
30
|
+
findings: list[dict[str, Any]],
|
|
31
|
+
finding_id: str | None,
|
|
32
|
+
fingerprint: str | None,
|
|
33
|
+
) -> list[dict[str, Any]]:
|
|
34
|
+
if finding_id is not None:
|
|
35
|
+
matches = [finding for finding in findings if finding["findingId"] == finding_id]
|
|
36
|
+
elif fingerprint is not None:
|
|
37
|
+
matches = [
|
|
38
|
+
finding for finding in findings if finding["fingerprints"]["primary"] == fingerprint
|
|
39
|
+
]
|
|
40
|
+
else:
|
|
41
|
+
return findings
|
|
42
|
+
|
|
43
|
+
if len(matches) != 1:
|
|
44
|
+
raise ValueError("the selector did not resolve exactly one finding")
|
|
45
|
+
return matches
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def validate_source(
|
|
49
|
+
scan_dir: Path,
|
|
50
|
+
*,
|
|
51
|
+
finding_id: str | None = None,
|
|
52
|
+
fingerprint: str | None = None,
|
|
53
|
+
) -> list[dict[str, Any]]:
|
|
54
|
+
if finding_id is not None and fingerprint is not None:
|
|
55
|
+
raise ValueError("use only one of --finding-id or --fingerprint")
|
|
56
|
+
|
|
57
|
+
validated = validate_contract(scan_dir)
|
|
58
|
+
findings_document = validated["findings"]
|
|
59
|
+
return _select_findings(
|
|
60
|
+
findings_document["findings"],
|
|
61
|
+
finding_id,
|
|
62
|
+
fingerprint,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _parse_args(argv: list[str]) -> argparse.Namespace:
|
|
67
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
68
|
+
parser.add_argument("scan_dir", type=Path)
|
|
69
|
+
selector = parser.add_mutually_exclusive_group()
|
|
70
|
+
selector.add_argument("--finding-id")
|
|
71
|
+
selector.add_argument("--fingerprint")
|
|
72
|
+
return parser.parse_args(argv)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def main(argv: list[str] | None = None) -> int:
|
|
76
|
+
args = _parse_args(sys.argv[1:] if argv is None else argv)
|
|
77
|
+
try:
|
|
78
|
+
findings = validate_source(
|
|
79
|
+
args.scan_dir,
|
|
80
|
+
finding_id=args.finding_id,
|
|
81
|
+
fingerprint=args.fingerprint,
|
|
82
|
+
)
|
|
83
|
+
except (OSError, ValueError, RecursionError) as exc:
|
|
84
|
+
print(f"tracking source preflight failed: {exc}", file=sys.stderr)
|
|
85
|
+
return 2
|
|
86
|
+
for finding in findings:
|
|
87
|
+
print(finding["findingId"])
|
|
88
|
+
return 0
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
if __name__ == "__main__":
|
|
92
|
+
raise SystemExit(main())
|