Install
npm install --global @openai/codex-securityWho it's for
If you need to locate security problems quickly in a real codebase — taking over an unfamiliar repository, giving a pre-release version a once-over, or gating a commit in CI — then this command-line tool is worth installing. It is aimed at people who have a terminal, can run a global npm install, and are willing to confirm the scan scope themselves, rather than GUI users who just want to click a button. It takes on the two halves of the job, "find" and "verify": it flags suspicious spots and gives evidence that traces back to the source files, instead of changing code on your behalf by default.
Three common prerequisites: you have repository code you can read; you are willing to let the tool read those files locally; and you have basic trust in the boundary that "the scan only reads code, it does not change code". For people doing code review, supply chain security checks, or compliance spot checks, it serves as a first coarse filter and saves effort compared with reading everything by hand.
Your first attempt in 3 minutes
Check the environment first. The official requirement is Node.js 22.13.0+ (within the 22.x branch only) or Node.js 24.x / 26.x, plus Python 3.10+; Python 3.10 also needs tomli installed separately. When the versions are not met, the command fails at startup.
Installation goes through the one path the official docs recommend: install this npm package globally, then complete a login.
npm install --global @openai/codex-security
cs login
Once it is installed, both cs and codex-security land in npm's global executable directory, and that directory must be on your PATH — otherwise the terminal reports "command not found" rather than an installation failure. Running cs prints the usage instructions, which means the install worked.
For the first run, pick a read-only, reversible action: keep the scope on an explicit directory and scan it once, rather than jumping straight into a deep scan of the whole repo.
cs scan . --path src
This step reads the files under the specified directory and sends their content off the machine to call the model for analysis — it is an operation with an external side effect, so confirm three things before running it: which directory to scan, whether the source code may leave the machine this time, and that the scan will not modify repository files. Treat the output as "leads to be verified", not as a final conclusion.
To have it triggered inside an agent on your behalf, open this repo in a Codex session with the Codex Security plugin enabled and make a request with a defined boundary: have it scan the repo, focus only on the authentication and authorization parts, and return the saved report, the source-code evidence, and a description of the coverage limits. There are three observable success signals: the command exits normally and prints a report summary; every finding points to a specific file and location; and the reply carries the coverage-limits note instead of a vague "scan complete".
Use cases
Case one: narrow the scope to a few directories, or look at a single change. A team has just merged a feature branch and wants to confirm that the authentication-related code has introduced no problems, so use cs scan . --path src --path tests to keep the scope inside the source and test directories; you can also use cs scan . --diff origin/main to look only at the committed changes relative to the baseline branch. The former returns all findings inside the directories, the latter returns the findings brought by this change — the report is itself a checklist you can take straight into a discussion.
Case two: add an automatic gate in CI. The way to do it is to put OPENAI_API_KEY or CODEX_API_KEY into the environment of the scanning process, then run the same cs scan . in the CI job. If the machine is remote or headless, you can instead use cs login --device-auth (provided the workspace allows it), or complete the login by following the SSH forwarding login section in the official SDK docs: https://github.com/openai/codex-security/blob/main/sdk/typescript/README.md#remote-login-with-ssh-forwarding. The success signal is the full report text appearing in the CI log, and subsequent steps being interrupted or allowed through as expected.
Boundaries of use
It reads code, and it also depends on an account and the network: having it installed locally does not mean a scan can run, the scan itself is still an external call, and the results are influenced by model judgment, so two scans of the same code may not yield the same findings. That makes it better as a source of leads than as a source of facts.
On CI or remote machines, without an API Key and without completing a device-auth or SSH login, the scan will not start — that is a hard prerequisite, not an option. In addition, some cybersecurity-oriented requests and protected findings require Trusted Access for Cyber approval; without it the related conclusions are missing or restricted — read the "coverage limits" section of the report carefully, because it states what this scan did not actually cover.
It does not change code by default, but once it is used with an agent that "fixes it while it is at it", it produces file writes and commit actions. Any operation that makes the tool modify the repo, create a branch, or push to a remote should be confirmed separately before execution, and the workspace should be kept clean.