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

fix(auth): document SSH login fallback (#1294)

mldangelo-oai7beb1ac4acd8
diff --git a/README.md b/README.md
index 20138ae7f..0390ebdc9 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,10 @@ npx @openai/codex-security login
npx @openai/codex-security scan /path/to/directory
```
+On remote or headless machines, use `login --device-auth` if your workspace
+allows it. If device auth is disabled,
+[sign in over SSH](sdk/typescript/README.md#remote-login-with-ssh-forwarding).
+
For CI, set `OPENAI_API_KEY` instead of signing in.
## Generate SECURITY.md
diff --git a/docker/README.md b/docker/README.md
index 2dc89a0b6..45d8810d6 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -131,7 +131,12 @@ docker compose -f compose.runner.yaml pull
docker compose -f compose.runner.yaml run --rm codex-security login --device-auth
```
-For unattended use, provide `OPENAI_API_KEY` or `CODEX_API_KEY` instead of login.
+The `login --device-auth` command above signs the runner in with ChatGPT and
+requires device auth to be enabled in your workspace. If device auth is
+disabled, skip that command and export `OPENAI_API_KEY` or `CODEX_API_KEY` in
+your host shell. Compose passes the key to the runner. Use API keys for
+unattended runs too.
+
Git authentication uses the existing `GH_TOKEN`/`GITHUB_TOKEN` and optional
`CODEX_SECURITY_GIT_HOST` settings. Pass only the credentials the runner needs;
the findings service's embedding credentials are configured separately.
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 517fc5782..481bcef3a 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -248,12 +248,14 @@ npx @openai/codex-security login
npx @openai/codex-security scan .
```
-Use device authentication on remote or headless machines:
+On remote or headless machines, use device auth if your workspace allows it:
```bash
npx @openai/codex-security login --device-auth
```
+If device auth is disabled, [sign in over SSH](#remote-login-with-ssh-forwarding).
+
For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin:
```bash
@@ -264,6 +266,28 @@ Environment API keys apply to the current command; only `login --with-api-key`
saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
Access-token environment variables are not scan API keys.
+### Remote login with SSH forwarding
+
+Use an SSH tunnel when device auth is disabled.
+
+On your local machine, replace `user@remote-host` with your SSH address and run:
+
+```bash
+ssh -L 1455:localhost:1455 user@remote-host
+```
+
+Run login in that SSH session:
+
+```bash
+npx @openai/codex-security login
+```
+
+Open the sign-in URL in your local browser. Keep SSH connected until login finishes.
+
+See the [authentication guide](https://learn.chatgpt.com/docs/auth?surface=cli#cli-fallback-forward-the-localhost-callback-over-ssh).
+
+### Native command authentication and other providers
+
SDK callers can select native command authentication through
`codexOverrides.model_providers.<id>.auth` and `model_provider` (including a
selected `profile`). Scans, comparisons, and deduplication reviews preserve
@@ -2794,6 +2818,7 @@ runtime dependencies.
## Containerized bulk scans
Create `repositories.csv` as described under [Bulk scans](#bulk-scans).
+Use device login only if your workspace allows it.
With a published image, run from the Codex Security repository root:
```bash
diff --git a/sdk/typescript/src/auth.ts b/sdk/typescript/src/auth.ts
index 749345984..5d745b161 100644
--- a/sdk/typescript/src/auth.ts
+++ b/sdk/typescript/src/auth.ts
@@ -310,9 +310,10 @@ export const CODEX_AUTH_CONFIG_KEYS = [
/** @internal Shared login recovery guidance for model commands. */
export const NO_CREDENTIALS_MESSAGE =
- "No credentials were found. Run 'codex-security login', use " +
- "'codex-security login --device-auth' on a remote or headless machine, or set " +
- "OPENAI_API_KEY or CODEX_API_KEY for CI.";
+ "No credentials were found. Run 'codex-security login'. On a remote or headless " +
+ "machine, use 'codex-security login --device-auth' if your workspace allows it. " +
+ "If device auth is disabled, see 'codex-security login --help' for browser login over SSH. " +
+ "For CI, set OPENAI_API_KEY or CODEX_API_KEY.";
function preferredAuthUrl(value: string): string | null {
for (const match of plainTerminalText(value).matchAll(
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index c8252033b..9cbb27751 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -5364,6 +5364,16 @@ export async function main(
})
.command("login", {
description: "Sign in with ChatGPT or store credentials.",
+ hint:
+ "For remote login, use --device-auth if your workspace allows it.\n" +
+ "If device auth is disabled, sign in over SSH:\n" +
+ " On your local machine (replace user@remote):\n" +
+ " ssh -L 1455:localhost:1455 user@remote\n" +
+ " In that SSH session:\n" +
+ " codex-security login\n" +
+ " Open the sign-in URL in your local browser.\n" +
+ " Keep SSH connected until login finishes.\n" +
+ "Docs: https://learn.chatgpt.com/docs/auth?surface=cli#cli-fallback-forward-the-localhost-callback-over-ssh",
destructive: true,
mcp: false,
args: z.object({
@@ -5376,7 +5386,7 @@ export async function main(
deviceAuth: z
.boolean()
.default(false)
- .describe("Use device-code authentication."),
+ .describe("Use device auth if your workspace allows it."),
withApiKey: z
.boolean()
.default(false)
diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.ts
index b6e08334d..1e56330ad 100644
--- a/sdk/typescript/tests-ts/cli-help.test.ts
+++ b/sdk/typescript/tests-ts/cli-help.test.ts
@@ -225,6 +225,7 @@ describe("CLI help", () => {
for (const command of [
[],
["scan"],
+ ["login"],
["publish", "scan"],
["scan", "import"],
]) {
@@ -246,6 +247,9 @@ describe("CLI help", () => {
}
const text = await help(["scan", "--help"], columns);
expect(text).toMatch(/^ codex-security scan \.(?:\s+#.*)?$/mu);
+ const login = await help(["login", "--help"], columns);
+ expect(login).toMatch(/^ ssh -L 1455:localhost:1455 user@remote$/mu);
+ expect(login).toMatch(/^ codex-security login$/mu);
},
);
});