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 de desarrollo. 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 usa módulos ECMAScript (ESM) y se ejecuta en el servidor con Node.js 24 o 26, o con Node.js 22 a partir de 22.13.0. El análisis también requiere Python 3.10 o 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 respaldado por archivos o configura otro proveedor. Amazon Bedrock usa credenciales de AWS; OpenRouter y Fireworks usan API keys y configuraciones específicas del proveedor.

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

Ejecutar un análisis

El SDK se ejecuta con tus permisos del sistema operativo local y no se detiene para solicitar aprobación. Los procesos de análisis pueden heredar tu entorno, así que elimina las credenciales que no sean necesarias antes de comenzar. Consulta Permisos de análisis local.

Guarda este ejemplo como scan.mjs. Sustituye las rutas, 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 que contiene el repositorio.

Si omites outputDir, Codex Security guarda los resultados en su propio directorio de estado persistente. Los resultados pueden incluir fragmentos de código fuente y detalles de vulnerabilidades. Establece quién puede leerlos y cuánto tiempo se conservarán.

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

Ejecútalo con Node.js:

node scan.mjs

El ejemplo muestra la ruta del informe, el estado del análisis y el número de hallazgos. Abre el informe para revisar las pruebas. El número varía según el repositorio y el análisis, así que no uses un número esperado para comprobar si la integración funciona.

run valida los artefactos guardados y devuelve un ScanResult cuando result.manifest.scan.status es "completed". Consulta result.coverage para ver las áreas revisadas, las exclusiones y el trabajo pospuesto. Un análisis completado aún puede tener lagunas en la cobertura. Los fallos de ejecución, de entrada o de integridad de los resultados pueden generar un error.

En los ejemplos posteriores, reutiliza el cliente security abierto y mantén close() en finally para liberar el entorno de ejecución. Añade las importaciones adicionales al principio de scan.mjs.

Comprobar las entradas con una verificación previa

Usa preflight para comprobar un repositorio, objetivo, modo, documentos de la base de conocimientos, 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"],
  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);

La comprobación previa verifica las entradas locales sin iniciar Codex, cargar credenciales ni comprobar la disponibilidad de Python y del plugin. Una comprobación previa satisfactoria no demuestra que el análisis pueda autenticarse o iniciarse.

Para obtener una vista previa del archivado de un directorio de resultados existente, define 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 directorio de archivado. La ruta final puede ser diferente porque run genera su propio destino único. Captura la ruta real del directorio de 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, diferencias confirmadas y árbol de trabajo. El objetivo predeterminado es el repositorio completo.

Analizar rutas seleccionadas

Pasa una matriz 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:

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

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

El valor predeterminado de la revisión de destino es HEAD. 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 de 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 diferencias o del árbol de trabajo.

Seleccionar el modo profundo

Define 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",
  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 diferencias y del árbol de trabajo. La configuración opcional controla los trabajadores simultáneos e independientes de análisis estándar, los subagentes por trabajador, los análisis consecutivos completados por un trabajador sin nuevos hallazgos y el número y la duración totales de las ejecuciones de los trabajadores. Requiere mode: "deep".

maxTimeHours tiene el valor predeterminado 96 y acepta un número positivo hasta 96, incluidas fracciones de hora. Al llegar al límite de tiempo, Codex Security detiene los procesos de trabajo sin finalizar, conserva los resultados de los análisis completados y los integra en el informe final. Revisa result.coverage para consultar el trabajo pospuesto y las preguntas pendientes.

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 recursivamente en los directorios. 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 de análisis guardados.

Añadir 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 del error mediante onWarning. Restaura todos los artefactos del análisis completado que el seguimiento haya modificado.

Definir un presupuesto de análisis

Define 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 estima el gasto, pero no es un tope estricto, por lo que las solicitudes que ya están en curso pueden finalizar ligeramente por encima de él. Si un análisis profundo alcanza el límite después de que Codex Security integre los resultados completados de los procesos de trabajo, run puede devolver un resultado con manifest.scan.status establecido en "completed" y comunicar la advertencia sobre el presupuesto a través de onWarning. Consulta result.coverage para ver el trabajo que quedó sin finalizar.

Si el análisis no puede producir un resultado completado válido, run genera 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 plugin en un análisis posterior, pasa expectedPluginVersion: result.pluginVersion. El SDK rechaza el análisis si la versión instalada del plugin 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 observados 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);
}

Los resultados nuevos no incluyen coverage.completeness. Usa manifest.scan.status para conocer el estado de ejecución y revisa las áreas pospuestas, las exclusiones y las preguntas pendientes en coverage para comprender qué revisó el análisis.

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

Seguir o cancelar un análisis

Pasa devoluciones de llamada ScanOptions para informar sobre el inicio del análisis, el progreso de los trabajadores 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 desde tu controlador de solicitudes o trabajos para cancelar un análisis. Si el análisis sigue ejecutándose después de 30 minutos, este ejemplo lo interrumpe y muestra el directorio que contiene cualquier salida guardada:

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

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:

El estado de Trusted Access es granted, not_granted o unknown. La ausencia de acceso o un acceso desconocido también activa onWarning.

onSessionEvent recibe eventos que no ocultan información confidencial y 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

Proporciona la configuración del entorno de ejecución cuando necesites un plugin, un intérprete o un ajuste de Codex específicos. Elige un modelo al que tus credenciales permitan acceder. Si inicias sesión con ChatGPT, consulta la disponibilidad de GPT-6.1 Sol antes de usar este ejemplo:

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

Para OpenRouter o Fireworks, proporciona también la API key correspondiente y una configuración completa del proveedor en codexOverrides. Por ejemplo, define 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 a fireworks, define name como Fireworks AI, define env_key como 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 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 almacenado en archivos. Usa API keys para CI y automatización del lado del servidor.

Cuando hay disponibles una API key y un inicio de sesión almacenado, el SDK usa la API key de forma predeterminada. 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",
});

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

Gestionar errores de análisis

Captura la clase de error exportada que corresponda a 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.