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: explain that the local Git hook is advisory (#1000)
mldangelo-oaib2b7a005c4ad
diff --git a/SECURITY.md b/SECURITY.mdindex 98b0de437..8f1c7958d 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -48,6 +48,11 @@ operations can use repository configuration, hooks, filters, attributes,credential helpers, worktrees, and executables on your `PATH`. These are notseparate security boundaries.+`codex-security install-hook` adds an optional, advisory Git pre-commit check+that you control. When Git runs it, it blocks a commit if the scan cannot+finish or finds an issue at or above the configured severity. Use a required+CI check to enforce a passing scan.+### Local trust and attacker prerequisitesThe product does not isolate users, tasks, repositories, or scan jobs that@@ -120,8 +125,9 @@ Report reproducible issues in an official release, such as:explicitly selected.- Path traversal, a symlink, an archive, or a file-replacement race that writesoutside the approved output or sends an unrelated local file to a model.-- An incomplete, forged, or incorrectly scoped scan accepted as complete or as- a passing CI result.+- Accepting an incomplete, forged, or incorrectly scoped scan as complete or as+ a passing CI result. This includes Codex Security or one of its official CI+ integrations reporting success when no scan ran.- GitHub, package, update, dependency, or model-service input that causes anunauthorized local action or compromises a release.- A reachable vulnerability in the published package, bundled runtime, build,@@ -136,6 +142,9 @@ The following are not security vulnerabilities by themselves:- Reading selected repository files, resolving worktrees, running Git, orusing configured hooks, filters, credential helpers, and executables withinthe authority you granted.+- Changing, disabling, or skipping a local Git pre-commit hook, unless Codex+ Security or one of its official CI integrations falsely reports that a scan+ completed or passed.- An attack that assumes prior control of your operating-system account,trusted local Git settings, private Codex state, or private scan outputswithout showing how a supported input gains that control.diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 8a097088a..7579096fb 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -1611,9 +1611,45 @@ runtime/export error, `130` for interruption, and `143` for termination.JSON scans do not use interactive controls. `validate`, `login`, and `logout`reject `--json`.-`install-hook` scans staged and unstaged changes before each commit. It blocks-on high-severity findings or failed scans, respects `core.hooksPath`, and leaves-existing hooks alone. Change the threshold with `--fail-on-severity`.+`install-hook` adds an optional local Git pre-commit check for staged and+unstaged changes. It's advisory; use a required CI check to enforce a passing+scan. When Git runs the hook, it blocks commits if the scan can't finish or+finds an issue at or above the threshold (`high` by default). Set it when+installing with `--fail-on-severity`. The installer respects `core.hooksPath`+and leaves custom hooks alone.++We recommend installing the CLI outside the repository and running that copy+directly. For a global installation:++```bash+npm install --global @openai/codex-security+```++If the repository also has a local copy, `npx` may run it instead.++Before installing or replacing a hook, run+`git -C /path/to/repository rev-parse --git-path hooks/pre-commit`. Git may+return a path relative to `/path/to/repository`. Check the hook, if it exists,+and the path to its directory for symlinks or shared locations. Leave custom,+linked, shared, or unverified hooks alone. If they need to change, contact the+owner or use a required CI check. Check older generated hooks too; the installer+can update them automatically.++If the hooks directory belongs only to this repository and there is no hook,+run the global CLI from outside the repository:++```bash+codex-security install-hook /path/to/repository+```++To migrate a hook, confirm it's a regular file used only by this repository+and contains only the generated Codex Security command. Keep its severity.+The installer can update older hooks that invoke `npx` if you use the same+severity. Newer hooks store absolute paths to Node and the CLI. If either path+changes, the installer won't replace the hook: back it up, remove it, and rerun+`codex-security install-hook /path/to/repository` with the same+`--fail-on-severity` value (default: `high`). If reinstallation fails, restore+the backup and verify the hook before relying on it.### Import alerts from the CLIdiff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex e06320621..b4da85512 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -3743,7 +3743,8 @@ export async function main(},}).command("install-hook", {- description: "Install a Git pre-commit security scan.",+ description:+ "Install an advisory local Git pre-commit check. Require a passing scan in CI.",destructive: true,mcp: false,args: z.object({