OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
docs: map source ownership and regression checks for contributors (#1699)
Michael D'Angeloe7932baac27d
diff --git a/AGENTS.md b/AGENTS.mdindex 4c427a140..e00c02abe 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -21,6 +21,9 @@ Codex Security is a thin wrapper around Codex and its security plugin.When changing `plugins/codex-security`, run its portable source checks beforesubmitting the change:+Run the commands in order from the repository root. `build:ci` compiles the tracked+`.mts` source checks into the generated `.mjs` entrypoints used below.+```bashpython -m ruff check --config plugins/codex-security/pyproject.toml plugins/codex-securitypython -m ruff format --check --config plugins/codex-security/pyproject.toml plugins/codex-securitydiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex dc6dc0280..3d2ba1de9 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -18,6 +18,7 @@ commands.Compact artifact contracts are authored in `plugins/codex-security/mcp-app/src/artifact-contracts.ts`, with shared finding and threat-model definitions in `finding-detail-schemas.ts` and `threat-model-schema.ts`.Canonical findings, scan-manifest, and coverage exports are defined in `mcp-app/scripts/canonical-schemas.mts`; patch-risk exports and their static type are defined in `mcp-app/src/patch-risk-schema.ts`.The corresponding JSON schemas are generated compatibility resources. Canonical runtime validation continues to use the selected plugin's JSON schemas.+Model-facing MCP schemas are projected by [`artifact-schema-loader.ts`](plugins/codex-security/mcp-app/src/artifact-schema-loader.ts).After editing the contracts, run `node plugins/codex-security/mcp-app/scripts/generate-artifact-schemas.mjs`.The MCP `typecheck` command checks that the generated resources are current. SDK model generation remains based on the canonical JSON exports.@@ -31,6 +32,29 @@ Model-based evaluations live in [`evals/`](evals/README.md), outside the pluginsource. Deterministic triage checks and the MCP reducer IPC regression remainpart of normal CI.+## Where to make a change++Start with the owner of the behavior, then follow its callers when the change+crosses a process, persistence, or package boundary.++| Change | Source to start with | Relevant checks |+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Plugin instructions | [Skills](plugins/codex-security/skills/) and shared [references](plugins/codex-security/references/) | [Portable plugin source checks](AGENTS.md#keep-it-simple) |+| Artifact contracts and generated SDK models | [Contract definitions](plugins/codex-security/mcp-app/src/artifact-contracts.ts), [canonical exports](plugins/codex-security/mcp-app/scripts/canonical-schemas.mts), and [model generator](sdk/typescript/scripts/generate-models.cjs) | [Canonical contract tests](plugins/codex-security/mcp-app/tests/test_canonical_artifact_contracts.ts), [MCP wire tests](plugins/codex-security/mcp-app/tests/test_compact_artifact_wire.ts), and the generation checks above |+| Deep Scan scheduling and workers | Shared [engine, coordinator, and executor](plugins/codex-security/mcp-app/src/deep-scan/), used by the MCP server and SDK launcher | [MCP tests](plugins/codex-security/mcp-app/tests/) and [direct SDK integration](sdk/typescript/tests-ts/direct-deep-scan.test.ts) |+| Durable scan state, checkpoints, and completion | [Python workbench](plugins/codex-security/scripts/workbench_db.py) and [Deep Scan persistence](plugins/codex-security/scripts/deep_scan_workbench.py) | [Python tests](plugins/codex-security/tests/) and [SDK workbench integration](sdk/typescript/tests-ts/deep-scan-workbench.test.ts) |+| Helper routing and stored-finding operations | SDK [runtime routing](sdk/typescript/src/runtime.ts), plugin [helper entrypoint](plugins/codex-security/mcp-app/helpers-main.ts), and [Node workbench commands](plugins/codex-security/mcp-app/src/workbench/commands.ts) | [SDK runtime tests](sdk/typescript/tests-ts/runtime.test.ts) and [MCP workbench tests](plugins/codex-security/mcp-app/tests/) |+| Public CLI and SDK behavior | [CLI adapter](sdk/typescript/src/cli.ts), [SDK API](sdk/typescript/src/api.ts), and adjacent modules | [SDK tests](sdk/typescript/tests-ts/) and the [installed-package checks](sdk/typescript/TESTING.md) |+| Markdown report rendering | [Scan report projection](plugins/codex-security/scripts/report_projection.py) and [threat-model projection](plugins/codex-security/scripts/threat_model_projection.py) | [Report tests](plugins/codex-security/tests/test_report_projection.py) and [threat-model tests](plugins/codex-security/tests/test_threat_model_projection.py) |+| Native filesystem and process operations | [Native bindings and adapters](plugins/codex-security/native/README.md) | The native guide's platform proofs and package checks |+| Packaged plugin contents | [Plugin manifest](plugins/codex-security/plugin-files.json) and [SDK plugin builder](sdk/typescript/scripts/build-plugin.mjs) | [Package inspection and installed consumers](sdk/typescript/TESTING.md) |++The SDK routes selected stored-finding and classification commands to the Node+helper; scan lifecycle commands still use the Python workbench. Trace the+specific command before changing either implementation. Shared Deep Scan+behavior belongs in the plugin engine, with adapter changes in the MCP server+or SDK only when their entrypoint behavior differs.+Search [existing issues](https://github.com/openai/codex-security/issues)before opening a new one.diff --git a/sdk/typescript/TESTING.md b/sdk/typescript/TESTING.mdindex 41af0485f..44566ac03 100644--- a/sdk/typescript/TESTING.md+++ b/sdk/typescript/TESTING.md@@ -84,9 +84,20 @@ The requirements file is the single list of pinned Python test dependencies. Ruf- Test observable results, failures, cancellation, and cleanup. Prefer aregression case that fails before a fix over assertions about private callsor exact prose.+- Pair a fault case with a healthy control when that shows the failure's cause.+ For ordering bugs, coordinate the relevant events explicitly rather than+ relying on sleeps: for example, persist a checkpoint before cancellation or+ fail an operation before its cleanup runs.- Keep fixtures synthetic and independent. Use real temporary directories,Git repositories, SQLite databases, and installed packages when thoseboundaries are the behavior under test. Do not use live model credentials.+- Follow the changed behavior through its consumer. Parser checks alone do not+ prove public API output, persisted state, child-process settings, or installed+ package behavior. Use the relevant boundary without repeating every test at+ every layer. See the [source map](../../CONTRIBUTING.md#where-to-make-a-change).+- When a result can be partial, assert what was retained and what remains+ unknown. Distinguish empty results from unavailable results, and checkpointed+ worker output from accepted results and published scan artifacts.- Use the typed `TestClient` and `createApiTestFixtures` helpers for API tests.Do not add a production abstraction solely to support a mock.- Test workflow retry, resume, and checkpoint permutations with the existing