README examples use unscoped npx codex-security instead of npx @openai/codex-security

[nickytonline]

Summary

Both READMEs tell users to run the CLI via npx codex-security ..., but the published package is scoped: @openai/codex-security. The bin name inside the package is codex-security, so the bare form only works if the scoped package has already been installed locally (npx then finds node_modules/.bin/codex security). Run cold — the documented "quick start" path for a new user — npx codex-security resolves against the npm registry under the unscoped name instead, which is a different, unrelated package.

Affected docs (current main @ f22d4a3):

• https://github.com/openai/codex-security/blob/f22d4a3/README.md#L11-L26
• https://github.com/openai/codex-security/blob/f22d4a3/sdk/typescript/README.md
  (~45 occurrences throughout)

Currently if you run the command you get this

❯ npx codex-security scan . --auth chatgpt

You ran the wrong package. This one does nothing.

You almost certainly wanted:
  npx @openai/codex-security

The real Codex Security CLI is published under the @openai scope. Its
installed command is named `codex-security`, which is why the unscoped name
looks right — but the scope is the part that proves who published it.

What this package is: an empty placeholder holding the unscoped name
`codex-security` so that nobody else can publish executable code there. It is
not affiliated with OpenAI. It has no dependencies and does nothing.

Why the distinction matters: npx runs a name it cannot resolve locally by
fetching it from the registry and executing it immediately. An unscoped name
that merely resembles an official command is enough to run a stranger's code
with your permissions. Check the scope before you run, not after.

And the part worth sitting with: the tool you were reaching for is a
security tool. It shipped a command name whose unscoped twin was left sitting
unregistered — so the documented way to run it walked users straight into the
class of supply-chain problem the tool exists to catch. That is why this
placeholder is here instead of somebody else's code.

Why this is more than a typo

The unscoped name codex-security is a real, currently-published npm package: https://www.npmjs.com/package/codex-security

Its own description reads:

Not the Codex Security CLI — use @openai/codex-security. This unscoped name
is an empty placeholder, unaffiliated with OpenAI.

with keywords: ["placeholder", "name-reservation", "typosquatting", "supply-chain"].

That package is currently a harmless placeholder someone registered defensively — but it's a third party, unaffiliated with OpenAI, and the docs are effectively instructing users to run whatever sits at that unscoped name. If it weren't squatted defensively, this would be a textbook typosquat vector: docs point at a name, someone publishes malicious code under that exact name, users copy-paste the documented command and execute it. The fix should be treated as a supply-chain hardening fix, not just a wording cleanup.

Evidence users are already hitting the bare form

Several open issues show repro commands using the undocumented-but-copied npx codex-security form (consistent with copying straight from these READMEs before a local install already put the right binary on npx's resolution path):

• Could not save the Codex Security scan: scan-manifest.json #20 — npx codex-security scan .
• bulk-scan omits the personal account when the user belongs to an organization #28 — npx codex-security bulk-scan
• scan.target.snapshotDigest: expected a non-empty string #53 — npx codex-security scan <folder> --diff origin/main --head HEAD
• Bulk-scan save fails with "scan.target.kind: must match the workbench target" on clean worktree checkouts #62 — npx codex-security bulk-scan repositories.csv --output-dir ./results --workers 1

These particular reports worked (or failed for unrelated reasons) because the user had already run npm install @openai/codex-security locally, so npx resolved codex-security from node_modules/.bin rather than the registry. The risk is specifically for a first-time / CI user following the docs verbatim with no prior local install.

Suggested fix

Replace npx codex-security with npx @openai/codex-security throughout README.md and sdk/typescript/README.md.

I've put up a draft PR as this is the first thing I ran into after reading the README for the repo.

AI Disclosure

Ran into this on my own, then updated the main README, then had Claude Code (Sonnet 5) scan the rest of the repo for other places it might occur. I also used AI to help generate the issue although I made some edits to it.