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 22 (22.13.0 ou posterior), 24 ou 26. 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

Analise apenas repositórios nos quais confia e que tem autorização para avaliar. O SDK é executado com as permissões locais do seu sistema operativo e nunca aguarda 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.

Crie um cliente CodexSecurity, execute uma análise normal do repositório e feche o cliente quando o trabalho terminar. Transmita outputDir para escolher um diretório privado de resultados fora da árvore de trabalho do Git envolvente.

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, pelo que deve escolher permissões e políticas de retenção adequadas.

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.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run inicia a análise, aguarda a conclusão, valida os artefactos selados e devolve um ScanResult. close liberta o runtime isolado e suporta chamadas repetidas.

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 análise preliminar não altera o runtime nem as credenciais do Codex. Também deixa a deteção do plugin e do Python para a própria análise. Isto torna a análise preliminar útil para verificar dados introduzidos pelo utilizador antes de uma operação demorada ou com credenciais.

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".

Por predefinição, maxTimeHours é 96 e aceita um número positivo até 96, incluindo frações de hora. No prazo limite, o Codex Security interrompe os trabalhadores inacabados, conserva os resultados das análises concluídas e agrega-os no relatório final. Reveja result.coverage.completeness antes de considerar uma análise com limite de tempo como prova de cobertura completa.

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 a despesa, mas não é um limite rígido, pelo que os pedidos já em curso podem terminar ligeiramente acima do mesmo. Se uma análise aprofundada atingir o limite depois de o Codex Security agregar os resultados concluídos dos trabalhadores, run devolve um resultado com coverage.completeness definido como "partial" e comunica o aviso de orçamento através de onWarning.

Se a análise não conseguir produzir um resultado parcial concluído, run lança ScanCostLimitExceededError e preserva qualquer saída disponível.

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

A completude da cobertura é complete, partial ou unknown. Reveja as superfícies adiadas, exclusões e questões em aberto antes de utilizar uma análise como prova para uma decisão de segurança.

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);

Transmita um AbortSignal quando o cancelamento provier de um pedido, controlador de tarefas ou tempo limite:

const controller = new AbortController();

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

  controller.abort();
  await scan;
} 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

Transmita a configuração do runtime quando precisar de um plugin, interpretador ou definição específica do Codex:

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

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 fornece 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 baseado em ficheiros. As API keys são adequadas para CI e automatizaçã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.