feat(cli): browse historical security findings

README.md

@@ -71,8 +71,15 @@ Scan history is stored in the Codex Security workbench state directory. If that
 directory cannot be written, set `CODEX_SECURITY_STATE_DIR` to a writable
 directory outside the repository.
 
-`findings list [repository]` shows open findings across a repository's scans
-and identifies findings not confirmed in its latest scan.
+Use `scans` to browse previous scans, `scans show` to inspect the latest
+completed scan, and `findings` to list saved findings for the current repository.
+`findings list [repository]` also identifies findings not confirmed in the latest
+scan.
+To review every finding from an earlier scan, first run
+`findings list --scan SCAN_ID --json`. For each numeric `nextOffset` in the
+response, repeat the command with `--offset NEXT_OFFSET`; stop when `nextOffset`
+is `null`. Use `findings show OCCURRENCE_ID` for the complete finding and any
+saved cross-scan links.
 
 `scans compare BEFORE_SCAN_ID AFTER_SCAN_ID` automatically matches findings by
 root cause, reuses saved matches, and identifies new, persisting, reopened,

sdk/typescript/README.md

@@ -223,13 +223,18 @@ npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside
 npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
 npx @openai/codex-security scans list /path/to/repository
 npx @openai/codex-security scans list --scan-root /path/outside/repository/results
+npx @openai/codex-security scans show
 npx @openai/codex-security scans show SCAN_ID
 npx @openai/codex-security scans logs SCAN_ID
 npx @openai/codex-security scans rerun SCAN_ID
 npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
 npx @openai/codex-security scans match --all
 npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
+npx @openai/codex-security findings
 npx @openai/codex-security findings list /path/to/repository
+npx @openai/codex-security findings list --severity high --status open
+npx @openai/codex-security findings list --scan SCAN_ID --offset 20
+npx @openai/codex-security findings show OCCURRENCE_ID
 npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
 npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
 npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
@@ -532,11 +537,30 @@ same command to resume.
 
 ### Scan history and reruns
 
-`npx @openai/codex-security scans list` lists scans for the current repository. Pass a
-repository path to inspect another checkout, `--scan-root DIR` to list scans
-whose artifacts are under a particular root. `scans show SCAN_ID` includes the
-scan configuration, results, coverage, and artifact locations. Add
-`--show-linked-findings` to include finding links from previous scans.
+`npx @openai/codex-security scans` lists previous scans for the current
+repository. Use `scans list REPOSITORY` to inspect another checkout, or
+`scans list --scan-root DIR` to list scans whose artifacts are under a particular
+root. `scans show` opens the latest completed scan;
+`scans show SCAN_ID` selects another saved scan. Both include scan configuration,
+results, coverage, and artifact locations.
+
+Run `findings` or `findings list` to browse open vulnerabilities for the current
+repository across saved scans. Add `--all-repositories` to include every saved
+repository, or `--scan SCAN_ID` to inspect all findings from one previous scan.
+Filter results with `--query TEXT`, `--severity LEVEL`, or
+`--status open|closed`; use `--offset N` and `--limit N` to page through the
+complete set. Pages contain at most 20 findings.
+
+`findings show OCCURRENCE_ID` opens the selected finding, its remediation advice,
+and any saved links to previous occurrences. Finding lists include the
+occurrence IDs needed by `findings show` and `findings false-positive`.
+Closed finding details show whether the finding was fixed, marked as a false
+positive, or ignored.
+
+Add `--show-linked-findings` to `scans show` to include previously saved finding
+links. Links appear after running `scans compare BEFORE AFTER` or
+`scans match --all`; creating uncached matches starts a Codex comparison and
+saves the result.
 
 `scans logs SCAN_ID` shows complete session events from the scan and its
 workers, which can include source code and credentials.

sdk/typescript/_bundled_plugin/scripts/workbench_cli.py

@@ -114,6 +114,9 @@ def parse_args(description: str) -> argparse.Namespace:
     get_scan.add_argument("--scan-id", required=True)
     get_scan.add_argument("--occurrence-id")
 
+    get_finding = subparsers.add_parser("get-finding")
+    get_finding.add_argument("--occurrence-id", required=True)
+
     get_scan_feedback = subparsers.add_parser("get-scan-feedback")
     get_scan_feedback.add_argument("--scan-id", required=True)
 
@@ -169,7 +172,10 @@ def parse_args(description: str) -> argparse.Namespace:
     list_global_findings.add_argument("--query")
     list_global_findings.add_argument("--severity", choices=FINDING_SEVERITIES)
     list_global_findings.add_argument("--status", choices=FINDING_STATUSES)
-    list_global_findings.add_argument("--target-id")
+    list_global_findings.add_argument("--repository")
+    list_global_findings.add_argument("--target-id", action="append")
+    list_global_findings.add_argument("--target-path", action="append")
+    list_global_findings.add_argument("--include-resolved", action="store_true")
     list_global_findings.add_argument("--offset", type=non_negative_int, default=0)
     list_global_findings.add_argument("--limit", type=positive_int, default=FINDINGS_PAGE_MAX)
     list_repositories = subparsers.add_parser("list-repositories")