Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

docs: map source ownership and regression checks for contributors (#1699)

Michael D'Angeloe7932baac27d
diff --git a/AGENTS.md b/AGENTS.md
index 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 before
submitting 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.
+
```bash
python -m ruff check --config plugins/codex-security/pyproject.toml plugins/codex-security
python -m ruff format --check --config plugins/codex-security/pyproject.toml plugins/codex-security
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 plugin
source. Deterministic triage checks and the MCP reducer IPC regression remain
part 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.md
index 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 a
regression case that fails before a fix over assertions about private calls
or 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 those
boundaries 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