Merge remote-tracking branch 'origin/main' into HEAD

Author: mldangelo-oai

README.md

@@ -58,6 +58,7 @@ value, including when no stored sign-in exists.
 Scan a subset of a repository or write machine-readable results:
 
 ```bash
+npx codex-security scan /path/to/repo --model gpt-5.6-terra
 npx codex-security scan /path/to/repo --path src --path tests
 npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
 npx codex-security scan /path/to/repo --diff origin/main --json
@@ -148,11 +149,11 @@ JSON scans remain noninteractive, including when stderr is a terminal. Commands
 that run Codex interactively (`validate`, `patch`, `login`, and `logout`) reject
 `--json`. Write CSV exports to a file when JSON output is selected.
 
-Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. To override
-either setting, pass valid TOML values (including quotes for strings):
+Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Switch
+models with `--model`. Use `--codex` for other Codex settings:
 
 ```bash
-npx codex-security scan . --codex 'model="gpt-5.6-sol"' --codex 'model_reasoning_effort="high"'
+npx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"'
 ```
 
 Scans report their requested paths and actual ranking, file-review, validation,

sdk/typescript/README.md

@@ -96,13 +96,15 @@ stored sign-in exists.
 
 ```bash
 npx codex-security scan /path/to/repository
+npx codex-security scan /path/to/repository --model gpt-5.6-terra
 npx codex-security scan /path/to/repository --path src --path tests
 npx codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
 npx codex-security scan /path/to/repository --diff origin/main --json
 npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results
 npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
 npx codex-security scan /path/to/repository --dry-run
 npx codex-security scan /path/to/repository --fail-on-severity high
+npx codex-security scan /path/to/repository --max-cost 5
 npx codex-security bulk-scan
 npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
 npx codex-security scans list /path/to/repository
@@ -150,16 +152,27 @@ for a passing policy. Incomplete scans still write the available human or JSON
 result to stdout and a coverage warning to stderr, including in report-only
 mode.
 
-Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Override
-either setting with repeatable `--codex KEY=VALUE` options, for example
-`--codex 'model="gpt-5.6-sol"' --codex 'model_reasoning_effort="high"'`.
+Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. Use
+`--model gpt-5.6-terra` to switch models. Use repeatable `--codex KEY=VALUE`
+options for other Codex settings, such as
+`--codex 'model_reasoning_effort="high"'`.
 
 Scan progress identifies the requested paths and reports actual ranking,
 file-review, validation, and attack-path phases as they become available.
 Completion summarizes findings, severity, coverage, elapsed time, available
-token and worker counts, the results directory, and the next useful command.
+token and worker counts, estimated cost, the results directory, and the next
+useful command.
 Progress and summaries use stderr; structured scan results remain on stdout.
 
+Each scan records its model, tokens, and estimated cost in its JSON result,
+scan history, and bulk-scan receipt. Estimates use
+[standard API token prices](https://developers.openai.com/api/docs/models/compare),
+including cached input and cache writes; fees and surcharges are not included.
+
+Use `--max-cost USD` to stop a scan, including its delegated workers, when its
+running cost exceeds the limit. Partial results are preserved. Requests
+already in progress can finish above the limit.
+
 Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
 for the complete CLI references.
 
@@ -190,6 +203,9 @@ 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.
 
+Every scan history command accepts a full scan ID or a unique prefix of at
+least eight characters.
+
 Scan history uses the existing Codex Security workbench database at
 `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Set
 `CODEX_SECURITY_STATE_DIR` to place the database elsewhere. Scan credentials

sdk/typescript/_bundled_plugin/scripts/resolve_security_md.py

@@ -5,9 +5,13 @@
 
 import argparse
 import json
+import os
+import stat
 import sys
 from pathlib import Path
 
+MAX_SECURITY_MD_BYTES = 1024 * 1024
+
 
 class ResolutionError(ValueError):
     """Raised when a SECURITY.md chain cannot be resolved."""
@@ -20,14 +24,50 @@ def _inside(path: Path, root: Path, label: str) -> Path:
         raise ResolutionError(f"{label} is outside the scan root: {path}") from exc
 
 
-def resolve_security_md(repo: Path, scope: Path) -> str:
-    """Return applicable SECURITY.md files, concatenated root to leaf."""
+def _resolve_root(repo: Path) -> Path:
     try:
         root = repo.expanduser().resolve(strict=True)
     except OSError as exc:
         raise ResolutionError(f"scan root does not exist: {repo}") from exc
     if not root.is_dir():
         raise ResolutionError(f"scan root is not a directory: {root}")
+    return root
+
+
+def list_security_md(repo: Path) -> list[str]:
+    """Return a stable, safely framed inventory without traversing Git metadata."""
+    root = _resolve_root(repo)
+
+    def raise_walk_error(error: OSError) -> None:
+        raise error
+
+    policies: list[str] = []
+    for directory, subdirectories, filenames in os.walk(
+        root, onerror=raise_walk_error, followlinks=False
+    ):
+        safe_subdirectories: list[str] = []
+        for name in sorted(subdirectories):
+            if name == ".git":
+                continue
+            directory_stat = (Path(directory) / name).stat(follow_symlinks=False)
+            if not stat.S_ISDIR(directory_stat.st_mode):
+                continue
+            reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+            if getattr(directory_stat, "st_file_attributes", 0) & reparse_point:
+                continue
+            safe_subdirectories.append(name)
+        subdirectories[:] = safe_subdirectories
+        if "SECURITY.md" not in filenames:
+            continue
+        policy = Path(directory) / "SECURITY.md"
+        if policy.is_file() or policy.is_symlink():
+            policies.append(policy.relative_to(root).as_posix())
+    return sorted(policies)
+
+
+def resolve_security_md(repo: Path, scope: Path) -> str:
+    """Return applicable SECURITY.md files, concatenated root to leaf."""
+    root = _resolve_root(repo)
 
     requested_scope = scope.expanduser()
     if not requested_scope.is_absolute():
@@ -54,7 +94,11 @@ def resolve_security_md(repo: Path, scope: Path) -> str:
         resolved_policy = policy.resolve(strict=True)
         _inside(resolved_policy, root, "SECURITY.md")
         try:
-            content = policy.read_bytes().decode("utf-8")
+            with resolved_policy.open("rb") as policy_file:
+                policy_bytes = policy_file.read(MAX_SECURITY_MD_BYTES + 1)
+            if len(policy_bytes) > MAX_SECURITY_MD_BYTES:
+                raise ResolutionError(f"SECURITY.md exceeds 1 MiB: {policy}")
+            content = policy_bytes.decode("utf-8")
         except UnicodeDecodeError as exc:
             raise ResolutionError(f"SECURITY.md is not valid UTF-8: {policy}") from exc
         if not content.strip():
@@ -72,22 +116,35 @@ def resolve_security_md(repo: Path, scope: Path) -> str:
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repo", required=True, type=Path, help="scan root directory")
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="write a JSON inventory of repository policy paths",
+    )
     parser.add_argument(
         "--scope",
-        required=True,
         type=Path,
         help="existing file or directory within the scan root",
     )
-    parser.add_argument("--out", required=True, type=Path, help="output Markdown path, or -")
-    return parser.parse_args()
+    parser.add_argument("--out", default=Path("-"), type=Path, help="output path, or - for stdout")
+    args = parser.parse_args()
+    if args.list and args.scope is not None:
+        parser.error("--list cannot be combined with --scope")
+    if not args.list and args.scope is None:
+        parser.error("--scope is required unless --list is specified")
+    return args
 
 
 def main() -> int:
     args = parse_args()
     try:
-        guidance = resolve_security_md(args.repo, args.scope)
+        guidance = (
+            json.dumps(list_security_md(args.repo), ensure_ascii=True) + "\n"
+            if args.list
+            else resolve_security_md(args.repo, args.scope)
+        )
         if args.out == Path("-"):
-            sys.stdout.write(guidance)
+            sys.stdout.buffer.write(guidance.encode("utf-8"))
         else:
             args.out.parent.mkdir(parents=True, exist_ok=True)
             args.out.write_text(guidance, encoding="utf-8")

sdk/typescript/_bundled_plugin/scripts/workbench_cli.py

@@ -208,6 +208,7 @@ def parse_args(description: str) -> argparse.Namespace:
     complete_scan = subparsers.add_parser("complete-scan")
     complete_scan.add_argument("--scan-id", required=True)
     complete_scan.add_argument("--claim-token")
+    complete_scan.add_argument("--cost-json")
 
     cancel_scan = subparsers.add_parser("cancel-scan")
     cancel_scan.add_argument("--scan-id", required=True)
@@ -217,6 +218,7 @@ def parse_args(description: str) -> argparse.Namespace:
     fail_scan.add_argument("--scan-id", required=True)
     fail_scan.add_argument("--message", required=True)
     fail_scan.add_argument("--claim-token")
+    fail_scan.add_argument("--cost-json")
 
     mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
     mark_handoff_delivered.add_argument("--scan-id", required=True)

sdk/typescript/_bundled_plugin/scripts/workbench_db.py

@@ -106,6 +106,7 @@
     capability_preflight_input,
     capability_preflight_json,
     optional_text,
+    parse_scan_cost,
     require_occurrence,
     require_uuid,
 )
@@ -774,13 +775,32 @@ def require_workspace(connection: sqlite3.Connection, workspace_id: str) -> sqli
 
 
 def require_scan(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
-    scan_id = require_uuid(scan_id, "scan-id")
+    scan_id = resolve_scan_id(connection, scan_id)
     row = connection.execute("SELECT * FROM scans WHERE id = ?", (scan_id,)).fetchone()
     if row is None:
         raise SystemExit("Codex Security scan not found.")
     return row
 
 
+def resolve_scan_id(connection: sqlite3.Connection, scan_id: str) -> str:
+    try:
+        return str(uuid.UUID(scan_id))
+    except ValueError:
+        if len(scan_id) < 8:
+            raise SystemExit("Scan ID prefixes must be at least eight characters.") from None
+        matches = connection.execute(
+            "SELECT id FROM scans WHERE substr(id, 1, ?) = ? LIMIT 2",
+            (len(scan_id), scan_id.lower()),
+        ).fetchall()
+        if not matches:
+            raise SystemExit("Codex Security scan not found.") from None
+        if len(matches) > 1:
+            raise SystemExit(
+                f'Scan ID prefix "{scan_id}" matches multiple scans; use a longer prefix.'
+            ) from None
+        return matches[0]["id"]
+
+
 def create_workspace(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
     workspace_id = require_uuid(args.workspace_id, "workspace-id")
     timestamp = now()
@@ -1434,12 +1454,16 @@ def pin_legacy_manifest_digest(
 
 def complete_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
     scan_id = require_uuid(args.scan_id, "scan-id")
+    cost_json = parse_scan_cost(args.cost_json)
     with scan_completion_lock(scan_id):
-        return complete_scan_locked(connection, scan_id, args.claim_token)
+        return complete_scan_locked(connection, scan_id, args.claim_token, cost_json)
 
 
 def complete_scan_locked(
-    connection: sqlite3.Connection, scan_id: str, claim_token: str | None
+    connection: sqlite3.Connection,
+    scan_id: str,
+    claim_token: str | None,
+    cost_json: str | None,
 ) -> dict[str, Any]:
     scan = require_scan(connection, scan_id)
     if scan["status"] == "complete":
@@ -1532,10 +1556,10 @@ def complete_scan_locked(
             """
             UPDATE scans
             SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
-                seal_manifest_digest = ?
+                seal_manifest_digest = ?, cost_json = ?
             WHERE id = ? AND status = 'running'
             """,
-            (timestamp, timestamp, manifest_digest, scan["id"]),
+            (timestamp, timestamp, manifest_digest, cost_json, scan["id"]),
         )
         if updated.rowcount != 1:
             raise SystemExit("Only a running scan can be completed.")
@@ -1731,6 +1755,7 @@ def coverage_for_comparison(scan: sqlite3.Row) -> dict[str, Any]:
 
 def fail_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
     scan_id = require_uuid(args.scan_id, "scan-id")
+    cost_json = parse_scan_cost(args.cost_json)
     connection.execute("BEGIN IMMEDIATE")
     try:
         timestamp = now()
@@ -1748,10 +1773,17 @@ def fail_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[
         updated = connection.execute(
             """
             UPDATE scans
-            SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?
+            SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
+                cost_json = ?
             WHERE id = ? AND status = 'running'
             """,
-            (optional_text(args.message, maximum=2400), timestamp, timestamp, scan["id"]),
+            (
+                optional_text(args.message, maximum=2400),
+                timestamp,
+                timestamp,
+                cost_json,
+                scan["id"],
+            ),
         )
         if updated.rowcount != 1:
             raise SystemExit("Only a running scan can be marked failed.")
@@ -3006,6 +3038,11 @@ def scan_result(
     return {
         "artifacts": artifacts,
         "canceledAt": scan["canceled_at"],
+        **(
+            {"cost": json.loads(scan["cost_json"], parse_constant=reject_non_finite_json)}
+            if scan["cost_json"] is not None
+            else {}
+        ),
         "contract": scan_contract(scan),
         "continuationThreadId": scan["continuation_thread_id"],
         "failureMessage": scan["failure_message"],
@@ -3208,9 +3245,13 @@ def finding_result(
         "title": bounded_output_text(occurrence["title"], FINDING_TITLE_BYTES),
         "triage": finding_triage_result(connection, occurrence["id"]),
     }
-    matches = scan_history.finding_matches(connection, occurrence["id"])
+    matches, known_since, known_scan_ids = scan_history.finding_matches(
+        connection, occurrence["id"], scan["id"], scan["started_at"]
+    )
     if matches:
         result["matches"] = matches
+        result["knownSince"] = known_since
+        result["knownScanIds"] = known_scan_ids
     result.pop("artifactPaths", None)
     source_excerpt = finding_source_excerpt(scan, target, locations)
     if source_excerpt: