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: explain that the local Git hook is advisory (#1000)

mldangelo-oaib2b7a005c4ad
diff --git a/SECURITY.md b/SECURITY.md
index 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 not
separate 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 prerequisites
The 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 writes
outside 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 an
unauthorized 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, or
using configured hooks, filters, credential helpers, and executables within
the 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 outputs
without showing how a supported input gains that control.
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 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 CLI
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 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({