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 conclusões tipadas, detalhes de cobertura e caminhos para artefactos de análise. Para análises mais longas, suporta verificações prévias, limites de custos, callbacks de progresso e cancelamento.

O SDK utiliza módulos ECMAScript (ESM) e é executado no servidor com Node.js 22 ou posterior. A análise também requer Python 3.10 ou posterior.

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 o Amazon Bedrock com credenciais AWS e substituições explícitas de model_provider e model.

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

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

Se omitir outputDir, o Codex Security guarda os resultados no seu próprio diretório de estado persistente. 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 verificação prévia

Utilize preflight para verificar um repositório, alvo, modo, 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"],
  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 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 verificação prévia útil para validar a entrada do utilizador antes de uma operação longa ou que utilize 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 efetivo 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

Forneça 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 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 cabeça é HEAD. Os alvos de diferenças exigem que o argumento do repositório seja a raiz da árvore de trabalho Git.

Analisar a árvore de trabalho

Utilize DiffTarget.workingTree para analisar alterações preparadas e não preparadas relativamente 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",
});

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.

Adicionar uma base de conhecimentos de segurança

Forneça 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.

Definir um orçamento de análise

Defina maxCostUsd para parar uma análise quando o custo estimado do modelo exceder um limite. Utilize onCost para acompanhar o custo durante a execução da 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 é uma estimativa, não um limite máximo rígido de despesa. Os pedidos já em curso podem terminar acima do mesmo. Se a análise exceder o limite, o SDK lança ScanCostLimitExceededError e preserva os resultados disponíveis.

Trabalhar com resultados de análises

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

Utilize diretamente as conclusõ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);
}

A completude da cobertura é complete, partial ou unknown. Reveja as superfícies adiadas, as exclusões e as 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 conclusões, a cobertura, os identificadores da análise e do tópico, reportPath, artifactsDir, sarifPath e os metadados do turno num único objeto preparado para JSON.

Acompanhar ou cancelar uma análise

Forneça 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");
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onReconnect(attempt, maxAttempts) {
    console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
  },
  onObserverError(observer, error) {
    console.error(`${observer} failed`, error);
  },
});

console.log(result.reportPath);

Forneça um AbortSignal quando o cancelamento for proveniente de um pedido, controlador de tarefas ou limite de tempo:

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 do ciclo de vida ScanOptions:

Configurar o runtime e as credenciais

Forneça a configuração do runtime quando necessitar 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 de plugins ou ZIP. 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 esforço de raciocínio extra-alto. 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.

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 guardado, 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 de ambiente. preflight aceita a mesma opção auth.

Processar erros de análise

Capture a classe de erro exportada correspondente à ação que a sua aplicação pode tomar:

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