Thanks for helping improve Codex Security. We welcome bug reports, feature requests, documentation corrections, and feedback from open-source maintainers.
plugins/codex-security/ is the canonical source for the Codex Security
plugin. Make plugin changes there.
The npm runtime under sdk/typescript/_bundled_plugin/ is generated from the
plugin source by pnpm run build:plugin and automatically during prepack for
packages and releases. Do not edit or commit files in that directory. See the
SDK testing guide for the generation and validation
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.
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.
pnpm --dir sdk/typescript run generate:models also copies workbench argument
encoding and executable path handling from the plugin source into the SDK. Edit the
plugin helper, then regenerate its SDK copy. Historical finding normalization is
maintained in the SDK.
pnpm --dir sdk/typescript run types checks freshness.
Model-based evaluations live in evals/, outside the plugin
source. Deterministic triage checks and the MCP reducer IPC regression remain
part of normal CI.
See the CI guide for check selection, platform/version coverage, required status checks, and test-runner qualification.
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 and shared references | Portable plugin source checks |
| Artifact contracts and generated SDK models | Contract definitions, canonical exports, and model generator | Canonical contract tests, MCP wire tests, and the generation checks above |
| Deep Scan scheduling and workers | Shared engine, coordinator, and executor, used by the MCP server and SDK launcher | MCP tests and direct SDK integration |
| Durable scan state, checkpoints, and completion | Python workbench and Deep Scan persistence | Python tests and SDK workbench integration |
| Helper routing and stored-finding operations | SDK runtime routing, plugin helper entrypoint, and Node workbench commands | SDK runtime tests and MCP workbench tests |
| Public CLI and SDK behavior | CLI adapter, SDK API, and adjacent modules | SDK tests and the installed-package checks |
| Markdown report rendering | Scan report projection and threat-model projection | Report tests and threat-model tests |
| Native filesystem and process operations | Native bindings and adapters | The native guide's platform proofs and package checks |
| Packaged plugin contents | Plugin manifest and SDK plugin builder | Package inspection and installed consumers |
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 before opening a new one.
If you maintain an open-source project, open an issue with the repository, your role, and what you need. Support is best effort. Scan only repositories you trust and either own or have permission to assess.
Include your CLI or SDK version, operating system, reproduction steps, and the expected and observed behavior. Remove credentials, private code, customer data, and security findings before posting.
Open an issue describing the problem and the workflow you want to support. Documentation corrections and safe examples are welcome. Use synthetic examples when documenting expected behavior. Keep example values fictional and safe to share. Do not include credentials or private information in examples.
Report Codex Security vulnerabilities privately as described in SECURITY.md. Do not post vulnerabilities, exploit details, credentials, or sensitive scan results publicly.
If a scan finds a vulnerability in another project, report it to that project's maintainers through their security policy.
Keep pull request labels focused on release behavior and material platform
impact. Do not apply area:* labels to pull requests; describe the affected
surface in the title and description. Issues retain their existing area,
priority, and status labels. Existing maintainer triage labels can remain on
pull requests while they identify actionable, unresolved work.
Preserve the release labels bug, enhancement, documentation,
breaking-change, and skip-release-notes, including maintainer overrides.
Follow their release-note and version semantics. Do not replace
manual breaking-change or skip-release-notes labels based only on the title.
Use platform:windows only when Windows-specific behavior is material to the
change. Dependabot uses dependencies across all package ecosystems. Labels
are not required to open, test, review, or merge a pull request.
Open the node-ci run for the PR revision that failed. The ci job reports
the overall result. Open the failing build, test shard, or validation job to
find the original error. If a later attempt passed, use the run's attempt
selector to inspect the first failure. From the command line,
gh run view RUN_ID --attempt 1 --log-failed shows that attempt's failed steps.
For a transient infrastructure failure, rerun the failed jobs after checking the original logs. For a failed assertion, reproduce it on the reported platform with the logged seed when available. See the CI guide for check selection and the SDK testing guide for local reproduction.
Maintainers update package dependencies and committed lockfiles with the affected source. The public release workflow installs those locked graphs, tests the package, and publishes a verified artifact with npm provenance. GitHub Actions dependencies are maintained separately in this repository.
Workflow and composite-action changes run workflow-quality through
node-ci. actionlint validates workflow syntax, and ShellCheck
checks shell scripts in workflow run steps for warnings and errors. zizmor's
offline checks at medium severity and above cover workflows and composite
actions. The pinned tool versions are in .github/workflows/workflow-quality.yml;
run these checks locally with:
SHELLCHECK_OPTS=--severity=warning actionlint
zizmor --offline --strict-collection --min-severity medium --config .github/zizmor.yml .githubThe actionlint configuration preserves GitHub's supported release queue and job-level cache syntax until the linter supports them. The zizmor configuration records reviewed privileged triggers and their trust boundaries. Review these exceptions when changing the affected workflows.
CI package builds and npm release validation require the production dependency
audit to pass. Run it locally with pnpm --dir sdk/typescript run audit:prod.
The existing policy checks production dependencies at the high-severity threshold.
Resolve high or critical advisories, or audit service failures, before retrying.
GitHub Releases is the canonical changelog. Maintainers should follow RELEASING.md to prepare, publish, verify, or repair a release.
See the SDK testing guide for local checks, test conventions, and the required and experimental CI jobs.