Start with the source map for a code or documentation change. For a bug or feature request, search existing issues first. Report vulnerabilities through the security policy.
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 |
|---|---|---|
| Documentation | User guides, SDK and CLI guides, and examples | Run node sdk/typescript/scripts/check-markdown.mjs after installing the SDK dependencies. Check examples from their stated working directory. |
| 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 schema generation checks |
| 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.
plugins/codex-security/ is the canonical source for the Codex Security
plugin. Make plugin changes there.
To inspect the bundled npm plugin, download the native package inputs, then run pnpm --dir sdk/typescript run build:plugin from the repository root. The build writes sdk/typescript/_bundled_plugin/. Packaging also generates this directory during prepack. Edit the plugin source and leave generated files out of commits.
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.
The SDK build reads Deep Scan setting names from
plugins/codex-security/mcp-app/src/deep-scan-settings.ts. If you build the
SDK from a sparse checkout, include this file alongside the plugin defaults
and severity rubric.
Model-based evaluations live in evals/, outside the plugin
source. CI runs deterministic triage checks and the Deep Scan iteration and
publication tests in the MCP suite.
See the CI guide for check selection, platform/version coverage, required status checks, and test-runner qualification.
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. Use synthetic examples that contributors can reproduce and share publicly.
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.
For changes to Jira intake or tracking, use synthetic findings in a designated QA project.
- Verify the site, account and selected connection. Read a synthetic issue by key and through a project-scoped JQL search that spans more than one page.
- Track a finding through the Atlassian app. Create an issue, repeat the operation to verify reuse, then update the approved fields. Read the issue back after each write and check for duplicates.
- Try a missing connection and an account with insufficient access. Check that each failure explains how to recover and leaves the project without duplicate issues.
Record live checks separately from static tests. Keep account and project details, issue keys and raw tool responses private. Report product vulnerabilities through SECURITY.md.
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.