← Files Codex SecurityARCHIVED FILE
scripts/workbench_finding_workflows.py
14.7 KB · Nov 18, 2026 · 06:11 UTC
"""Durable state for the opt-in local scan, publication, and dedupe workflow."""
from __future__ import annotations
import argparse
import hashlib
import json
import sqlite3
import stat
import sys
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
from workbench_scan_usage import stored_scan_cost_fields
from workbench_target import (
UnreadableLocalFile,
UnsupportedLocalFileType,
directory_content_digest,
git_bytes,
git_revision,
)
from workbench_validation import _valid_legacy_scan_cost
WORKFLOW_BINDINGS = {
"repositoryPath": "repository_path",
"scanRequestDigest": "scan_request_digest",
"scanId": "scan_id",
"scanDir": "scan_dir",
"artifactDigest": "artifact_digest",
"destination": "destination",
}
WORKFLOW_STAGES = ("scan", "publish", "dedupe")
def _usable_cost_range(value: Any) -> bool:
if not isinstance(value, dict) or value.get("context") != "unknown" or "max" not in value:
return False
minimum, maximum = value.get("min"), value["max"]
return (
type(minimum) in (int, float)
and 0 <= minimum <= sys.float_info.max
and (
maximum is None
or type(maximum) in (int, float)
and minimum <= maximum <= sys.float_info.max
)
)
def _recorded_cost(value: str | None) -> dict[str, Any] | None:
"""Recover the SDK cost fields that are usable from this historical receipt."""
try:
cost = stored_scan_cost_fields(value).get("cost")
except (TypeError, ValueError, RecursionError):
return None
if not _valid_legacy_scan_cost(cost):
return None
fields = (
"model",
"inputTokens",
"cachedInputTokens",
"cacheWriteInputTokens",
"outputTokens",
"estimatedUsd",
)
result = {field: cost[field] for field in fields}
if isinstance(cost.get("cacheWriteInputTokensReported"), bool):
result["cacheWriteInputTokensReported"] = cost["cacheWriteInputTokensReported"]
bounds = cost.get("estimatedUsdRange")
if _usable_cost_range(bounds):
result["estimatedUsdRange"] = {field: bounds[field] for field in ("min", "max", "context")}
pricing = cost.get("pricing")
if (
isinstance(pricing, dict)
and pricing.get("serviceTier") == "standard"
and pricing.get("context") == "short"
and isinstance(pricing.get("source"), str)
and isinstance(pricing.get("asOf"), str)
):
details = {field: pricing[field] for field in ("source", "asOf", "serviceTier", "context")}
rate_keys = ("input", "cacheRead", "cacheWrite", "output")
for field in ("usdPerMillionTokens", "longContextUsdPerMillionTokens"):
rates = pricing.get(field)
if isinstance(rates, dict) and all(
type(rates.get(key)) in (int, float) and 0 <= rates[key] <= sys.float_info.max
for key in rate_keys
):
details[field] = {key: rates[key] for key in rate_keys}
if "usdPerMillionTokens" in details:
result["pricing"] = details
return result
def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str, Any] | None:
"""Return the stored stages, scope, and available scan cost, or None if the workflow ID is unknown."""
row = connection.execute(
"""SELECT w.*, s.cost_json FROM finding_workflows AS w
LEFT JOIN scans AS s ON s.id = w.scan_id AND s.scan_dir = w.scan_dir
AND s.status = 'complete'
WHERE w.id = ?""",
(workflow_id,),
).fetchone()
if row is None:
return None
state = {"id": row["id"], "stages": {}}
if (cost := _recorded_cost(row["cost_json"])) is not None:
state["recordedCost"] = cost
for field, column in WORKFLOW_BINDINGS.items():
if row[column] is not None:
state[field] = row[column]
if row["scope_repository_id"] is not None:
state["scope"] = {"repositoryId": row["scope_repository_id"]}
elif row["scope_all_repositories"] is not None:
state["scope"] = {"allRepositories": bool(row["scope_all_repositories"])}
results = json.loads(row["results_json"])
for stage in WORKFLOW_STAGES:
current = {"status": row[f"{stage}_status"]}
if row[f"{stage}_error"] is not None:
current["error"] = row[f"{stage}_error"]
if stage in results:
current["result"] = results[stage]
state["stages"][stage] = current
if "dedupePendingWrite" in results:
state["stages"]["dedupe"]["pendingWrite"] = results["dedupePendingWrite"]
return state
def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestamp: str) -> None:
"""Insert or update the workflow bindings, scope, stage statuses, and saved results in the caller’s connection."""
values = {"id": state["id"]}
values.update({column: state.get(field) for field, column in WORKFLOW_BINDINGS.items()})
scope = state.get("scope", {})
values.update(
scope_repository_id=scope.get("repositoryId"),
scope_all_repositories=scope.get("allRepositories"),
)
results = {}
for stage in WORKFLOW_STAGES:
current = state["stages"][stage]
values[f"{stage}_status"] = current["status"]
values[f"{stage}_error"] = current.get("error")
if "result" in current:
results[stage] = current["result"]
if "pendingWrite" in state["stages"]["dedupe"]:
results["dedupePendingWrite"] = state["stages"]["dedupe"]["pendingWrite"]
values.update(
results_json=json.dumps(results, allow_nan=False),
created_at=timestamp,
updated_at=timestamp,
)
updates = ", ".join(
f"{column} = excluded.{column}" for column in values if column not in {"id", "created_at"}
)
connection.execute(
f"INSERT INTO finding_workflows ({', '.join(values)}) "
f"VALUES ({', '.join('?' for _ in values)}) ON CONFLICT(id) DO UPDATE SET {updates}",
tuple(values.values()),
)
def bind_workflow(state: dict[str, Any], binding: dict[str, Any]) -> None:
"""Add bindings to the supplied state in place, raising SystemExit for unknown or conflicting fields."""
for field, value in binding.items():
if field not in WORKFLOW_BINDINGS and field != "scope":
raise SystemExit("Unknown workflow binding.")
if field in state and state[field] != value:
raise SystemExit(
f"Workflow {state['id']} is already bound to a different {field}. "
"Use another --workflow-id."
)
state[field] = value
def register_workflow_scan(
connection: sqlite3.Connection, workflow_id: str, scan_id: str, scan_dir: str, timestamp: str
) -> None:
"""Called inside the scan-registration transaction, before model execution."""
state = read_workflow(connection, workflow_id)
if state is None:
raise SystemExit("The workflow must be started before registering its scan.")
if state["stages"]["scan"]["status"] == "completed":
raise SystemExit("The workflow scan is already complete.")
previous = state.get("scanId")
if previous is not None:
row = connection.execute(
"""SELECT saved.status, saved.recipe_json AS saved, attempt.recipe_json AS attempt
FROM scans AS saved JOIN scans AS attempt ON attempt.id = ? WHERE saved.id = ?""",
(scan_id, previous),
).fetchone()
if row is not None:
if row["status"] == "complete":
raise SystemExit(
"Reuse the workflow's completed scan instead of registering another."
)
saved = json.loads(row["saved"] or "{}")
attempt = json.loads(row["attempt"] or "{}")
if saved.get("severityRubric") != attempt.get("severityRubric"):
raise SystemExit(
"Another attempt registered a different severity rubric. Retry this workflow to reuse its saved rubric."
)
state["scanId"] = scan_id
state["scanDir"] = scan_dir
save_workflow(connection, state, timestamp)
def finding_workflow(
connection: sqlite3.Connection, payload: dict[str, Any], timestamp: str
) -> dict[str, Any]:
"""Dispatch a workflow request by ID and return its state, source snapshot, or review as the action specifies."""
workflow_id = payload["id"]
if not isinstance(workflow_id, str) or not workflow_id.strip():
raise SystemExit("workflowId must be a nonempty string.")
if payload["action"] == "get":
return {"workflow": read_workflow(connection, workflow_id)}
if payload["action"] == "source":
evidence = payload.get("evidence") is True
if evidence:
try:
target = Path(payload["repository"])
metadata = target.lstat()
if (
not target.is_absolute()
or not stat.S_ISDIR(metadata.st_mode)
or getattr(metadata, "st_reparse_tag", 0) & 0x20000000
or target.resolve(strict=True) != target
):
raise UnreadableLocalFile("The validation evidence directory was replaced.")
except (OSError, RuntimeError, UnreadableLocalFile):
if payload.get("optional") is True:
return {"source": None}
raise
else:
target = Path(payload["repository"]).resolve(strict=True)
private_paths = payload.get("privateStatePaths", [])
if not isinstance(private_paths, list) or any(
not isinstance(path, str) or not Path(path).is_absolute() for path in private_paths
):
raise SystemExit("Private runtime paths must be absolute paths.")
excluded = tuple(sorted({Path(path).resolve() for path in private_paths}))
excluded = tuple(path for path in excluded if path.is_relative_to(target))
if target in excluded:
raise SystemExit("Private runtime storage must not exclude the repository root.")
try:
content = directory_content_digest(
target,
excluded=excluded,
include_ignored=True,
include_git_metadata=evidence,
)
except (UnsupportedLocalFileType, UnreadableLocalFile, OSError):
if payload.get("optional") is True:
return {"source": None}
raise
return {
"source": {
"repository": str(target),
"revision": (
"unversioned"
if evidence or payload.get("gitDisabled")
else git_revision(target)
),
"refsDigest": hashlib.sha256(
b""
if evidence or payload.get("gitDisabled")
else (git_bytes(target, "show-ref") or b"").strip()
).hexdigest(),
"content": content,
**({"privateStatePaths": [str(path) for path in excluded]} if excluded else {}),
}
}
if payload["action"] == "get-review":
row = connection.execute(
"SELECT result_json FROM finding_workflow_reviews WHERE workflow_id = ? AND review_key = ?",
(workflow_id, payload["key"]),
).fetchone()
return {"review": json.loads(row["result_json"]) if row is not None else None}
if payload["action"] == "save-review":
binding = payload["binding"]
source = binding["source"]
scope = binding["scope"]
on_conflict = (
"DO UPDATE SET result_json = excluded.result_json, created_at = excluded.created_at"
if payload.get("replace") is True and binding.get("stage") == "scan-validation"
else "DO NOTHING"
)
with connection:
connection.execute(
f"""INSERT INTO finding_workflow_reviews
(workflow_id, review_key, review_contract_version, codex_version,
source_repository_path, source_revision, source_refs_digest, source_content_digest,
scope_repository_id, scope_all_repositories, model, effort, settings_digest,
prompt_digest, contract_digest, result_json, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(workflow_id, review_key) {on_conflict}""",
(
workflow_id,
payload["key"],
binding["version"],
binding["codexVersion"],
source["repository"],
source["revision"],
source["refsDigest"],
source["content"],
scope.get("repositoryId"),
scope.get("allRepositories"),
binding["model"],
binding["effort"],
binding.get("settingsDigest"),
binding["promptDigest"],
binding["contractDigest"],
json.dumps(payload["result"], allow_nan=False),
timestamp,
),
)
return {}
connection.execute("BEGIN IMMEDIATE")
with connection:
state = read_workflow(connection, workflow_id)
if state is None:
state = {
"id": workflow_id,
"stages": {stage: {"status": "pending"} for stage in WORKFLOW_STAGES},
}
bind_workflow(state, payload.get("binding", {}))
action = payload["action"]
if action != "bind":
stage = payload["stage"]
if stage not in state["stages"]:
raise SystemExit("Unknown workflow stage.")
current = state["stages"][stage]
if current["status"] != "completed":
if action == "begin":
current["status"] = "running"
elif action == "complete":
state["stages"][stage] = {"status": "completed", "result": payload["result"]}
elif action == "fail":
current.update(status="failed", error=payload["error"])
if "result" in payload:
current["result"] = payload["result"]
elif action == "prepare-dedupe":
current.update(result=payload["result"], pendingWrite=payload["pendingWrite"])
else:
raise SystemExit("Unknown workflow action.")
save_workflow(connection, state, timestamp)
return {"workflow": state}
if __name__ == "__main__":
argparse.ArgumentParser(description=__doc__).parse_args()
SHA-256: 2d3914e553d5e5bf710a8d27bd25f878a023449270b2045db97a9752c1f7ba51