OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
Hosted Standard scans (protocol v2)
codex-security scan --host runs one scan using newline-delimited JSON-RPC on
stdin/stdout. Use the flag alone. It performs no login, update check, local
inference, or model fallback.
For hosted patch generation and verification, use the separate hosted remediation API.
Public executor API
Use the standalone runHostedScan(input, { executor, signal, onEvent })
function to run one hosted Standard scan. CodexSecurity.run() retains its local
scan behavior; it does not accept a hosted executor. The CLI command is a thin
JSON-RPC adapter around the same standalone function.
The CLI owns scan registration, plugin lifecycle, target checks, finalization, report generation and sealed artifact validation. The host owns authorization, frozen checkout, execution, durable run state, replay, reconciliation, usage, billing and cleanup. It collects authoritative usage before cleanup and persists accepted output independently from inference. Findings ingestion and deduplication consume that accepted output separately. CLI workbench state remains scan-domain state; there is no hosted-attempt replay store.
In this TypeScript integration, host is your application's executor and
receipt store. Substitute your authorized model, checkout and frozen revision.
import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
const executor: ScanExecutor = {
async run(request, { signal, onEvent }) {
// Persist the request identity before dispatch. Mount the matching plugin,
// checkout, scan state and output directory in the remote executor.
return await host.executeOnce(request, { signal, onEvent });
},
};
const result = await runHostedScan(
{
version: 2,
repository: "/workspace/repository",
revision: "0123456789012345678901234567890123456789",
scope: { paths: ["services/api", "services/web"] },
outputDirectory: "/scan/output",
stateDirectory: "/scan/state",
model: "gpt-5.6-sol",
reasoningEffort: "high",
identity: {
runId: "run-1",
attemptId: "attempt-1",
buildId: "runtime-build",
},
},
{
executor,
onEvent(event) {
console.error(event);
},
},
);
// These host methods are application code, outside the CLI.
await host.persistReceipt(result);
if (result.status === "completed") {
// Check the frozen identity/scope and artifact paths, hashes, sizes and seals.
await host.verifyAndAcceptArtifacts(result);
} else if (result.status === "acceptance_unknown") {
// Look up the existing attempt/session; do not call runHostedScan again.
await host.reconcileExecution(result.identity, result.execution);
}
// Failed and canceled receipts remain recorded but are not accepted
// completed scans. Persistence retries reuse this receipt without more inference.
The function creates and closes its scan client internally, reusing the ordinary
Standard scan lifecycle. Omit scope for the entire repository, or pass literal
repository-relative folders/files. Model settings come from the frozen input;
local profiles and other local scan options are not accepted.
To supply grading rules, pass severityRubric with the Markdown text in
markdown, a positive integer revision, and the lowercase sha256 digest of
the exact UTF-8 text, including any trailing newline. The SDK verifies the digest
before dispatch, includes the rubric in the model prompt, and echoes the snapshot
in execution.run and the terminal scan receipt. Omit the field to use the
existing Standard scan grading rules.
When a logical run spans multiple attempts, save the selected snapshot in the host's durable run state before starting its first CLI process. Send that saved snapshot with every subsequent attempt for the same run, including attempts in a fresh checkout or container. A configuration change then applies to new runs.
ScanExecutor.run receives an AbortSignal and an optional onEvent observer for
{type: "progress", progress} or {type: "activity", activity} events. Progress
uses the existing ScanProgress type; activity uses ScanActivity. Progress may
include reviewItems: { completed, total } for saved reviews, counted separately
from files. Observer failures cannot stop execution. Aborting waits for the
executor to settle; the host must cancel remote work and return its recorded
outcome.
Preparation errors throw before execution. Execution and finalization return a
HostedScanResult receipt with status completed, failed,
canceled, or acceptance_unknown. The receipt retains the executor's outcome, session
identity, usage, message and structured error even if artifact finalization
fails. Only validated artifacts receive hashes and sizes. Repeated invocations
are separate scans; the host decides whether a new invocation is allowed.
Temporary runtime cleanup failures preserve the terminal receipt, including
its execution outcome, session identity, usage, and validated artifacts. They
are reported separately through onEvent as a failed message activity with
ID runtime.cleanup (a scan.progress notification over JSON-RPC). A cleanup
failure does not change the scan status or require another execution attempt.
Wire contract
Send {"jsonrpc":"2.0","id":"run","method":"run","params":...} with the
parameters below. IDs are strings or safe integers from -9007199254740991 through
9007199254740991; send larger numeric identifiers as strings.
{
"version": 2,
"repository": "/workspace/repository",
"revision": "0123456789012345678901234567890123456789",
"scope": { "paths": ["services/api", "services/web"] },
"outputDirectory": "/scan/output",
"stateDirectory": "/scan/state",
"model": "gpt-5.6-sol",
"reasoningEffort": "high",
"identity": {
"runId": "example-run",
"attemptId": "example-attempt",
"buildId": "exact-runtime-build"
}
}
Omit scope to scan the entire repository, matching the local CLI default.
{"paths":["."]} also means the repository. An explicit empty list is invalid;
root cannot be mixed with narrower paths. Each entry is one literal filename or
directory: app/[slug]/page.tsx and reports/a,b.ts are not patterns or lists.
Significant whitespace is preserved; " service " and " " do not select
"service" or the repository. An explicit empty string is invalid. Paths use the
ordinary CLI target resolver's filename semantics, with repository-relative
paths required here. They are normalized, deduplicated and sorted without
changing filename characters. Preparation also checks the existing output
contract: scope paths must be valid UTF-8 and cannot contain control characters,
backslashes, or start with a drive prefix such as C:. Incompatible filenames
fail before executor dispatch, including on POSIX where those files may exist.
Every selected path must exist and remain inside
the repository at the frozen revision before any execution request. Missing paths fail the whole
request; the CLI never skips them or broadens the scope. Canonical path aliases
are rejected with an actionable correction. Diff, Deep, resume, mock, local
workflow and post-scan execution are unsupported in this hosted Standard API.
The CLI verifies HEAD before path existence, registers the scan with its bundled
workbench, and sends one execution.run request. Its JSON-RPC ID equals the
required params.requestId. Params contain version: 2, normalized
repository, revision, scope, identity, registered scanId, prompt,
model, reasoningEffort, and runtime:
pluginRootandpluginVersion: the matching bundled plugin.stateDirectoryandoutputDirectory: writable paths outside the repository.environment: explicit runtime paths and interpreter settings, never host inference credentials.
The CLI and executor must share these filesystem paths or explicitly transfer the same state. This includes:
- The frozen checkout and matching
pluginRoottree, including its executable helpers, skills, and MCP server. - The whole
stateDirectory, including the registered workbench database, journals, and scan inputs; a live database file alone is not a consistent copy. outputDirectory, where the executor records its draft and the CLI later writes the validated manifest, findings and report.- The temporary files named by
CODEX_SECURITY_CONFIG_PATHand, for path scans,CODEX_SECURITY_TARGET_PATHS_FILEinruntime.environment. These are required by preflight and scope binding, even though they can live outside the state and output directories. The supplied interpreter paths must also resolve.
Keep these paths available throughout the invocation. The CLI removes its
temporary config/scope files when the invocation closes; caller-owned state
and output directories remain available. If remote work may outlive an
acceptance_unknown return, the host must preserve the files that work still
needs before returning that outcome. Use shared mounts or a coordinated transfer
that preserves the supplied path bindings, not independent copies of mutable
workbench state.
For path scans with the Linux CLI and a current plugin, use the inventory
path the scope helper reports. A Linux executor can keep the inventory in
stateDirectory outside the checkout and captured output. The state binding
may include one protected symlink and must exclude .. from the path and
link target. Its protected directory must support executor-owned mode-0600
files and keep a reader open across writer close.
Other layouts use scoped-source-input.jsonl in scan output. If a later
shell loses the inventory, run the recovery command in the prompt. It may
replace an earlier output file, so the executor needs permission to remove it.
State transfers include private inventories named
<scope-input-filename>.scoped-<24 lowercase hex digits>.jsonl. Hosts can
remove the request's private inventories after execution finishes.
Run the plugin stdio server from
pluginRoot/scripts/launch_codex_security_mcp --stdio with the supplied
environment. The executor needs the target files, plugin skills and registered
artifacts, and must expose record_codex_security_scan_draft. CLI workbench
finalization follows the turn. Merely returning model text is insufficient.
Separately provisioned executors must receive the exact frozen runtime/plugin
build and preserve state; do not interpret plugin schemas as strict Structured
Outputs schemas.
The execution response result has:
- Required
requestIdmatching the execution request, andstatus:completed,failed,canceled, oracceptance_unknown. sessionId, required for completed execution and optional for other outcomes.- Optional
finalResponse,message, and structurederrorwith numericcode, stringmessageand optionaldata. - Optional opaque host
usage. Absence means unknown, never zero. The host collects it for diagnostics; these observations do not replace authoritative accounting.
A transport failure or mismatched receipt is not proof of non-acceptance. The
CLI stops without resubmitting and leaves reconciliation to the host. The terminal
result retains execution even when scanning fails or is canceled. The runtime's
hostProtocolVersion identifies this protocol as version 2.
A package-exported example is available at
@openai/codex-security/schemas/hosted-scan-v2.fixture.json. Its response is
the executor's reply; terminal is the separate final scan receipt. The example
hashes and sizes are illustrative and do not validate any real files.
| Final scan status | Host handling |
|---|---|
completed |
Verify artifact receipts and seals before accepting output. |
failed or canceled |
Retain identity, diagnostics and any execution/usage receipt. |
acceptance_unknown |
Reconcile the existing remote attempt and collect usage before cleanup; do not resubmit blindly. |
Reconciliation uses the host's durable attempt/session identifiers and provider
status. Preserve state and output for inspection, and cancel or join remote work
before releasing resources it still uses. The hosted API has no replay store,
resume, or finalize-only operation: calling runHostedScan again registers a new
scan. A provider reporting execution completion does not substitute for a
validated, sealed scan receipt.
Optional owner suggestions
Set ownerSuggestions: true to record ownership evidence during the existing
scan execution. The scan agent may include an optional hint on each finding:
{
"extensions": {
"ownerSuggestion": {
"email": "[email protected]",
"commit": "0123456789012345678901234567890123456789",
"reason": "Maintains the affected source."
}
}
}
Use an observed contributor email and a full supporting commit hash from Git blame/history for the affected source. Omit the hint when ownership is unclear. The scan collects hints within its session and budget. Findings take priority over optional hints.
After sealing the scan, the SDK builds owner-suggestions.json without inference.
CODEOWNERS declarations take precedence. Other hints must match an observed Git
identity and supporting commit in the finding's evidence. Missing hints abstain;
invalid hints produce per-finding owner errors. Neither invalid hints nor report
failures invalidate sealed findings. A completed receipt includes the artifact
when available, or ownerSuggestionsError if finalization fails.
Read the owner report from the completed receipt. Finalization uses
suggestOwnersFromScan and can run after the scan reaches maxCostUsd.
The standalone suggestOwners API and suggest-owners command can call a
model under their own budget. Both paths use the same CODEOWNERS rules, Git
evidence, identity checks, and report format.
Progress, cancellation and artifacts
The host sends execution.progress notifications with {requestId, event}.
The CLI forwards valid progress/activity through scan.progress notifications
with {id: <original run RPC id>, event}. Invalid optional event payloads are
ignored; mismatched request IDs are rejected. Stdout contains JSON-RPC only.
Send {"jsonrpc":"2.0","method":"cancel","params":{"id":"run"}} with the
original run request ID. If canceled during checkout verification, the CLI returns
a canceled receipt with the requested checkout, scope, and rubric before starting
the executor. Invalid request fields still return a JSON-RPC error.
After dispatch the CLI aborts its executor signal, emits
execution.cancel with {requestId}, and waits for the host's outcome/usage
before returning a canceled result. For a registered scan, the durable lifecycle
and final scan receipt record cancellation even if the executor reports failure.
The execution field retains that failure, its diagnostics, and any usage.
A caller deadline expiring after registration records a failed scan, including
when the executor acknowledges the deadline with a canceled execution.
If the executor reports acceptance_unknown, the local scan records failed
and the host receives acceptance_unknown for reconciliation.
The host must continue reading notifications while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with blocked output terminate the transport even while a write callback is stuck. Input EOF before the terminal response fails the run; EOF while that response is flushing waits for the write callback. A selected successful result is not a successful delivery. Hosts own deadlines and independently cancel remote work and reconcile known execution identities after transport failure.
Preparation failures include typed error.data.reason for missing, escaping,
aliased or syntactically invalid paths and revision mismatch. Other failures
must not be presented as missing paths.
The terminal run result includes version: 2, status, frozen
identity/revision/normalized scope, output directory, scan ID when registered,
plugin version when known, provenance (CLI/plugin/build identity), optional execution,
and artifacts. Each artifact is {path, sha256, bytes} over its exact bytes.
Receipts cover canonical outputs, sealed supplemental files, and preserved
source files bound by the manifest. Coverage limitations remain diagnostics in
completed scans; required-output failures return failed, and unvalidated files
never receive artifact receipts. acceptance_unknown, failed
and canceled results are not accepted completed scans.
The host verifies receipt paths, hashes, sizes, scope, revision and seals before accepting output.