SDK de TypeScript de Codex Security

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

El SDK usa módulos ECMAScript (ESM) y se ejecuta del lado del servidor con Node.js 22 (22.13.0 o una versión posterior), 24 o 26. Los análisis también requieren Python 3.10 o una versión posterior. Python 3.10 también requiere el paquete tomli.

Configurar el SDK

Instala el SDK:

npm install @openai/codex-security

Antes de iniciar un análisis, define OPENAI_API_KEY o CODEX_API_KEY, usa un inicio de sesión existente de Codex almacenado en un archivo o configura otro proveedor. Amazon Bedrock usa credenciales de AWS; OpenRouter y Fireworks usan claves de API y configuración específicas de cada proveedor.

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

Ejecutar un análisis

Analiza solo repositorios en los que confíes y que tengas permiso para evaluar. El SDK se ejecuta con los permisos de tu sistema operativo local y nunca se detiene para solicitar aprobación. Los procesos de análisis pueden heredar tu entorno, así que elimina las credenciales no relacionadas antes de comenzar. Consulta Permisos de análisis locales.

Crea un único cliente CodexSecurity, ejecuta un análisis estándar del repositorio y cierra el cliente cuando termine el trabajo. Pasa outputDir para elegir un directorio privado de resultados fuera del worktree de Git que contiene el repositorio.

Si omites outputDir, Codex Security guarda los resultados en su propio directorio de estado persistente. Los resultados pueden incluir fragmentos del código fuente y detalles de vulnerabilidades, así que elige permisos y políticas de retención adecuados.

import { CodexSecurity } from "@openai/codex-security";

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 termine, valida los artefactos sellados y devuelve un ScanResult. close libera el entorno de ejecución aislado y admite llamadas repetidas.

Comprobar las entradas con preflight

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

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

Preflight no modifica el entorno de ejecución ni las credenciales de Codex. También deja la detección del complemento y de Python para el análisis en sí. Esto hace que preflight resulte útil para comprobar las entradas del usuario antes de una operación de larga duración 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 valor archiveDir devuelto permite anticipar el nombre del directorio archivado. La ruta final puede ser diferente porque run genera su propio destino único. Captura la ruta real del directorio archivado 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 objetivos de repositorio, ruta, diff de commits y árbol de trabajo. El objetivo predeterminado es el repositorio completo.

Analizar rutas seleccionadas

Pasa un arreglo de rutas dentro 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:

import { DiffTarget } from "@openai/codex-security";

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

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

El valor predeterminado de head es HEAD. Los objetivos de diff requieren que el argumento del repositorio sea la raíz del worktree de Git.

Analizar el árbol de trabajo

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

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

El valor predeterminado de la base es HEAD. Recupera las revisiones seleccionadas antes de iniciar un análisis de diff o del árbol de trabajo.

Seleccionar el modo profundo

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

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

El modo profundo admite objetivos de repositorio y ruta. Usa el modo estándar para los análisis de diff y del árbol de trabajo. La configuración opcional controla los workers independientes y simultáneos de análisis estándar, los subagentes por worker, los análisis consecutivos completados por los workers sin nuevos hallazgos y la cantidad total y la duración de sus ejecuciones. Estos parámetros requieren mode: "deep".

El valor predeterminado de maxTimeHours es 96 y acepta un número positivo de hasta 96, incluidas las fracciones de hora. Cuando se cumple el plazo, Codex Security detiene los workers que no finalizaron, conserva los resultados de los análisis completados y los integra en el informe final. Revisa result.coverage.completeness antes de considerar un análisis con límite de tiempo como evidencia de una cobertura completa.

Agregar 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 realiza búsquedas recursivas en los directorios. Los formatos de documento compatibles son .md, .markdown, .txt, .pdf y .docx. El SDK rechaza las rutas de entrada enlazadas, omite las entradas enlazadas de los directorios y mantiene el contenido extraído de los documentos fuera de los resultados guardados del análisis.

Agregar instrucciones de análisis y seguimiento

Usa scanPrompt para orientar el análisis y postScanPrompt para solicitar un seguimiento:

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.",
});

Si el seguimiento falla, el SDK conserva el análisis completado e informa el error mediante onWarning. Restaura todos los artefactos del análisis completado que el seguimiento haya modificado.

Establecer un presupuesto para el análisis

Establece maxCostUsd para detener un análisis cuando el costo estimado del modelo supere un límite. Usa onCost para hacer un seguimiento del costo 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 estima el gasto, pero no establece un tope estricto, por lo que las solicitudes ya en curso pueden finalizar con un costo ligeramente superior. Si un análisis profundo alcanza el límite después de que Codex Security integra los resultados completados por los workers, run devuelve un resultado con coverage.completeness establecido en "partial" y notifica la advertencia de presupuesto mediante onWarning.

Si el análisis no puede generar un resultado parcial finalizado, run lanza ScanCostLimitExceededError y conserva cualquier salida disponible.

Trabajar con los resultados del análisis

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

Para exigir el mismo complemento en un análisis posterior, pasa expectedPluginVersion: result.pluginVersion. El SDK rechaza el análisis si la versión instalada del complemento es diferente.

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

Los hallazgos pueden incluir los campos opcionales codeEvidence, rootCause, validation, attackPath, remediationTests y preventiveControls.

Para los hallazgos de todo el repositorio, confirmedInLatestScan distingue los hallazgos detectados en el análisis más reciente de los hallazgos anteriores que siguen abiertos:

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

El grado de integridad de la cobertura es complete, partial o unknown. Revisa las superficies pospuestas, las exclusiones y las preguntas abiertas antes de usar un análisis como evidencia para una decisión de seguridad.

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

Supervisar o cancelar un análisis

Pasa funciones de devolución de llamada de ScanOptions para informar sobre el inicio del análisis, el progreso de los workers y los reintentos de conexión:

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

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

import { ScanInterruptedError } from "@openai/codex-security";

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 datos de salida parciales en scanDir. Conserva ese directorio cuando sea necesario investigar el resultado.

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

El estado de Trusted Access es granted, not_granted o unknown. Si no hay acceso o su estado es desconocido, también se activa onWarning.

onSessionEvent recibe eventos cuyo contenido no se ha ocultado y que pueden contener código fuente o credenciales. Fíltralos antes de enviarlos a registros compartidos u otros servicios.

Configurar el entorno de ejecución y las credenciales

Pasa la configuración del entorno de ejecución cuando necesites un complemento, un intérprete o una configuración específica de 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 acepta el directorio de un complemento o un archivo ZIP. pythonPath selecciona el intérprete del complemento. codexOverrides combina los valores admitidos en la configuración aislada de Codex. Los análisis usan gpt-5.6-sol con un esfuerzo de razonamiento muy alto de forma predeterminada. Establece model y model_reasoning_effort en codexOverrides para usar otro modelo u otro nivel de esfuerzo de razonamiento. Para usar Amazon Bedrock, establece model_provider y model en codexOverrides.

codexOverrides no puede restringir el acceso del análisis al sistema de archivos ni cambiar su política de aprobación. Consulta Permisos de análisis locales.

Para OpenRouter o Fireworks, proporciona también la clave de API correspondiente y una configuración completa del proveedor en codexOverrides. Por ejemplo, establece OPENROUTER_API_KEY y configura 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 Fireworks, cambia ambas claves openrouter por fireworks, establece name en Fireworks AI, establece env_key en FIREWORKS_API_KEY, usa https://api.fireworks.ai/inference/v1 como base_url y selecciona un modelo de Fireworks.

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

Un objeto de inicio de sesión proporciona waitForInstructions, authUrl, verificationUrl, userCode, wait y cancel para que una aplicación pueda mostrar y completar el flujo de inicio de sesión seleccionado. El SDK puede reutilizar un inicio de sesión de Codex almacenado en un archivo. Las claves de API son una opción útil para CI y la automatización del lado del servidor.

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

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

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

Controlar los errores del análisis

Captura la clase de error exportada que corresponda a la acción que tu aplicación pueda realizar:

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