← Files Codex SecurityARCHIVED FILE
scripts/workbench_validation.py
9.95 KB · Nov 18, 2026 · 06:11 UTC
"""Shared validation helpers for Codex Security workbench commands."""
from __future__ import annotations
import argparse
import json
import math
import re
import sqlite3
import sys
import uuid
from datetime import datetime
from pathlib import Path
from typing import Any
# Some plugin hosts launch Python with safe-path isolation enabled.
sys.path.insert(0, str(Path(__file__).resolve().parent))
import finalize_scan_contract as finalizer
from workbench_constants import optional_text as optional_text
from workbench_scan_usage import TOKEN_FIELDS, valid_account_rate_limit
from workbench_scan_usage import (
_reject_nonstandard_json_number as reject_nonstandard_json_number,
)
from workbench_scan_usage import _timestamp as usage_timestamp
reject_non_finite_json = finalizer._reject_non_finite_json
def read_json_object(path: Path) -> dict[str, Any]:
"""Read a UTF-8 JSON object from path, raising SystemExit on read errors, malformed JSON, or another top-level type."""
try:
payload = json.loads(
path.read_text(encoding="utf-8"),
parse_constant=reject_non_finite_json,
)
except (OSError, ValueError) as exc:
raise SystemExit(f"{path.name}: invalid JSON: {exc}") from exc
if not isinstance(payload, dict):
raise SystemExit(f"{path.name}: expected a JSON object.")
return payload
def javascript_utf8(value: str) -> bytes:
"""Match Node's UTF-8 encoding of UTF-16 strings without changing stored text."""
return (
value.encode("utf-16-le", errors="surrogatepass")
.decode("utf-16-le", errors="replace")
.encode("utf-8")
)
def timestamp_key(value: str) -> datetime:
return finalizer.parse_timestamp(value)
def require_uuid(value: str, label: str) -> str:
"""Return the standard hyphenated UUID text or raise SystemExit using label to identify the invalid argument."""
try:
return str(uuid.UUID(value))
except ValueError as exc:
raise SystemExit(f"{label} must be a UUID.") from exc
def sqlite_busy(error: sqlite3.OperationalError) -> bool:
return "locked" in str(error).lower() or "busy" in str(error).lower()
path_within_scope = finalizer.path_within_scope
def require_close_note(close_reason: str | None, note: str | None) -> None:
"""Require a note when closing a finding as a false positive or when declining a fix."""
if note is None and close_reason == "false_positive":
raise SystemExit("Explain why this finding is a false positive.")
if note is None and close_reason == "wont_fix":
raise SystemExit("Explain why this finding will not be fixed.")
def user_context_argument(args: argparse.Namespace) -> str | None:
value = sys.stdin.read() if getattr(args, "user_context_stdin", False) else args.user_context
return optional_text(value)
SCAN_USAGE_TOKEN_KEYS = tuple(TOKEN_FIELDS.values())
def _valid_legacy_scan_cost(cost: object) -> bool:
token_keys = ("inputTokens", "cachedInputTokens", "cacheWriteInputTokens", "outputTokens")
try:
return (
isinstance(cost, dict)
and isinstance(cost.get("model"), str)
and bool(cost["model"])
and all(type(cost.get(key)) is int and cost[key] >= 0 for key in token_keys)
and cost["cachedInputTokens"] + cost["cacheWriteInputTokens"] <= cost["inputTokens"]
and type(cost.get("estimatedUsd")) in (int, float)
and math.isfinite(cost["estimatedUsd"])
and cost["estimatedUsd"] >= 0
)
except OverflowError:
return False
def _valid_measured_scan_usage(usage: object) -> bool:
if not isinstance(usage, dict):
return False
coverage = usage.get("coverage")
thread_count = usage.get("threadCount")
if (
coverage not in ("complete", "partial", "unavailable")
or usage.get("source") not in ("codex_rollout", "codex_runtime")
or type(thread_count) is not int
or thread_count < 0
):
return False
completion = usage.get("completion")
if "completion" in usage and (
not isinstance(completion, dict)
or set(completion) != {"threadId", "turnId", "finalized"}
or not isinstance(completion["threadId"], str)
or not completion["threadId"]
or not isinstance(completion["turnId"], str)
or not completion["turnId"]
or type(completion["finalized"]) is not bool
or not completion["finalized"]
and coverage == "complete"
):
return False
warnings = usage.get("warnings", [])
if (
not isinstance(warnings, list)
or len(warnings) > 32
or any(
not isinstance(warning, str) or re.fullmatch(r"[a-z][a-z0-9_]{0,63}", warning) is None
for warning in warnings
)
or len(set(warnings)) != len(warnings)
):
return False
if "accountRateLimits" in usage:
limits = usage["accountRateLimits"]
if not isinstance(limits, list) or not all(
valid_account_rate_limit(limit) for limit in limits
):
return False
if coverage == "unavailable":
return thread_count == 0 and set(usage).issubset(
{"coverage", "source", "threadCount", "warnings", "completion", "accountRateLimits"}
)
allowed_keys = {
"coverage",
"coverageScope",
"source",
"threadCount",
"missingThreadCount",
"warnings",
"completion",
"byRole",
"window",
"observedAt",
"tokensUpdatedAt",
"accountRateLimits",
"cacheWriteInputTokensReported",
*SCAN_USAGE_TOKEN_KEYS,
}
if thread_count == 0 or not set(usage).issubset(allowed_keys):
return False
if "coverageScope" in usage:
scope = usage["coverageScope"]
if (
not isinstance(scope, list)
or any(not isinstance(identity, str) or not identity for identity in scope)
or len(set(scope)) != len(scope)
):
return False
if (
not all(type(usage.get(key)) is int and usage[key] >= 0 for key in SCAN_USAGE_TOKEN_KEYS)
or usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]
or "cacheWriteInputTokensReported" in usage
and type(usage["cacheWriteInputTokensReported"]) is not bool
):
return False
missing = usage.get("missingThreadCount", 0)
if type(missing) is not int or missing < 0:
return False
if coverage == "complete" and (
any(warning != "cost_estimate_covers_earlier_usage" for warning in warnings) or missing
):
return False
if coverage == "partial" and not (warnings or missing):
return False
for field in ("observedAt", "tokensUpdatedAt"):
if field in usage and usage_timestamp(usage[field]) is None:
return False
if "window" in usage:
window = usage["window"]
if not isinstance(window, dict) or set(window) != {"startedAt", "endedAt"}:
return False
start, end = (usage_timestamp(window[key]) for key in ("startedAt", "endedAt"))
if start is None or end is None or start > end:
return False
if "byRole" in usage:
roles = usage["byRole"]
keys = {*SCAN_USAGE_TOKEN_KEYS, "threadCount"}
if not isinstance(roles, dict) or set(roles) != {"parent", "workers"}:
return False
if any(
not isinstance(role, dict)
or not keys.issubset(role)
or not set(role).issubset({*keys, "cacheWriteInputTokensReported"})
or any(type(role[key]) is not int or role[key] < 0 for key in keys)
or "cacheWriteInputTokensReported" in role
and type(role["cacheWriteInputTokensReported"]) is not bool
for role in roles.values()
):
return False
if any(sum(role[key] for role in roles.values()) != usage[key] for key in keys):
return False
return True
def parse_scan_cost(value: str | None) -> str | None:
"""Return compact JSON for valid measured usage or a legacy cost estimate.
None means cost data was omitted. Invalid JSON, nonfinite numbers, or an
unsupported cost record raise SystemExit.
"""
if value is None:
return None
try:
cost = json.loads(value, parse_constant=reject_nonstandard_json_number)
except (TypeError, UnicodeError, ValueError) as exc:
raise SystemExit("Scan cost must be a valid JSON object.") from exc
if isinstance(cost, dict) and "usage" in cost:
if (
not set(cost).issubset({"usage", "cost"})
or not _valid_measured_scan_usage(cost["usage"])
or "cost" in cost
and not _valid_legacy_scan_cost(cost["cost"])
):
raise SystemExit("Scan cost includes invalid measured token usage.")
elif not _valid_legacy_scan_cost(cost):
raise SystemExit(
"Scan cost must include a model, nonnegative token counts, and an estimated USD amount."
)
return json.dumps(cost, separators=(",", ":"), allow_nan=False)
def bounded_output_text(value: Any, maximum_bytes: int) -> str:
"""Return the prefix of the stringified value that fits in maximum_bytes of UTF-8 without splitting a character."""
encoded = str(value).encode("utf-8")[:maximum_bytes]
return encoded.decode("utf-8", errors="ignore")
def require_occurrence(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row:
"""Return the finding occurrence row or raise SystemExit if its ID is missing or unknown."""
occurrence_id = optional_text(occurrence_id, maximum=256)
if occurrence_id is None:
raise SystemExit("occurrence-id is required.")
row = connection.execute(
"SELECT * FROM finding_occurrences WHERE id = ?", (occurrence_id,)
).fetchone()
if row is None:
raise SystemExit("Codex Security finding occurrence not found.")
return row
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
SHA-256: 06746a3aae15e85cd5c1671bf4da16f000cc2ad1cb19bbea9e63e00fa524e2ea