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
docs(examples): add Azure Pipelines Bedrock scan example (#906)
mldangelo-oai86f6afcfd256
diff --git a/examples/README.md b/examples/README.mdindex 2ffc05cb5..afd700875 100644--- a/examples/README.md+++ b/examples/README.md@@ -22,6 +22,10 @@ Examples and templates for using Codex Security:validation script against a deliberately vulnerable API using synthetic data.Follow the demo's setup instructions, and do not deploy the example app.+- [Azure Pipelines with Amazon Bedrock](azure-pipelines/README.md): centrally run+ manual full or committed-diff scans against Azure Repos, with OIDC credentials,+ report artifacts, and optional native SARIF publishing.+## npm packageThis top-level `examples/` directory is available in the repository only; it isdiff --git a/examples/azure-pipelines/README.md b/examples/azure-pipelines/README.mdnew file mode 100644index 000000000..ce2c36fa4--- /dev/null+++ b/examples/azure-pipelines/README.md@@ -0,0 +1,106 @@+# Azure Pipelines with Amazon Bedrock++This example runs Codex Security from a centrally owned Azure Pipelines YAML+file against a configured Azure Repos Git repository. It supports manual full+and committed-diff scans, short-lived AWS credentials through OIDC, report+artifacts, and optional SARIF publishing to the target repository's Advanced+Security view. No Codex Security runtime changes or custom extension are needed.++It targets Azure DevOps Services and Microsoft-hosted Linux agents. It does not+enroll repositories, create branch policies, or automatically validate PRs.+Use a trusted tooling repository for the pipeline definition; the target+repository does not need its own pipeline file.++## Setup++1. Copy [`azure-pipelines.yml`](azure-pipelines.yml) into the tooling repository.+ Set `resources.repositories.target.name` to the approved `Project/Repository`+ and adjust the default `targetRef`. Keep the repository name fixed in reviewed+ YAML instead of accepting arbitrary scan targets at queue time.+2. Install the current [AWS Toolkit for Azure DevOps](https://github.com/aws/aws-toolkit-azure-devops/releases)+ extension in your organization. Create an AWS service connection named+ `codex-security-bedrock` with **Use OIDC** and an AWS role ARN; leave access+ keys unset. Follow the [AWS OIDC setup guide](https://aws.amazon.com/blogs/modernizing-with-aws/how-to-federate-into-aws-from-azure-devops-using-openid-connect/).+ Restrict the role trust to the service connection's actual issuer, audience,+ and subject. Authorize only this pipeline to use the connection.+3. Set `awsRegion` and `bedrockModelId` to an available, approved Bedrock model or+ inference profile. Grant the role only the required Bedrock invocation+ permissions for those resources. The requested AWS session is one hour,+ matching the job timeout; configure the role to allow that duration.+4. Create a pipeline pointing at the copied YAML. Grant its project build+ service identity read access to the target repository and authorize the+ repository resource. Cross-project checkout needs explicit access in the+ target project; do not disable project-scoped job authorization to work around+ a missing grant. See [multi-repository checkout permissions](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/multi-repo-checkout?view=azure-devops).+5. Keep `publishToAdvancedSecurity: false` for artifact-only runs. To enable the+ native findings view, enable the required GitHub Code Security / Advanced+ Security entitlement on the **target** repository and grant the pipeline+ identity permission to publish its results. Then opt in when queuing a run.+ See [third-party SARIF publishing](https://learn.microsoft.com/en-us/azure/devops/repos/security/github-advanced-security-code-scanning-third-party?view=azure-devops).++The YAML pins the CLI, Node, and Python versions and uses current task majors.+Azure Pipelines resolves compatible task updates within those majors. Review+the pinned versions when adopting or upgrading the example.++## Run a scan++Choose **Run pipeline** from the trusted tooling branch, then set:++| Parameter | Meaning |+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |+| `targetRef` | Target branch or tag, defaulting to `refs/heads/main`. |+| `scanMode` | `full` for a baseline, or `diff` for changes relative to a base revision. |+| `baseRevision` | Used only for `diff`; defaults to `HEAD^` (the preceding commit). Prefer an exact base commit SHA for reproducibility. |+| `failOnSeverity` | `none` is report-only; select a severity to fail on findings at or above it. |+| `publishToAdvancedSecurity` | Opt in to native SARIF publishing after completing its setup. |++Start with a full scan. For a later committed-diff scan, select the target branch+and a base revision present in that repository's history. The checkout fetches+full history; Codex Security resolves the diff against the checked-out commit.+This scans committed changes, not an automatically discovered PR.++The optional publisher uses the `target` repository resource metadata, not the+tooling repository's build metadata. Keep its alias and+`advancedsecurity.publish.repository` in sync when adapting the YAML. This is+Microsoft's [explicit multi-repository publishing mechanism](https://learn.microsoft.com/en-us/azure/devops/release-notes/2025/sprint-253-update#multi-repository-publishing-scenarios-supported-for-github-advanced-security-for-azure-devops).+Full and diff results use separate categories so a partial diff does not replace+the full-scan baseline. A diff result is still a snapshot of that diff, not a+complete repository inventory; use full scans to track the baseline over time.++## Results and failures++The `codex-security` pipeline artifact contains `result.json`, available+`report.md`, `coverage.json`, and `findings.json`, plus `results.sarif` after a+successful export. Check the JSON/report for findings, coverage, runtime, and+usage; missing or incomplete coverage is not a clean scan.++| Scan exit | Pipeline behavior |+| ------------- | ---------------------------------------------------------------------------------------------- |+| `0` | Completed scan; export SARIF and retain reports. |+| `1` | Severity policy failed; still export SARIF and retain reports, but keep the job failed. |+| Other nonzero | Scan failed or was incomplete; retain available reports without exporting or publishing SARIF. |++An export or publishing failure also fails the job. Cancellation skips the+post-scan steps, so artifacts are not guaranteed for canceled runs. Native+publishing waits for processing; verify the target repository and commit in the+first live run. Local validation cannot prove your organization's OIDC trust,+permissions, model access, or SARIF ingestion.++## Trust and rollout boundaries++- Restrict who can edit or queue this privileged pipeline and use its AWS service+ connection. Treat scanned code and model output as untrusted. OIDC avoids+ long-lived keys; it does not make running untrusted code with credentials safe.+- The CLI is installed before target checkout, outside the repository, with npm+ lifecycle scripts disabled. Checkout does not persist its credential. The AWS+ task supplies temporary credentials only to the scan step; no PAT or Azure+ access token is explicitly passed to the CLI.+- Reports can contain source excerpts and vulnerability details. Restrict artifact+ access and configure your project's pipeline-run retention policy. The example+ retains selected reports, not raw scan state, transcripts, or authentication+ files.+- For automatic Azure Repos PR checks, configure a target-branch **build validation+ policy** and a PR-aware checkout/pipeline design. YAML `pr:` triggers do not+ enable Azure Repos PR validation. Attaching this manual pipeline unchanged to+ a policy would still scan its configured target ref, not necessarily the PR.+ See [Azure Repos PR triggers](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/azure-repos-git?view=azure-devops#pr-triggers).diff --git a/examples/azure-pipelines/azure-pipelines.yml b/examples/azure-pipelines/azure-pipelines.ymlnew file mode 100644index 000000000..71d085dad--- /dev/null+++ b/examples/azure-pipelines/azure-pipelines.yml@@ -0,0 +1,163 @@+# Setup and permissions: examples/azure-pipelines/README.md+trigger: none++parameters:+ - name: targetRef+ type: string+ default: refs/heads/main+ - name: scanMode+ type: string+ default: full+ values: [full, diff]+ - name: baseRevision+ type: string+ default: HEAD^+ - name: failOnSeverity+ type: string+ default: none+ values: [none, low, medium, high, critical]+ - name: publishToAdvancedSecurity+ type: boolean+ default: false++resources:+ repositories:+ - repository: target+ type: git+ name: ExampleProject/example-app # Replace with the approved project/repository.+ ref: ${{ parameters.targetRef }}+ trigger: none++variables:+ codexSecurityVersion: "0.1.27"+ awsServiceConnection: codex-security-bedrock+ awsRegion: us-east-1+ bedrockModelId: REPLACE_WITH_APPROVED_MODEL_ID+ aws.rolecredential.maxduration: "3600"+ targetDirectory: $(Pipeline.Workspace)/s/scan-target+ scanDirectory: $(Agent.TempDirectory)/codex-security/scan+ reportDirectory: $(Agent.TempDirectory)/codex-security/reports+ scanExitCode: not-started+ sarifReady: "false"++jobs:+ - job: scan+ displayName: Codex Security+ timeoutInMinutes: 60+ pool:+ vmImage: ubuntu-24.04+ variables:+ # Attribute alerts to the scanned repository, not the pipeline's repository.+ advancedsecurity.publish.repository: $[ convertToJson(resources.repositories['target']) ]+ steps:+ - task: UseNode@1+ inputs:+ version: "24.21.0"+ - task: UsePythonVersion@0+ inputs:+ versionSpec: "3.14.7"++ # Install before checkout so repository npm configuration is not consulted.+ - task: Bash@3+ name: installCli+ displayName: Install Codex Security+ inputs:+ targetType: inline+ workingDirectory: $(Agent.TempDirectory)+ script: |+ set -euo pipefail+ npm install --prefix "$CLI_DIRECTORY" --ignore-scripts --no-audit --no-fund \+ --registry=https://registry.npmjs.org/ \+ "@openai/codex-security@$CODEX_SECURITY_VERSION"+ printf '##vso[task.prependpath]%s\n' "$CLI_DIRECTORY/node_modules/.bin"+ env:+ CLI_DIRECTORY: $(Agent.TempDirectory)/codex-security-cli+ CODEX_SECURITY_VERSION: $(codexSecurityVersion)++ - checkout: target+ path: s/scan-target+ fetchDepth: 0+ persistCredentials: false++ - task: AWSShellScript@1+ name: runScan+ displayName: Scan with Bedrock OIDC credentials+ inputs:+ awsCredentials: $(awsServiceConnection)+ regionName: $(awsRegion)+ scriptType: inline+ disableAutoCwd: true+ workingDirectory: $(targetDirectory)+ inlineScript: |+ set -euo pipefail+ mkdir -p "$REPORT_DIRECTORY"+ args=(scan "$TARGET_DIRECTORY" --provider amazon-bedrock+ --model "$BEDROCK_MODEL_ID" --mode standard --effort high+ --output-dir "$SCAN_DIRECTORY" --json)+ if [[ "$SCAN_MODE" == diff ]]; then+ args+=(--diff "$BASE_REVISION")+ fi+ if [[ "$FAIL_ON_SEVERITY" != none ]]; then+ args+=(--fail-on-severity "$FAIL_ON_SEVERITY")+ fi+ status=0+ codex-security "${args[@]}" > "$REPORT_DIRECTORY/result.json" || status=$?+ printf '##vso[task.setvariable variable=scanExitCode]%s\n' "$status"+ exit "$status"+ env:+ TARGET_DIRECTORY: $(targetDirectory)+ SCAN_DIRECTORY: $(scanDirectory)+ REPORT_DIRECTORY: $(reportDirectory)+ BEDROCK_MODEL_ID: $(bedrockModelId)+ SCAN_MODE: ${{ parameters.scanMode }}+ BASE_REVISION: ${{ parameters.baseRevision }}+ FAIL_ON_SEVERITY: ${{ parameters.failOnSeverity }}++ - task: Bash@3+ name: exportSarif+ displayName: Export completed scan to SARIF+ condition: and(succeededOrFailed(), in(variables['scanExitCode'], '0', '1'))+ inputs:+ targetType: inline+ script: |+ set -euo pipefail+ codex-security export "$SCAN_DIRECTORY" --export-format sarif \+ --source-root "$TARGET_DIRECTORY" --output "$REPORT_DIRECTORY/results.sarif"+ printf '##vso[task.setvariable variable=sarifReady]true\n'+ env:+ TARGET_DIRECTORY: $(targetDirectory)+ SCAN_DIRECTORY: $(scanDirectory)+ REPORT_DIRECTORY: $(reportDirectory)++ - ${{ if parameters.publishToAdvancedSecurity }}:+ - task: AdvancedSecurity-Publish@1+ displayName: Publish SARIF to the target repository+ condition: and(succeededOrFailed(), eq(variables['sarifReady'], 'true'))+ inputs:+ SarifsInputDirectory: $(reportDirectory)+ Category: codex-security/${{ parameters.scanMode }}+ WaitForProcessing: true++ - task: Bash@3+ name: stageReports+ displayName: Collect reports without raw scan state+ condition: and(succeededOrFailed(), ne(variables['scanExitCode'], 'not-started'))+ inputs:+ targetType: inline+ script: |+ set -euo pipefail+ for report in report.md coverage.json findings.json; do+ if [[ -f "$SCAN_DIRECTORY/$report" ]]; then+ cp "$SCAN_DIRECTORY/$report" "$REPORT_DIRECTORY/$report"+ fi+ done+ env:+ SCAN_DIRECTORY: $(scanDirectory)+ REPORT_DIRECTORY: $(reportDirectory)++ - task: PublishPipelineArtifact@1+ displayName: Retain scan reports+ condition: and(succeededOrFailed(), ne(variables['scanExitCode'], 'not-started'))+ inputs:+ targetPath: $(reportDirectory)+ artifact: codex-securitydiff --git a/sdk/typescript/tests-ts/azure-pipelines-example.test.ts b/sdk/typescript/tests-ts/azure-pipelines-example.test.tsnew file mode 100644index 000000000..d1c53deb4--- /dev/null+++ b/sdk/typescript/tests-ts/azure-pipelines-example.test.ts@@ -0,0 +1,231 @@+import { spawnSync } from "node:child_process";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ readdirSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, test } from "bun:test";+import { parse } from "yaml";++interface Step {+ name?: string;+ task?: string;+ checkout?: string;+ condition?: string;+ fetchDepth?: number;+ persistCredentials?: boolean;+ env?: Record<string, string>;+ inputs?: Record<string, string | boolean>;+}++const pipeline = parse(+ readFileSync(+ new URL(+ "../../../examples/azure-pipelines/azure-pipelines.yml",+ import.meta.url,+ ),+ "utf8",+ ),+) as {+ trigger: string;+ resources: { repositories: { repository: string; trigger: string }[] };+ jobs: {+ variables: Record<string, string>;+ steps: (Step | Record<string, Step[]>)[];+ }[];+};+const job = pipeline.jobs[0]!;+const steps = job.steps.flatMap((step) =>+ step.task || step.checkout ? [step] : Object.values(step).flat(),+) as Step[];+const scan = steps.find((step) => step.name === "runScan")!;+const sarif = steps.find((step) => step.name === "exportSarif")!;+const temporaryDirectories: string[] = [];++afterEach(() => {+ for (const directory of temporaryDirectories.splice(0)) {+ rmSync(directory, { recursive: true, force: true });+ }+});++function runStep(+ step: Step,+ overrides: Record<string, string> = {},+ scanFiles: string[] = [],+) {+ const directory = mkdtempSync(join(tmpdir(), "codex azure example "));+ temporaryDirectories.push(directory);+ for (const child of ["repository with spaces", "scan", "reports"]) {+ mkdirSync(join(directory, child));+ }+ for (const file of scanFiles) {+ writeFileSync(join(directory, "scan", file), "synthetic fixture");+ }+ // Git Bash accepts forward-slash drive paths on Windows.+ const root = directory.replaceAll("\\", "/");+ const bash =+ process.platform === "win32"+ ? join(+ process.env["ProgramFiles"] ?? "C:/Program Files",+ "Git/bin/bash.exe",+ )+ : "bash";+ const result = spawnSync(+ bash,+ [+ "--noprofile",+ "--norc",+ "-c",+ `codex-security() {+ printf '%s\\0' "$@" > "$ARGUMENTS_PATH"+ printf '{"mock":true}\\n'+ return "$MOCK_EXIT_CODE"+}+${step.inputs?.["inlineScript"] ?? step.inputs?.["script"]}`,+ ],+ {+ cwd: directory,+ encoding: "utf8",+ env: {+ PATH: process.env["PATH"],+ SYSTEMROOT: process.env["SYSTEMROOT"],+ ARGUMENTS_PATH: `${root}/arguments`,+ TARGET_DIRECTORY: `${root}/repository with spaces`,+ SCAN_DIRECTORY: `${root}/scan`,+ REPORT_DIRECTORY: `${root}/reports`,+ BEDROCK_MODEL_ID: "example.model",+ SCAN_MODE: "full",+ BASE_REVISION: "HEAD^",+ FAIL_ON_SEVERITY: "none",+ MOCK_EXIT_CODE: "0",+ ...overrides,+ },+ },+ );+ if (result.error) throw result.error;+ const argumentsPath = join(directory, "arguments");+ const args = existsSync(argumentsPath)+ ? readFileSync(argumentsPath, "utf8").split("\0").slice(0, -1)+ : [];+ return { ...result, directory, root, args };+}++test("runs a report-only full scan outside the target checkout", () => {+ const result = runStep(scan);+ expect(result.status).toBe(0);+ expect(result.args).toEqual([+ "scan",+ `${result.root}/repository with spaces`,+ "--provider",+ "amazon-bedrock",+ "--model",+ "example.model",+ "--mode",+ "standard",+ "--effort",+ "high",+ "--output-dir",+ `${result.root}/scan`,+ "--json",+ ]);+});++test("passes a diff revision literally, without evaluating shell syntax", () => {+ const base = "revision with spaces; $(exit 99)";+ const result = runStep(scan, { SCAN_MODE: "diff", BASE_REVISION: base });+ expect(result.status).toBe(0);+ expect(result.args.slice(-2)).toEqual(["--diff", base]);+});++for (const status of [0, 1, 2, 130, 143]) {+ test(`preserves scan exit ${status} and records it for subsequent tasks`, () => {+ const result = runStep(scan, {+ MOCK_EXIT_CODE: String(status),+ FAIL_ON_SEVERITY: "high",+ });+ expect(result.status).toBe(status);+ expect(result.args.slice(-2)).toEqual(["--fail-on-severity", "high"]);+ expect(result.stdout).toBe(+ `##vso[task.setvariable variable=scanExitCode]${status}\n`,+ );+ expect(+ JSON.parse(+ readFileSync(join(result.directory, "reports/result.json"), "utf8"),+ ),+ ).toEqual({ mock: true });+ });+}++test("exports fingerprints and only signals readiness after a successful export", () => {+ const result = runStep(sarif);+ expect(result.status).toBe(0);+ expect(result.args).toEqual([+ "export",+ `${result.root}/scan`,+ "--export-format",+ "sarif",+ "--source-root",+ `${result.root}/repository with spaces`,+ "--output",+ `${result.root}/reports/results.sarif`,+ ]);+ expect(result.stdout).toContain(+ "##vso[task.setvariable variable=sarifReady]true\n",+ );+ const failed = runStep(sarif, { MOCK_EXIT_CODE: "2" });+ expect(failed.status).toBe(2);+ expect(failed.stdout).not.toContain("variable=sarifReady");+ expect(sarif.condition).toBe(+ "and(succeededOrFailed(), in(variables['scanExitCode'], '0', '1'))",+ );+ const publisher = steps.find(+ (step) => step.task === "AdvancedSecurity-Publish@1",+ )!;+ expect(publisher.condition).toBe(+ "and(succeededOrFailed(), eq(variables['sarifReady'], 'true'))",+ );+});++test("retains selected reports without copying raw state or credentials", () => {+ const collect = steps.find((step) => step.name === "stageReports")!;+ const reports = ["coverage.json", "findings.json", "report.md"];+ const result = runStep(collect, {}, [+ ...reports,+ "auth.json",+ "transcript.jsonl",+ "workbench.sqlite3",+ ]);+ expect(result.status).toBe(0);+ expect(readdirSync(join(result.directory, "reports")).sort()).toEqual(+ reports,+ );+ expect(runStep(collect).status).toBe(0);+});++test("uses the explicit target resource and keeps setup separate from scanning", () => {+ expect(pipeline.trigger).toBe("none");+ expect(pipeline.resources.repositories).toMatchObject([+ { repository: "target", trigger: "none" },+ ]);+ expect(job.variables["advancedsecurity.publish.repository"]).toBe(+ "$[ convertToJson(resources.repositories['target']) ]",+ );+ const checkout = steps.findIndex((step) => step.checkout === "target");+ expect(steps.findIndex((step) => step.name === "installCli")).toBeLessThan(+ checkout,+ );+ expect(steps[checkout]).toMatchObject({+ fetchDepth: 0,+ persistCredentials: false,+ });+ expect(scan.inputs?.["disableAutoCwd"]).toBe(true);+ for (const step of steps) {+ expect(step.env ?? {}).not.toHaveProperty("SYSTEM_ACCESSTOKEN");+ }+});