SDK TypeScript do Codex Security

Utilize o SDK TypeScript do Codex Security para executar análises de segurança em repositórios e alterações de código a partir da sua aplicação ou ferramenta de desenvolvimento. O SDK devolve deteções tipificadas, detalhes de cobertura e caminhos para os artefactos da análise. Para análises mais demoradas, suporta verificações preliminares, limites de custos, callbacks de progresso e cancelamento.

O SDK utiliza módulos ECMAScript (ESM) e é executado no servidor com Node.js 24 ou 26, ou Node.js 22 a partir da versão 22.13.0. A análise também requer Python 3.10 ou posterior. O Python 3.10 também requer o pacote tomli.

Configurar o SDK

Instale o SDK:

npm install @openai/codex-security

Antes de iniciar uma análise, defina OPENAI_API_KEY ou CODEX_API_KEY, utilize um início de sessão existente do Codex baseado em ficheiros ou configure outro fornecedor. O Amazon Bedrock utiliza credenciais da AWS; o OpenRouter e o Fireworks utilizam API keys e configurações específicas do fornecedor.

Para obter os melhores resultados, utilize uma conta verificada para Trusted Access for Cyber. Iniciar sessão ou fornecer uma API key não concede Trusted Access.

Executar uma análise

O SDK é executado com as suas permissões locais do sistema operativo e não faz pausas para aprovação. Os processos de análise podem herdar o seu ambiente, pelo que deve remover credenciais não relacionadas antes de começar. Consulte Permissões de análise local.

Guarde este exemplo como scan.mjs. Substitua os caminhos, execute uma análise padrão do repositório e feche o cliente quando o trabalho terminar. Passe outputDir para escolher um diretório privado de resultados fora da árvore de trabalho Git que contém o repositório.

Se omitir outputDir, o Codex Security guarda os resultados no seu próprio diretório persistente de estado. Os resultados podem incluir excertos de código-fonte e detalhes de vulnerabilidades. Defina quem os pode ler e durante quanto tempo devem ser conservados.

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

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

Execute-o com Node.js:

node scan.mjs

O exemplo apresenta o caminho do relatório, o estado da análise e o número de constatações. Abra o relatório para rever as evidências. O número varia consoante o repositório e a análise, pelo que não deve utilizar um número esperado para verificar se a integração funciona.

run valida os artefactos guardados e devolve um ScanResult quando result.manifest.scan.status é "completed". Consulte result.coverage para ver as áreas revistas, as exclusões e o trabalho adiado. Uma análise concluída pode ainda ter lacunas de cobertura. Falhas de execução, de entrada ou de integridade dos resultados podem lançar um erro.

Nos exemplos seguintes, reutilize o cliente security aberto e mantenha close() em finally para libertar o ambiente de execução. Adicione quaisquer importações adicionais no início de scan.mjs.

Verificar entradas com a análise preliminar

Utilize preflight para verificar um repositório, alvo, modo, documentos da base de conhecimentos, localização de saída e configuração do Codex antes de iniciar uma análise:

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: ["/path/to/architecture.md"],
  outputDir: "/path/outside/repository/results",
});

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

A verificação prévia verifica as entradas locais sem iniciar o Codex, carregar credenciais ou verificar a disponibilidade do Python e do plugin. Uma verificação prévia bem-sucedida não comprova que a análise consiga autenticar-se ou iniciar.

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

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

O archiveDir devolvido pré-visualiza a nomenclatura do arquivamento. O caminho final pode ser diferente porque run gera o seu próprio destino exclusivo. Capture o caminho real do arquivamento com onOutputArchived:

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

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

Escolher um alvo de análise

O SDK suporta alvos de repositório, caminho, diferenças consolidadas e árvore de trabalho. O alvo predefinido é o repositório completo.

Analisar caminhos selecionados

Transmita uma matriz de caminhos dentro do repositório:

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Os caminhos podem identificar ficheiros ou diretórios. O SDK resolve cada caminho dentro do repositório e remove duplicados.

Analisar alterações consolidadas

Utilize DiffTarget.refs para analisar alterações consolidadas entre duas revisões do Git disponíveis localmente:

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

Por predefinição, a origem é HEAD. Os alvos de diferenças requerem que o argumento do repositório seja a raiz da árvore de trabalho do Git.

Analisar a árvore de trabalho

Utilize DiffTarget.workingTree para analisar alterações preparadas e não preparadas em relação a uma revisão de base:

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

Por predefinição, a base é HEAD. Obtenha as revisões selecionadas antes de iniciar uma análise de diferenças ou da árvore de trabalho.

Selecionar o modo aprofundado

Defina mode: "deep" para uma análise de repositório ou caminho que necessite de uma revisão mais abrangente:

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

O modo aprofundado suporta alvos de repositório e caminho. Utilize o modo normal para análises de diferenças e da árvore de trabalho. As definições opcionais controlam os trabalhadores simultâneos e independentes de análise normal, os subagentes por trabalhador, as análises consecutivas concluídas pelo trabalhador sem novas deteções e o número total e a duração das execuções dos trabalhadores. Requerem mode: "deep".

maxTimeHours tem o valor predefinido 96 e aceita um número positivo até 96, incluindo frações de hora. Ao atingir o prazo, o Codex Security interrompe os processos de trabalho por concluir, conserva os resultados das análises concluídas e agrega-os no relatório final. Consulte result.coverage para ver o trabalho adiado e as questões em aberto.

Adicionar uma base de conhecimentos de segurança

Transmita documentos de arquitetura, modelos de ameaças ou políticas de segurança através de knowledgeBasePaths:

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

O SDK aceita ficheiros ou diretórios e pesquisa diretórios recursivamente. Os formatos de documento suportados são .md, .markdown, .txt, .pdf e .docx. O SDK rejeita caminhos de entrada ligados, ignora entradas de diretório ligadas e mantém o conteúdo extraído dos documentos fora dos resultados de análise guardados.

Adicionar instruções de análise e acompanhamento

Utilize scanPrompt para orientar a análise e postScanPrompt para solicitar um acompanhamento:

const result = await security.run("/path/to/repository", {
  scanPrompt: "Focus on tenant isolation and authorization checks.",
  postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});

Se o acompanhamento falhar, o SDK conserva a análise concluída e comunica o erro através de onWarning. Restaura quaisquer artefactos da análise concluída que o acompanhamento tenha alterado.

Definir um orçamento de análise

Defina maxCostUsd para interromper uma análise quando o custo estimado do modelo exceder um limite. Utilize onCost para acompanhar o custo durante a análise:

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

O limite estima as despesas, mas não é um teto rígido, pelo que os pedidos já em curso podem terminar ligeiramente acima desse valor. Se uma análise aprofundada atingir o limite depois de o Codex Security agregar os resultados dos processos de trabalho concluídos, run pode devolver um resultado com manifest.scan.status definido como "completed" e comunicar o aviso de orçamento através de onWarning. Consulte result.coverage para ver o trabalho que ficou por concluir.

Se a análise não conseguir produzir um resultado concluído válido, run lança ScanCostLimitExceededError e preserva todos os dados de saída disponíveis.

Trabalhar com resultados de análises

ScanResult expõe os documentos estruturados, os metadados da análise e os caminhos dos artefactos:

Para exigir o mesmo plugin numa análise posterior, transmita expectedPluginVersion: result.pluginVersion. O SDK rejeita a análise se a versão do plugin instalado for diferente.

Utilize diretamente as deteções estruturadas e a cobertura:

for (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
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

As deteções podem incluir os campos opcionais codeEvidence, rootCause, validation, attackPath, remediationTests e preventiveControls.

Para deteções em todo o repositório, confirmedInLatestScan distingue as deteções observadas na análise mais recente das deteções anteriores que permanecem abertas:

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

Os novos resultados não incluem coverage.completeness. Utilize manifest.scan.status para ver o estado da execução e reveja as áreas adiadas, as exclusões e as questões em aberto em coverage para compreender o que a análise reviu.

result.toJSON() devolve o manifesto, as deteções do repositório e da análise atual, a cobertura, os identificadores da análise e do tópico, reportPath, artifactsDir, sarifPath, o custo e os metadados do turno num único objeto preparado para JSON.

Acompanhar ou cancelar uma análise

Transmita callbacks ScanOptions para comunicar o início da análise, o progresso dos trabalhadores e as novas tentativas de ligação:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  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);

Passe um AbortSignal do controlador do pedido ou da tarefa para cancelar uma análise. Se a análise ainda estiver em execução ao fim de 30 minutos, este exemplo interrompe-a e apresenta o diretório que contém os dados de saída guardados:

try {
  await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

Uma análise interrompida pode deixar uma saída parcial em scanDir. Preserve esse diretório quando for necessário investigar o resultado.

As aplicações que apresentam o progresso da configuração da análise também podem utilizar os callbacks de ciclo de vida ScanOptions:

O estado de Trusted Access é granted, not_granted ou unknown. O acesso em falta ou desconhecido também aciona onWarning.

onSessionEvent recebe eventos que não são ocultados e podem conter código-fonte ou credenciais. Filtre-os antes de os enviar para registos partilhados ou outros serviços.

Configurar o runtime e as credenciais

Forneça a configuração de execução quando precisar de um plugin, interpretador ou definição do Codex específicos. Escolha um modelo ao qual as suas credenciais permitam aceder. Se iniciar sessão com o ChatGPT, consulte a disponibilidade do GPT-6.1 Sol antes de utilizar este exemplo:

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

pluginPath aceita um diretório ou ZIP de plugin. pythonPath seleciona o interpretador do plugin. codexOverrides intercala valores suportados na configuração isolada do Codex. Por predefinição, as análises utilizam gpt-5.6-sol com um esforço de raciocínio extraelevado. Defina model e model_reasoning_effort em codexOverrides para utilizar um modelo ou esforço de raciocínio diferente. Para utilizar o Amazon Bedrock, defina model_provider e model em codexOverrides.

codexOverrides não pode restringir o acesso da análise ao sistema de ficheiros nem alterar a respetiva política de aprovação. Consulte Permissões de análise local.

Para OpenRouter ou Fireworks, forneça também a API key correspondente e uma configuração completa do fornecedor em codexOverrides. Por exemplo, defina OPENROUTER_API_KEY e configure o OpenRouter:

const security = new CodexSecurity({
  codexOverrides: {
    model: "anthropic/claude-sonnet-4.5",
    model_provider: "openrouter",
    model_providers: {
      openrouter: {
        name: "OpenRouter",
        base_url: "https://openrouter.ai/api/v1",
        env_key: "OPENROUTER_API_KEY",
        wire_api: "responses",
      },
    },
  },
});

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

O cliente também expõe métodos de autenticação suportados:

Um identificador de início de sessão disponibiliza waitForInstructions, authUrl, verificationUrl, userCode, wait e cancel para que uma aplicação possa apresentar e concluir o fluxo de início de sessão selecionado. O SDK pode reutilizar um início de sessão do Codex guardado num ficheiro. Utilize API keys para CI e automação no servidor.

Quando estão disponíveis uma API key e um início de sessão armazenado, o SDK utiliza a API key por predefinição. Para utilizar o seu início de sessão do ChatGPT, selecione-o para a análise:

const result = await security.run("/path/to/repository", {
  auth: "chatgpt",
});

Defina auth: "api-key" para exigir uma API key do ambiente. preflight aceita a mesma opção auth.

Tratar erros de análise

Capture a classe de erro exportada que corresponde à ação que a sua aplicação pode executar:

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