OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
refactor(examples): port custom validation to TypeScript (#792)
Kyle Brownbfac227986ce
diff --git a/.gitignore b/.gitignoreindex 9e13db875..aa6f1054e 100644--- a/.gitignore+++ b/.gitignore@@ -22,3 +22,7 @@ __pycache__/# Emitted by sdk/typescript's build:ci script./.github/scripts/check_plugin_source_compatibility.mjs/.github/scripts/test_check_plugin_source_compatibility.mjs++# Emitted by sdk/typescript's build:examples script.+/examples/custom-validation/app.mjs+/examples/custom-validation/validate.mjsdiff --git a/examples/custom-validation/README.md b/examples/custom-validation/README.mdindex 16aa0464a..571de2d87 100644--- a/examples/custom-validation/README.md+++ b/examples/custom-validation/README.md@@ -2,8 +2,9 @@This deliberately vulnerable invoice API contains only synthetic data. Do notdeploy it. The validation script starts a real loopback HTTP server, tests-cross-account access, saves the evidence, and stops the server. It needs Python-3.10 or later and no extra packages or Docker.+cross-account access, saves the evidence, and stops the server. It uses the+SDK's supported Node.js version (including 22.13) and TypeScript compiler, with no+extra packages or Docker.From the repository root, build the CLI and run the demo:@@ -14,8 +15,16 @@ node examples/custom-validation/run.mjs```The runner uses your existing Codex Security sign-in or API key. It copies the-fixture to a temporary directory and prints the scan output path. Extra CLI-options can be appended, for example `--model gpt-5.6-terra --effort high`.+TypeScript fixture to a temporary directory, compiles it to JavaScript, and+prints the scan output path. Extra CLI options can be appended, for example+`--model gpt-5.6-terra --effort high`.++To run just the HTTP proof without a scan:++```bash+pnpm --dir sdk/typescript run build:examples+node examples/custom-validation/validate.mjs --output reports/http-proof.json+```Look for these files in the printed scan directory:@@ -31,4 +40,4 @@ cannot complete; it does not fall back to the default validation workflow.Adapt [validation.md](validation.md) for your own setup, tests, and cleanup.For a Docker-based project, the same prompt can run your existing compose or-test script instead of `validate.py`.+test script instead of `validate.mjs`.diff --git a/examples/custom-validation/app.mts b/examples/custom-validation/app.mtsnew file mode 100644index 000000000..478d252a6--- /dev/null+++ b/examples/custom-validation/app.mts@@ -0,0 +1,58 @@+// Deliberately vulnerable local fixture. Do not deploy this application.+import { once } from "node:events";+import { createServer as createHttpServer, type Server } from "node:http";+import type { AddressInfo } from "node:net";+import { pathToFileURL } from "node:url";++// These identities, tokens, and records are synthetic demo data.+const tokens = new Map([+ ["demo-alice", "alice"],+ ["demo-bob", "bob"],+]);+type Invoice = { id: string; owner: string; amount: number };+const invoices = new Map<string, Invoice>([+ ["1001", { id: "1001", owner: "alice", amount: 25 }],+ ["1002", { id: "1002", owner: "bob", amount: 80 }],+]);++export async function createServer(): Promise<Server> {+ const server = createHttpServer((request, response) => {+ function reply(status: number, body: Invoice | { error: string }): void {+ const encoded = JSON.stringify(body);+ response.writeHead(status, {+ "Content-Type": "application/json",+ "Content-Length": Buffer.byteLength(encoded),+ });+ response.end(encoded);+ }++ if (request.method !== "GET") {+ response.writeHead(501).end();+ return;+ }+ const authorization = request.headers.authorization ?? "";+ const token = authorization.startsWith("Bearer ")+ ? authorization.slice("Bearer ".length)+ : authorization;+ const user = tokens.get(token);+ if (user === undefined) return reply(401, { error: "unauthorized" });+ const path = request.url ?? "";+ if (!path.startsWith("/invoices/"))+ return reply(404, { error: "not found" });+ const invoice = invoices.get(path.slice("/invoices/".length));+ if (invoice === undefined) return reply(404, { error: "not found" });+ // BUG: authentication does not establish ownership of this invoice.+ reply(200, invoice);+ });+ server.listen(0, "127.0.0.1");+ await once(server, "listening");+ return server;+}++if (+ process.argv[1] &&+ import.meta.url === pathToFileURL(process.argv[1]).href+) {+ const server = await createServer();+ console.log(`http://127.0.0.1:${(server.address() as AddressInfo).port}`);+}diff --git a/examples/custom-validation/app.py b/examples/custom-validation/app.pydeleted file mode 100644index b9267bdc5..000000000--- a/examples/custom-validation/app.py+++ /dev/null@@ -1,48 +0,0 @@-"""Deliberately vulnerable local fixture. Do not deploy this application."""--import json-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer---# These identities, tokens, and records are synthetic demo data.-TOKENS = {"demo-alice": "alice", "demo-bob": "bob"}-INVOICES = {- "1001": {"id": "1001", "owner": "alice", "amount": 25},- "1002": {"id": "1002", "owner": "bob", "amount": 80},-}---class InvoiceHandler(BaseHTTPRequestHandler):- def reply(self, status, body):- encoded = json.dumps(body).encode()- self.send_response(status)- self.send_header("Content-Type", "application/json")- self.send_header("Content-Length", str(len(encoded)))- self.end_headers()- self.wfile.write(encoded)-- def do_GET(self):- token = self.headers.get("Authorization", "").removeprefix("Bearer ")- user = TOKENS.get(token)- if user is None:- return self.reply(401, {"error": "unauthorized"})- if not self.path.startswith("/invoices/"):- return self.reply(404, {"error": "not found"})- invoice = INVOICES.get(self.path.removeprefix("/invoices/"))- if invoice is None:- return self.reply(404, {"error": "not found"})- # BUG: authentication does not establish ownership of this invoice.- return self.reply(200, invoice)-- def log_message(self, format, *args):- pass---def create_server():- return ThreadingHTTPServer(("127.0.0.1", 0), InvoiceHandler)---if __name__ == "__main__":- with create_server() as server:- print(f"http://127.0.0.1:{server.server_port}", flush=True)- server.serve_forever()diff --git a/examples/custom-validation/run.mjs b/examples/custom-validation/run.mjsindex fa790e04a..ee4e7aa41 100644--- a/examples/custom-validation/run.mjs+++ b/examples/custom-validation/run.mjs@@ -8,10 +8,21 @@ const root = await mkdtemp(join(tmpdir(), "codex-security-validation-demo-"));const target = join(root, "target");const output = join(root, "scan");await mkdir(target);-for (const name of ["app.py", "validate.py"]) {+for (const name of ["app.mts", "validate.mts"]) {await copyFile(new URL(name, import.meta.url), join(target, name));}+const build = spawnSync(+ process.execPath,+ ["--run", "build:examples", "--", "--outDir", target],+ {+ cwd: fileURLToPath(new URL("../../sdk/typescript", import.meta.url)),+ stdio: "inherit",+ },+);+if (build.error) throw build.error;+if (build.status !== 0) process.exit(build.status ?? 1);+console.log(`Demo target: ${target}\nScan output: ${output}`);const child = spawnSync(process.execPath,@@ -22,7 +33,7 @@ const child = spawnSync("scan",target,"--path",- "app.py",+ "app.mts","--scan-prompt-file",fileURLToPath(new URL("scan.md", import.meta.url)),"--validation-prompt-file",diff --git a/examples/custom-validation/scan.md b/examples/custom-validation/scan.mdindex 0f6e4ff6c..eb7accbf7 100644--- a/examples/custom-validation/scan.md+++ b/examples/custom-validation/scan.md@@ -1,4 +1,4 @@-Review invoice ownership checks in `app.py`. An authenticated account must not+Review invoice ownership checks in `app.mts`. An authenticated account must notread another account's invoice. The fixed tokens and records are synthetic test-data, not production credentials. `validate.py` is a test harness, not an+data, not production credentials. `validate.mts` is a test harness, not anapplication endpoint. Keep discovery source-only.diff --git a/examples/custom-validation/validate.mts b/examples/custom-validation/validate.mtsnew file mode 100644index 000000000..68bfc378d--- /dev/null+++ b/examples/custom-validation/validate.mts@@ -0,0 +1,79 @@+// Exercise the fixture over real HTTP and save the observed evidence.+import assert from "node:assert/strict";+import { mkdir, writeFile } from "node:fs/promises";+import type { AddressInfo } from "node:net";+import { dirname } from "node:path";+import { parseArgs } from "node:util";+import { createServer } from "./app.mjs";++type HttpResult = {+ status: number;+ body: { id?: string; owner?: string; amount?: number; error?: string };+};++async function main(): Promise<number> {+ let output: string;+ try {+ const { values } = parseArgs({+ options: {+ output: { type: "string" },+ help: { type: "boolean", short: "h" },+ },+ });+ if (values.help) {+ console.log("Usage: node validate.mjs --output PATH");+ return 0;+ }+ if (values.output === undefined) throw new Error("--output is required");+ output = values.output;+ } catch (error) {+ console.error((error as Error).message);+ return 2;+ }++ const server = await createServer();+ const baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;+ async function get(invoice: string, token?: string): Promise<HttpResult> {+ const response = await fetch(`${baseUrl}/invoices/${invoice}`, {+ headers: token === undefined ? {} : { Authorization: `Bearer ${token}` },+ signal: AbortSignal.timeout(5_000),+ });+ return {+ status: response.status,+ body: (await response.json()) as HttpResult["body"],+ };+ }++ let evidence: {+ anonymous: HttpResult;+ own_invoice: HttpResult;+ other_invoice: HttpResult;+ cross_account_read: boolean;+ };+ try {+ const anonymous = await get("1002");+ const own_invoice = await get("1001", "demo-alice");+ const other_invoice = await get("1002", "demo-alice");+ assert.equal(anonymous.status, 401, "Authentication control failed");+ assert.equal(own_invoice.status, 200, "Own-account control failed");+ evidence = {+ anonymous,+ own_invoice,+ other_invoice,+ cross_account_read:+ other_invoice.status === 200 && other_invoice.body.owner === "bob",+ };+ } finally {+ await new Promise<void>((resolve, reject) => {+ server.close((error) => (error ? reject(error) : resolve()));+ });+ }++ const proof = { ...evidence, server_stopped: true };+ await mkdir(dirname(output), { recursive: true });+ await writeFile(output, `${JSON.stringify(proof, null, 2)}\n`, "utf8");+ console.log(JSON.stringify(proof));+ return 0;+}++process.exitCode = await main();diff --git a/examples/custom-validation/validate.py b/examples/custom-validation/validate.pydeleted file mode 100644index c7430a689..000000000--- a/examples/custom-validation/validate.py+++ /dev/null@@ -1,60 +0,0 @@-"""Exercise the fixture over real HTTP and save the observed evidence."""--import argparse-import json-import runpy-from http.client import HTTPConnection-from pathlib import Path-from threading import Thread---def main():- parser = argparse.ArgumentParser()- parser.add_argument("--output", required=True, type=Path)- args = parser.parse_args()-- app = runpy.run_path(str(Path(__file__).with_name("app.py")))- server = app["create_server"]()- worker = Thread(target=server.serve_forever, daemon=True)- worker.start()-- def get(invoice, token=None):- connection = HTTPConnection("127.0.0.1", server.server_port, timeout=5)- try:- headers = (- {} if token is None else {"Authorization": f"Bearer {token}"}- )- connection.request("GET", f"/invoices/{invoice}", headers=headers)- response = connection.getresponse()- return {"status": response.status, "body": json.loads(response.read())}- finally:- connection.close()-- try:- anonymous = get("1002")- own_invoice = get("1001", "demo-alice")- other_invoice = get("1002", "demo-alice")- assert anonymous["status"] == 401, "Authentication control failed"- assert own_invoice["status"] == 200, "Own-account control failed"- evidence = {- "anonymous": anonymous,- "own_invoice": own_invoice,- "other_invoice": other_invoice,- "cross_account_read": (- other_invoice["status"] == 200- and other_invoice["body"].get("owner") == "bob"- ),- }- finally:- server.shutdown()- server.server_close()- worker.join()-- evidence["server_stopped"] = True- args.output.parent.mkdir(parents=True, exist_ok=True)- args.output.write_text(json.dumps(evidence, indent=2) + "\n", encoding="utf-8")- print(json.dumps(evidence))---if __name__ == "__main__":- main()diff --git a/examples/custom-validation/validation.md b/examples/custom-validation/validation.mdindex 0aec3c4a4..ba2aec678 100644--- a/examples/custom-validation/validation.md+++ b/examples/custom-validation/validation.md@@ -1,9 +1,9 @@Validate the invoice-ownership finding against this local fixture.-1. Use the configured Python interpreter to run `validate.py` from the supplied+1. Run `node validate.mjs` from the suppliedrepository root. Pass `--output` with the absolute path to`artifacts/custom-validation/http-proof.json` inside this scan's directory.- Set `PYTHONDONTWRITEBYTECODE=1` so the target remains unchanged.+ The runner has already compiled the TypeScript fixture to JavaScript.2. The script starts a server on an ephemeral `127.0.0.1` port, makes three HTTPrequests using synthetic identities, and shuts the server down. This localserver is the only authorized test target. Do not install packages or contactdiff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex fac6c0ff7..206344b15 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -50,10 +50,11 @@"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","build": "node --run clean && tsc -p tsconfig.build.json && node scripts/build-dashboard.mjs","build:ci": "tsc -p tsconfig.ci.json",+ "build:examples": "tsc -p tsconfig.examples.json","build:plugin": "node scripts/build-plugin.mjs","check:plugin-source": "node scripts/check-plugin-source.mjs","check:package": "node scripts/check-package.mjs",- "format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json,md}\" \"../../.github/scripts/*.mts\"",+ "format": "prettier --check --ignore-path .gitignore --ignore-path .prettierignore \"**/*.{cjs,mjs,js,ts,mts,tsx,json,md}\" \"../../.github/scripts/*.mts\" \"../../examples/custom-validation/*.{mts,md}\"","generate:models": "node scripts/generate-models.cjs","generate:models:check": "node scripts/generate-models.cjs --check","lint": "tsc --noEmit",diff --git a/sdk/typescript/tests-ts/custom-validation-example.test.ts b/sdk/typescript/tests-ts/custom-validation-example.test.tsnew file mode 100644index 000000000..d2550b77b--- /dev/null+++ b/sdk/typescript/tests-ts/custom-validation-example.test.ts@@ -0,0 +1,49 @@+import { mkdtemp, readFile, rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { fileURLToPath } from "node:url";+import { expect, test } from "bun:test";+import { runCommand } from "./support/shell.js";++test("compiled validation example saves HTTP proof and exits after server cleanup", async () => {+ const source = await mkdtemp(join(tmpdir(), "custom-validation-example-"));+ const output = await mkdtemp(join(tmpdir(), "custom-validation-proof-"));+ const packageRoot = fileURLToPath(new URL("..", import.meta.url));+ try {+ const build = await runCommand(+ "node",+ ["--run", "build:examples", "--", "--outDir", source],+ { cwd: packageRoot, timeout: 30_000 },+ );+ expect(build.status, build.stdout + build.stderr).toBe(0);+ const proofPath = join(output, "artifacts", "http-proof.json");+ const result = await runCommand(+ "node",+ [join(source, "validate.mjs"), "--output", proofPath],+ { timeout: 30_000 },+ );+ // A server left listening would prevent this process from exiting normally.+ expect(result.status, result.stderr).toBe(0);+ expect(result.stderr).toBe("");+ const proof = {+ anonymous: { status: 401, body: { error: "unauthorized" } },+ own_invoice: {+ status: 200,+ body: { id: "1001", owner: "alice", amount: 25 },+ },+ other_invoice: {+ status: 200,+ body: { id: "1002", owner: "bob", amount: 80 },+ },+ cross_account_read: true,+ server_stopped: true,+ };+ expect(JSON.parse(result.stdout)).toEqual(proof);+ expect(JSON.parse(await readFile(proofPath, "utf8"))).toEqual(proof);+ } finally {+ await Promise.all([+ rm(source, { recursive: true, force: true }),+ rm(output, { recursive: true, force: true }),+ ]);+ }+});diff --git a/sdk/typescript/tsconfig.examples.json b/sdk/typescript/tsconfig.examples.jsonnew file mode 100644index 000000000..eabb66409--- /dev/null+++ b/sdk/typescript/tsconfig.examples.json@@ -0,0 +1,7 @@+{+ "extends": "./tsconfig.ci.json",+ "include": ["../../examples/custom-validation/*.mts"],+ "compilerOptions": {+ "rootDir": "../../examples/custom-validation"+ }+}diff --git a/sdk/typescript/tsconfig.json b/sdk/typescript/tsconfig.jsonindex 6738b4dcf..1b08f5158 100644--- a/sdk/typescript/tsconfig.json+++ b/sdk/typescript/tsconfig.json@@ -6,6 +6,7 @@"dashboard/**/*.tsx","tests-ts/**/*.ts","../../.github/scripts/*.mts",+ "../../examples/custom-validation/*.mts","scripts/compare-test-reports.mts","scripts/smoke-findings-service.ts","scripts/fixtures/findings-service-sqlite.ts",