@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.
Files changed (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. 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())