SDK de TypeScript de Codex Security

Usa el SDK de TypeScript de Codex Security para ejecutar análisis de seguridad en repositorios y cambios de código desde tu aplicación o herramienta para desarrolladores. El SDK devuelve hallazgos tipados, detalles de cobertura y rutas a los artefactos del análisis. Para análisis más largos, admite comprobaciones previas, límites de costes, devoluciones de llamada de progreso y cancelación.

El SDK utiliza módulos ECMAScript (ESM) y se ejecuta en el servidor con Node.js 22 o posterior. El análisis también requiere Python 3.10 o posterior.

Configurar el SDK

Instala el SDK:

npm install @openai/codex-security

Antes de iniciar un análisis, establece OPENAI_API_KEY o CODEX_API_KEY, usa un inicio de sesión existente de Codex respaldado por archivos o configura Amazon Bedrock con credenciales de AWS y reemplazos explícitos de model_provider y model.

Para obtener los mejores resultados, usa una cuenta verificada para Trusted Access for Cyber. Iniciar sesión o proporcionar una API key no concede Trusted Access.

Ejecutar un análisis

Crea un cliente CodexSecurity, ejecuta un análisis estándar del repositorio y cierra el cliente cuando finalice el trabajo. Pasa outputDir para elegir un directorio privado de resultados fuera del árbol de trabajo de Git contenedor.

Si omites outputDir, Codex Security guarda los resultados en su propio directorio de estado persistente. Los resultados pueden incluir extractos del código fuente y detalles de vulnerabilidades, por lo que debes elegir permisos y políticas de conservación adecuados.

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 el análisis, espera a que finalice, valida los artefactos sellados y devuelve un ScanResult. close libera el entorno de ejecución aislado y admite llamadas repetidas.

Comprobar las entradas mediante la comprobación previa

Usa preflight para comprobar un repositorio, objetivo, modo, ubicación de salida y configuración de Codex antes de iniciar un análisis:

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

La comprobación previa no modifica el entorno de ejecución ni las credenciales de Codex. También deja el descubrimiento de complementos y Python para el propio análisis. Esto hace que la comprobación previa resulte útil para comprobar la entrada del usuario antes de una operación larga o que requiera credenciales.

Para obtener una vista previa del archivado de un directorio de resultados existente, establece archiveExisting: true:

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

console.log(plan.archiveDir);

El archiveDir devuelto muestra una vista previa del nombre del archivo. La ruta final puede ser distinta porque run genera su propio destino único. Captura la ruta real del archivo con onOutputArchived:

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

El análisis archiva los resultados anteriores y comienza con un directorio de salida vacío.

Elegir un objetivo de análisis

El SDK admite como objetivos repositorios, rutas, diferencias confirmadas y árboles de trabajo. El objetivo predeterminado es el repositorio completo.

Analizar rutas seleccionadas

Pasa una matriz de rutas del repositorio:

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

Las rutas pueden identificar archivos o directorios. El SDK resuelve cada ruta dentro del repositorio y elimina los duplicados.

Analizar cambios confirmados

Usa DiffTarget.refs para analizar los cambios confirmados entre dos revisiones de Git disponibles localmente:

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

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

La cabecera usa HEAD de forma predeterminada. Los objetivos de diferencias requieren que el argumento del repositorio sea la raíz del árbol de trabajo de Git.

Analizar el árbol de trabajo

Usa DiffTarget.workingTree para analizar los cambios preparados y no preparados respecto a una revisión base:

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

La base usa HEAD de forma predeterminada. Obtén las revisiones seleccionadas antes de iniciar un análisis de diferencias o del árbol de trabajo.

Seleccionar el modo profundo

Establece mode: "deep" para un análisis de repositorio o ruta que necesite una revisión más amplia:

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

El modo profundo admite objetivos de repositorio y ruta. Usa el modo estándar para los análisis de diferencias y del árbol de trabajo.

Añadir una base de conocimientos de seguridad

Pasa documentos de arquitectura, modelos de amenazas o políticas de seguridad mediante knowledgeBasePaths:

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

El SDK acepta archivos o directorios y busca en los directorios de forma recursiva. Los formatos de documento admitidos son .md, .markdown, .txt, .pdf y .docx. El SDK rechaza las rutas de entrada enlazadas, omite las entradas enlazadas de directorios y mantiene el contenido extraído de los documentos fuera de los resultados guardados del análisis.

Establecer un presupuesto de análisis

Establece maxCostUsd para detener un análisis cuando el coste estimado del modelo supere un límite. Usa onCost para hacer un seguimiento del coste mientras se ejecuta el análisis:

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

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

El límite es una estimación, no un tope estricto de gasto. Las solicitudes ya en curso pueden finalizar por encima de él. Si el análisis supera el límite, el SDK produce ScanCostLimitExceededError y conserva los resultados disponibles.

Trabajar con los resultados del análisis

ScanResult expone los documentos estructurados, los metadatos del análisis y las rutas de los artefactos:

Usa directamente los hallazgos estructurados y la 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);
}

La exhaustividad de la cobertura es complete, partial o unknown. Revisa las superficies aplazadas, las exclusiones y las preguntas abiertas antes de usar un análisis como prueba para una decisión de seguridad.

result.toJSON() devuelve el manifiesto, los hallazgos, la cobertura, los identificadores del análisis y del hilo, reportPath, artifactsDir, sarifPath y los metadatos del turno en un objeto listo para JSON.

Seguir o cancelar un análisis

Pasa devoluciones de llamada ScanOptions para informar del inicio del análisis, el progreso de los procesos de trabajo y los reintentos de conexión:

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

Pasa un AbortSignal cuando la cancelación proceda de una solicitud, un controlador de trabajos o un tiempo de espera:

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

Un análisis interrumpido puede dejar una salida parcial en scanDir. Conserva ese directorio cuando sea necesario investigar el resultado.

Las aplicaciones que muestran el progreso de configuración del análisis también pueden usar las devoluciones de llamada del ciclo de vida ScanOptions:

Configurar el entorno de ejecución y las credenciales

Pasa la configuración del entorno de ejecución cuando necesites un complemento, intérprete o ajuste de Codex específico:

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 acepta un directorio o ZIP de complemento. pythonPath selecciona el intérprete del complemento. codexOverrides combina los valores admitidos con la configuración aislada de Codex. Los análisis usan gpt-5.6-sol con un esfuerzo de razonamiento extraalto de forma predeterminada. Establece model y model_reasoning_effort en codexOverrides para usar un modelo o esfuerzo de razonamiento distinto. Para usar Amazon Bedrock, establece model_provider y model en codexOverrides.

El cliente también expone métodos de autenticación admitidos:

Un identificador de inicio de sesión proporciona waitForInstructions, authUrl, verificationUrl, userCode, wait y cancel para que una aplicación pueda presentar y completar el flujo de inicio de sesión seleccionado. El SDK puede reutilizar un inicio de sesión de Codex respaldado por archivos. Las API key son adecuadas para CI y la automatización del lado del servidor.

Cuando están disponibles tanto una API key como un inicio de sesión almacenado, el SDK usa de forma predeterminada la API key. Para usar en su lugar tu inicio de sesión de ChatGPT, selecciónalo para el análisis:

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

Establece auth: "api-key" para exigir una API key del entorno. preflight acepta la misma opción auth.

Gestionar los errores de análisis

Captura la clase de error exportada que coincida con la acción que tu aplicación pueda realizar:

Continúa con la guía de inicio rápido de la CLI, la guía de CI o la referencia de la CLI.