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(scans): explain connected repository review workflows (#1553)

mldangelo-oai2b68f471bab1
diff --git a/README.md b/README.md
index 18d7776e5..d95f8be41 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,11 @@ cs scan . --mode deep
Use `cs --help` to browse commands, or `cs scan --help`
for scan options, cost limits, and patching after a scan.
+For an application spread across repositories, see
+[review one system across repositories](sdk/typescript/docs/cli.md#review-one-system-across-repositories).
+Use [bulk scans](sdk/typescript/docs/cli.md#bulk-scans) for independent repository
+reviews in one resumable campaign.
+
## TypeScript SDK
Install the package locally in your TypeScript project:
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index f54fa6b98..28c9750c2 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -665,8 +665,71 @@ a larger total or `undefined`. It runs once per limit without blocking the scan.
Late responses after cancellation/completion are ignored; invalid increases or
save failures keep the existing limit. `onCost(cost, maxCostUsd)` reports changes.
+## Review one system across repositories
+
+Use a single directory/path scan when an application spans repositories and you
+want Codex to follow relationships between their source files. Put the checkouts
+under one parent directory; that parent does not need to be a Git repository.
+Select the relevant paths beneath it and supply the shared architecture and
+reporting instructions explicitly:
+
+```text
+workspace/
+├── application/
+│ ├── api/ # Git checkout
+│ ├── web/ # Git checkout
+│ └── shared/ # Git checkout
+├── context/
+│ ├── architecture.md
+│ └── scan-instructions.md
+└── results/
+```
+
+From `workspace/`, run:
+
+```bash
+codex-security scan ./application \
+ --mode deep \
+ --path api/src --path web/src --path shared/src \
+ --knowledge-base ./context/architecture.md \
+ --scan-prompt-file ./context/scan-instructions.md \
+ --output-dir ./results/system-review
+```
+
+Scope paths are relative to `application/`. Context and output paths in this
+example are relative to the working directory. Keep results outside the scanned
+directory and any enclosing Git worktree. You do not need to add `AGENTS.md` or
+`SECURITY.md` to each checkout to pass these documents.
+
+Include both sides of a boundary you want reviewed, such as an API caller and
+its authorization implementation. Architecture documents can explain deployment
+facts and trust boundaries, but cannot replace missing source evidence. Identify
+excluded or unavailable services in the context so their dependencies remain
+explicit coverage limitations. Distinguish source that supports an investigation
+from locations where you want findings reported.
+
+Record each checkout's commit and local changes before scanning, and keep the
+checkouts unchanged while a scan or resume is active. A non-Git parent is recorded
+as one directory snapshot, rather than one pinned revision per child repository.
+Use the saved scan ID when inspecting results and logs:
+
+```bash
+codex-security scans show SCAN_ID
+codex-security scans logs SCAN_ID
+```
+
+See [scan history and reruns](#scan-history-and-reruns) for the distinction between
+continuing an interrupted scan and starting a new run. Neither approach proves
+that every possible cross-service path was reviewed; inspect the reported
+coverage and unresolved questions alongside findings.
+
## Bulk scans
+Bulk scans run independent repository reviews in one resumable campaign. Shared
+knowledge-base documents give each review application context; they do not make
+the campaign a joint source review across repositories. For that workflow, use
+[one system scan](#review-one-system-across-repositories).
+
Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
selection. It lists repositories pushed in the last 90 days, excluding forks
and archives, asks for output, and saves the selection as `repositories.csv`.