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 22 (22.13.0 o posterior), 24 o 26. 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 concede Trusted Access.

Ejecutar un análisis

Analiza únicamente repositorios en los que confíes y para los que tengas permiso de evaluación. El SDK se ejecuta con los permisos locales de tu sistema operativo 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 los análisis locales.

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 que lo contiene.

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 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 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 verificación previa no modifica el entorno de ejecución de Codex ni las credenciales. También deja el descubrimiento del plugin y de Python para el propio análisis. Esto hace que la verificación previa sea ú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, 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 archivo. La ruta final puede ser diferente 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 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 rama de origen 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".

El valor predeterminado de maxTimeHours es 96 y acepta un número positivo de hasta 96, incluidas fracciones de hora. Al llegar al plazo, Codex Security detiene los trabajadores sin finalizar, conserva los resultados de análisis completados y los agrega al informe final. Revisa result.coverage.completeness antes de considerar un análisis con límite de tiempo como prueba de cobertura completa.

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 agregue los resultados completados de los trabajadores, run devuelve un resultado con coverage.completeness definido como "partial" e informa de la advertencia de presupuesto mediante onWarning.

Si el análisis no puede generar un resultado parcial completado, 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);
}

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

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 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:

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 están censurados 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

Pasa la configuración del entorno de ejecución cuando necesites un plugin, 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 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 acceso seleccionado. El SDK puede reutilizar un inicio de sesión de Codex respaldado por archivos. Las API keys son una opción adecuada para CI y la automatización en el 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.