SDK TypeScript do Codex Security

Use o SDK TypeScript do Codex Security para executar varreduras de segurança em repositórios e alterações de código a partir do seu aplicativo ou da sua ferramenta de desenvolvimento. O SDK retorna achados tipados, o manifesto da varredura e os caminhos dos relatórios salvos.

O SDK usa módulos ECMAScript (ESM) e é executado no servidor com Node.js 24 ou 26, ou com Node.js 22 a partir da versão 22.13.0. As varreduras também exigem Python 3.10 ou posterior. Para o Python 3.10, também é necessário instalar o pacote tomli.

Para ler ou retomar sessões compactadas do Codex (.jsonl.zst), use Node.js 22.15.0 ou posterior da série 22.x, ou Node.js 24 ou 26. Sessões .jsonl sem compactação funcionam em todas as versões compatíveis do Node.js.

Configure o SDK

Instale o SDK:

npm install @openai/codex-security

Antes de iniciar uma varredura, defina OPENAI_API_KEY ou CODEX_API_KEY, use um login do Codex já salvo em arquivo ou configure outro provedor. O Amazon Bedrock usa credenciais da AWS. O OpenRouter e o Fireworks usam chaves de API e configurações específicas de cada provedor.

Algumas solicitações de cibersegurança e alguns achados protegidos exigem Trusted Access for Cyber na sua conta do ChatGPT ou na sua organização da API.

Execute uma varredura

O SDK é executado com as suas permissões no sistema operacional local e não pausa para pedir aprovação. Os processos da varredura podem herdar as variáveis do seu ambiente. Remova as credenciais que não serão usadas antes de começar. Consulte Permissões de varredura local.

Salve este exemplo como scan.mjs. Passe os caminhos do repositório e do diretório de resultados como argumentos de linha de comando. Execute uma varredura padrão do repositório e feche o cliente quando a execução terminar. Passe outputDir para escolher um diretório privado de resultados fora da árvore de trabalho do Git que contém o código em análise.

Se você omitir outputDir, o Codex Security salvará os resultados no próprio diretório de estado persistente. Os resultados podem incluir trechos do código-fonte e detalhes de vulnerabilidades. Defina quem pode lê-los e por quanto tempo serão mantidos.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { CodexSecurity } from "@openai/codex-security";

const [repository, outputDir] = process.argv.slice(2);
if (!repository || !outputDir) {
  throw new Error("Usage: node scan.mjs <repository> <results-directory>");
}
const security = new CodexSecurity();

try {
  const result = await security.run(repository, {
    outputDir,
  });

  console.log(result.reportPath);
  console.log(result.manifest.scan.status);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

Execute o exemplo com o Node.js:

node scan.mjs /path/to/repository /path/outside/repository/results

O exemplo exibe o caminho do relatório, o status da varredura e a quantidade de achados. Abra o relatório para examinar as evidências.

run valida os artefatos salvos e retorna um ScanResult quando result.manifest.scan.status é "completed". Consulte result.manifest.scan.scope para conferir o alvo solicitado e result.manifest.scan.warnings para verificar se há avisos. O status de conclusão por si só não indica quais arquivos foram analisados. Falhas no ambiente de execução, nas entradas ou na integridade dos resultados podem gerar um erro.

Nos próximos exemplos, reutilize o cliente security aberto e mantenha close() no bloco finally para liberar o ambiente de execução. Adicione as demais importações no início de scan.mjs.

Verifique as entradas antes da varredura

Use preflight para verificar o repositório, o alvo, o modo, os documentos da base de conhecimento, o local de saída e a configuração do Codex antes de iniciar uma varredura. Este exemplo lê o arquivo security.md na raiz do repositório:

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

const plan = await security.preflight(repository, {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: [knowledgeBase],
  outputDir: outputDir,
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

A verificação prévia examina as entradas locais sem iniciar o Codex, carregar credenciais ou verificar a disponibilidade do Python e do plugin. Mesmo que a verificação seja bem-sucedida, não há garantia de que a varredura conseguirá se autenticar ou iniciar.

Para visualizar o destino de arquivamento de um diretório de resultados existente, defina archiveExisting: true:

1
2
3
4
5
6const plan = await security.preflight(repository, {
  outputDir: outputDir,
  archiveExisting: true,
});

console.log(plan.archiveDir);

O valor retornado em archiveDir mostra como o diretório de arquivamento será nomeado. O caminho final pode ser diferente porque run gera seu próprio destino exclusivo. Para obter o caminho usado de fato, use onOutputArchived:

1
2
3
4
5
6
7
8
9
10
11try {
  await security.run(repository, {
    outputDir: outputDir,
    archiveExisting: true,
    onOutputArchived(archiveDir) {
      console.log("Archived results:", archiveDir);
    },
  });
} finally {
  await security.close();
}

A varredura arquiva os resultados anteriores e começa com um diretório de saída vazio.

Escolha o alvo da varredura

O SDK aceita como alvo um repositório, caminhos específicos, diferenças entre commits ou alterações na árvore de trabalho. O alvo padrão é o repositório inteiro.

Analise caminhos específicos

Passe um array de caminhos dentro do repositório:

1
2
3
4
5
6
7try {
  const result = await security.run(repository, {
    target: ["services/billing", "packages/auth"],
  });
} finally {
  await security.close();
}

Os caminhos podem indicar arquivos ou diretórios. O SDK resolve cada caminho dentro do repositório e remove as duplicatas.

Analise alterações entre commits

Use DiffTarget.refs para analisar as alterações registradas em commits entre duas revisões do Git disponíveis localmente:

1
2
3
4
5
6
7
8
9
10
11
12import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "HEAD~1",
  head: "HEAD",
});

try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

A revisão final padrão é HEAD. Passe a raiz da árvore de trabalho do Git como repositório e faça checkout da revisão final solicitada antes da varredura.

Analise a árvore de trabalho

Use DiffTarget.workingTree para analisar as alterações, tanto as preparadas para commit quanto as ainda não preparadas, em relação a uma revisão de base:

1
2
3
4
5
6
7import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.workingTree({ base: "HEAD" });
try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

A base padrão é HEAD. Busque as revisões selecionadas antes de iniciar uma varredura das diferenças entre commits ou da árvore de trabalho.

Selecione o modo aprofundado

Defina mode: "deep" quando a varredura de um repositório ou de caminhos específicos exigir uma análise mais abrangente:

1
2
3
4
5
6
7
8
9
10
11
12
13try {
  const result = await security.run(repository, {
    target: ["services/billing"],
    mode: "deep",
    workers: 2,
    subagents: 0,
    stopAfterNoNew: 3,
    maxDiscoveryRuns: 10,
    maxTimeMinutes: 90,
  });
} finally {
  await security.close();
}

O modo aprofundado aceita repositórios e caminhos como alvos. Use o modo padrão para analisar diferenças entre commits e alterações na árvore de trabalho. No modo aprofundado, workers limita o número de workers que executam a varredura simultaneamente, e subagents define o número de subagentes por worker. stopAfterNoNew encerra a etapa de descoberta quando os workers atingem o número especificado de execuções consecutivas sem novos achados. maxDiscoveryRuns limita o número total de execuções dos workers.

Defina maxTimeMinutes para limitar a duração da descoberta no modo aprofundado. Tanto o valor padrão quanto o máximo são de 5.760 minutos (96 horas). Quando o prazo termina, a descoberta é encerrada e o SDK combina os resultados dos workers que concluíram a execução. Nas varreduras padrão, maxTimeMinutes serve como referência de tempo para a investigação. A geração de relatórios pode terminar depois desse prazo. A validação personalizada e as instruções pós-varredura são executadas fora desse período.

Adicione uma base de conhecimento de segurança

Passe documentos de arquitetura, modelos de ameaças ou políticas de segurança por meio de knowledgeBasePaths:

1
2
3
4
5
6
7
8
9
10
11import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

try {
  const result = await security.run(repository, {
    knowledgeBasePaths: [knowledgeBase],
  });
} finally {
  await security.close();
}

O SDK aceita arquivos ou diretórios e percorre os diretórios recursivamente. Os formatos compatíveis incluem texto em UTF-8 (inclusive JSON e SARIF), PDF e DOCX. O SDK rejeita caminhos de entrada que sejam links e ignora links ao percorrer os diretórios.

O SDK salva o texto extraído dos documentos no arquivo privado .scan-knowledge.json, junto aos artefatos da varredura. Mantenha o arquivo no diretório da varredura. Ao retomar uma varredura aprofundada interrompida, codex-security scans resume usa esse texto salvo mesmo que os documentos originais tenham sido alterados ou excluídos. Os relatórios canônicos não incorporam o texto dos documentos.

Adicione instruções para a varredura e para a etapa seguinte

Use scanPrompt para direcionar a varredura e postScanPrompt para solicitar uma ação após a conclusão:

1
2
3
4
5
6
7
8try {
  const result = await security.run(repository, {
    scanPrompt: "Focus on tenant isolation and authorization checks.",
    postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
  });
} finally {
  await security.close();
}

Se essa ação falhar, o SDK mantém a varredura concluída e informa o erro por meio de onWarning. Ele restaura os artefatos da varredura concluída que a ação tiver alterado. A ação é executada depois que o acompanhamento de custos da varredura termina e não está sujeita a maxCostUsd.

Valide os achados no seu ambiente

Passe validationPrompt para verificar possíveis achados com seu próprio procedimento de teste. Por exemplo, indique no prompt um script sob seu controle que esteja fora da cópia de trabalho e execute-o usando seu servidor de teste local. Depois dos argumentos que indicam o repositório e o diretório de resultados, passe o caminho do script de validação e a URL do servidor, nessa ordem:

1
2
3
4
5
6
7const [validationScript, validationUrl] = process.argv.slice(4);
if (!validationScript || !validationUrl)
  throw new Error("Pass a validation script path and service URL.");
const result = await security.run(repository, {
  outputDir,
  validationPrompt: `Run ${validationScript} against ${validationUrl} and report which findings reproduce.`,
});

node scan.mjs /path/to/repository /path/outside/repository/results /path/to/validate.sh http://localhost:3000

Use validationPrompt em varreduras padrão de repositórios, caminhos, diferenças entre commits ou árvores de trabalho. Para usar o mesmo procedimento em cada varredura padrão de componente, passe scanOptions.validationPrompt para runComponentScans. As varreduras aprofundadas rejeitam a validação personalizada.

Defina um orçamento para a varredura

Defina maxCostUsd para interromper a varredura quando o custo estimado de uso do modelo ultrapassar o limite. Use onCost para acompanhar o custo durante a execução e exibir estimatedUsdRange:

1
2
3
4
5
6
7
8
9
10
11
12try {
  const result = await security.run(repository, {
    maxCostUsd: 5,
    onCost(cost) {
      console.log(cost.estimatedUsdRange);
    },
  });

  console.log(result.cost?.estimatedUsdRange);
} finally {
  await security.close();
}

O limite usa estimatedUsd, a estimativa de referência para contexto curto. Solicitações já em andamento podem elevar essa estimativa acima do limite. Os preços para contexto longo podem fazer com que estimatedUsdRange também ultrapasse esse valor. Esse limite não estabelece um teto de cobrança.

Se uma varredura aprofundada atingir o limite depois que o Codex Security agregar os resultados dos workers que terminaram a execução, run poderá retornar um resultado com manifest.scan.status definido como "completed" e emitir o aviso de orçamento por meio de onWarning.

Se a varredura não conseguir produzir um resultado final válido, run lançará ScanCostLimitExceededError e preservará toda a saída disponível.

Analise os componentes do projeto

Use runComponentScans para analisar serviços ou pacotes em paralelo e combinar os achados. Atribua a cada componente um nome e um ou mais caminhos relativos ao repositório. Escolha um diretório de saída novo ou vazio fora da árvore de trabalho do Git que contém o projeto.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { runComponentScans } from "@openai/codex-security";

const result = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  components: [
    { name: "API", paths: ["services/api", "packages/auth"] },
    { name: "Web", paths: ["services/billing"] },
  ],
  workers: 2,
  onProgress: ({ name, status }) => console.log(name, status),
});

console.log(result.reportPath);
if (result.failed > 0) {
  throw new Error(`${result.failed} component scans failed.`);
}

Defina workers para controlar quantos componentes são analisados ao mesmo tempo. O padrão é quatro.

Para que o Codex proponha os componentes, passe auto: true em vez de components. Adicione planOnly: true para salvar o plano em components.json sem executar nenhuma varredura:

1
2
3
4
5
6
7
8
9
10import { runComponentScans } from "@openai/codex-security";

const plan = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  auto: true,
  planOnly: true,
});

console.log(plan.planPath);

Se a execução terminar com falhas em alguns componentes, leia o arquivo JSON indicado em result.retryPlanPath. Passe o array components desse arquivo para runComponentScans com um novo outputDir. O relatório da nova tentativa abrange apenas esses componentes. Examine os relatórios das duas execuções.

Trabalhe com os resultados da varredura

ScanResult disponibiliza os documentos estruturados, os metadados da varredura e os caminhos dos artefatos:

Para exigir a mesma versão do plugin em uma varredura posterior, passe expectedPluginVersion: result.pluginVersion. O SDK rejeita a varredura se a versão instalada do plugin for diferente.

Consulte a gravidade e a primeira localização no código-fonte de cada achado:

1
2
3
4
5
6
7
8
9
10for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

Os achados podem incluir os campos opcionais codeEvidence, rootCause, validation, attackPath, remediationTests e preventiveControls.

Entre os achados de todo o repositório, confirmedInLatestScan distingue os identificados na varredura mais recente dos achados anteriores que continuam em aberto:

1
2
3for (const finding of result.repositoryFindings ?? []) {
  console.log(finding.title, finding.confirmedInLatestScan);
}

Use result.toJSON() para serializar o manifesto, os achados, as exclusões registradas na análise, os caminhos dos artefatos e os metadados do turno.

Leia os modelos de ameaças salvos

Verifique se threatModel e threatModelPath têm valor null antes de usá-los. Você pode exportar um modelo salvo mesmo que o Codex Security não tenha conseguido gravar o arquivo Markdown correspondente. Use o caminho retornado pela exportação em vez de presumir o nome do arquivo.

Exporte os artefatos salvos

Exporte resultados salvos sem iniciar o Codex, carregar credenciais ou fazer uma chamada ao modelo. Este exemplo exporta um modelo de ameaças salvo para a saída padrão. Passe o diretório que contém os resultados de uma varredura como primeiro argumento de linha de comando:

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { exportArtifact } from "@openai/codex-security";

const directory = process.argv[2];
if (!directory) {
  throw new Error(
    "Pass an existing scan results directory as the first argument."
  );
}

await exportArtifact({
  source: { directory },
  artifact: "threat-model",
  output: "-",
});

Para selecionar uma varredura salva pelo ID, use source: { scanId: "SCAN_ID" } no lugar do diretório. Defina output com o caminho de destino para salvar o artefato em um arquivo.

A exportação gera modelos de ameaças em Markdown. Se a varredura não tiver um modelo de ameaças salvo, a exportação retornará um erro. Para exportar achados, defina artifact: "findings" e escolha format: "sarif" (o padrão), "json", "csv" ou "servicenow-avit".

O resultado inclui o caminho de saída em path e, ao exportar um modelo de ameaças para um arquivo, os dados de provenance dos mesmos resultados salvos. Ambos os campos têm valor null quando output: "-" grava na saída padrão. A exportação exige Python 3.10 ou posterior.

Para usar o ServiceNow Manual AVIT Ingestion, defina artifact: "findings" e format: "servicenow-avit". Prepare o modelo do aplicativo e passe o caminho desse arquivo em avitTemplate. Em output, informe o caminho do arquivo CSV de destino em um local privado fora do repositório. Use source.directory para selecionar o diretório que já contém os resultados da varredura.

Valide um achado existente

Use validate para conferir no código-fonte um achado de outra ferramenta ou de outro fluxo de trabalho. O método não inicia uma nova varredura nem executa o aplicativo ou seus testes. Se precisar de evidências de execução, reproduza o problema separadamente.

1
2
3
4
5
6
7
8
9
10const validation = await security.validate({
  repositoryPath: repository,
  finding: {
    title: "Possible SQL injection",
    location: "src/index.js:1",
  },
});

console.log(validation.disposition);
console.log(validation.report);

Passe o achado como texto não vazio ou como objeto JSON. Se estiver em um arquivo, leia o arquivo e passe seu conteúdo.

O campo disposition indica se o achado foi classificado como reportable, suppressed, not_applicable ou deferred. O texto em Markdown de validation.report explica as evidências e as lacunas que ainda existem. Salve essa string se precisar de um arquivo de relatório.

Acompanhe ou cancele uma varredura

Passe callbacks de ScanOptions para informar o início da varredura, o progresso dos workers e as tentativas de reconexão:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27try {
  const result = await security.run(repository, {
    outputDir: outputDir,
    onScanStarted() {
      console.log("Scan started");
    },
    onProgress(progress) {
      console.log(progress.phase, progress.filesCompleted, progress.filesTotal);
    },
    onWorkerStatus(status) {
      console.log(status.kind, status);
    },
    onSessionEvent(session) {
      console.log(session.threadId, session.worker, session.event["type"]);
    },
    onReconnect(attempt, maxAttempts) {
      console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
    },
    onObserverError(observer, error) {
      console.error(`${observer} failed`, error);
    },
  });

  console.log(result.reportPath);
} finally {
  await security.close();
}

Passe um AbortSignal da solicitação ou do controlador de tarefas para cancelar uma varredura. Se ela ainda estiver em execução após 30 minutos, este exemplo a interromperá e exibirá o diretório que contém a saída salva, se houver:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { ScanInterruptedError } from "@openai/codex-security";

try {
  await security.run(repository, {
    outputDir: outputDir,
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
} finally {
  await security.close();
}

Uma varredura interrompida pode deixar resultados parciais em scanDir. Preserve esse diretório se precisar investigar o resultado.

Aplicativos que exibem o progresso da preparação da varredura também podem usar os callbacks de ciclo de vida de ScanOptions:

O status do Trusted Access pode ser granted, not_granted ou unknown. A ausência de acesso ou um status desconhecido também aciona onWarning.

onSessionEvent recebe eventos sem ocultação de dados, que podem conter código-fonte ou credenciais. Filtre esses eventos antes de enviá-los a logs compartilhados ou a outros serviços.

Configure o ambiente de execução e as credenciais

Passe a configuração do ambiente de execução quando precisar de um plugin, de um interpretador ou de uma configuração específica do Codex. Escolha um modelo disponível para sua conta:

1
2
3
4
5
6
7
8const security = new CodexSecurity({
  // To override the bundled plugin, add pluginPath: "/path/to/plugin".
  pythonPath: "python3",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

Defina pluginPath com o caminho de um diretório de plugin ou de um arquivo ZIP para substituir o plugin incluído no SDK. pythonPath seleciona o interpretador do plugin. codexOverrides incorpora os valores compatíveis à configuração isolada do Codex. Para usar o Amazon Bedrock, defina model_provider e model em codexOverrides.

Defina codexOverrides.approval_policy como "never" para negar solicitações de permissão. Caso contrário, as varreduras usam a revisão automática das solicitações de aprovação. Consulte Permissões de varredura local para saber mais sobre o acesso ao sistema de arquivos e as credenciais herdadas.

Para usar o OpenRouter ou o Fireworks, forneça também a chave de API correspondente e a configuração completa do provedor em codexOverrides. Defina OPENROUTER_API_KEY e passe o ID de um modelo disponível no OpenRouter para esta função TypeScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16function createOpenRouterClient(model: string) {
  return new CodexSecurity({
    codexOverrides: {
      model,
      model_provider: "openrouter",
      model_providers: {
        openrouter: {
          name: "OpenRouter",
          base_url: "https://openrouter.ai/api/v1",
          env_key: "OPENROUTER_API_KEY",
          wire_api: "responses",
        },
      },
    },
  });
}

Para usar o Fireworks, altere as duas chaves openrouter para fireworks, defina name como Fireworks AI e env_key como FIREWORKS_API_KEY, use https://api.fireworks.ai/inference/v1 como base_url e selecione um modelo do Fireworks.

O cliente também disponibiliza os seguintes métodos de autenticação:

O objeto de login disponibiliza waitForInstructions, authUrl, verificationUrl, userCode, wait e cancel para que o aplicativo possa apresentar e concluir o fluxo de login escolhido. O SDK pode reutilizar um login do Codex salvo em arquivo. Use chaves de API para CI e automação no servidor.

Quando há uma chave de API e um login salvo, o SDK usa a chave de API por padrão. Para usar seu login do ChatGPT, selecione-o para a varredura:

1
2
3const result = await security.run(repository, {
  auth: "chatgpt",
});

Defina auth: "api-key" para exigir uma chave de API nas variáveis de ambiente. preflight aceita a mesma opção auth.

Trate os erros da varredura

Capture os erros pela classe exportada que corresponde à ação que seu aplicativo pode tomar:

Continue com o guia de início rápido da CLI, o guia de CI ou a referência da CLI.