SDK de TypeScript de Codex Security

Usa el SDK de TypeScript de Codex Security para analizar la seguridad de repositorios y cambios de código desde tu aplicación o herramienta de desarrollo. El SDK devuelve hallazgos tipados, el archivo de manifiesto del análisis y las rutas de los informes guardados.

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

Para leer o reanudar sesiones comprimidas de Codex (.jsonl.zst), usa Node.js 22.15.0 o una versión posterior de la serie 22.x, o bien Node.js 24 o 26. Las sesiones .jsonl sin comprimir funcionan en todas las versiones compatibles de Node.js.

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 una sesión de Codex existente guardada en un archivo o configura otro proveedor. Amazon Bedrock usa credenciales de AWS. OpenRouter y Fireworks usan claves de API y configuraciones específicas de cada proveedor.

Algunas solicitudes de ciberseguridad y algunos hallazgos protegidos requieren que tu cuenta de ChatGPT o tu organización de API tenga Trusted Access for Cyber.

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 ajenas al análisis antes de empezar. Consulta los permisos de los análisis locales.

Guarda este ejemplo como scan.mjs. Pasa la ruta del repositorio y la del directorio de resultados como argumentos de la línea de comandos. Ejecuta un análisis estándar del repositorio y cierra el cliente cuando termine. Pasa outputDir para elegir un directorio privado de resultados fuera del worktree de Git que contiene el código que vas a analizar.

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. Define quién puede leerlos y durante cuánto tiempo se conservarán.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { CodexSecurity } from "@openai/codex-security";

const [repository, outputDir] = process.argv.slice(2);
if (!repository || !outputDir) {
  throw new Error("Usage: node scan.mjs <repository> <results-directory>");
}
const security = new CodexSecurity();

try {
  const result = await security.run(repository, {
    outputDir,
  });

  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 /path/to/repository /path/outside/repository/results

El ejemplo muestra la ruta del informe, el estado del análisis y la cantidad de hallazgos. Abre el informe para revisar la evidencia.

run valida los artefactos guardados y devuelve un ScanResult cuando result.manifest.scan.status es "completed". Consulta result.manifest.scan.scope para ver el objetivo solicitado y result.manifest.scan.warnings para ver si hay advertencias. El estado de finalización por sí solo no indica qué archivos se revisaron. Los fallos de ejecución, de entrada o de integridad de los resultados pueden generar un error.

En los siguientes ejemplos, reutiliza el cliente security abierto y conserva la llamada a close() en finally para liberar el entorno de ejecución. Agrega las importaciones adicionales al inicio de scan.mjs.

Verificar las entradas antes del análisis

Usa preflight para verificar el repositorio, el objetivo, el 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. Este ejemplo lee security.md desde la raíz del repositorio:

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

const plan = await security.preflight(repository, {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: [knowledgeBase],
  outputDir: outputDir,
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

La verificación previa comprueba las entradas locales sin iniciar Codex, cargar credenciales ni verificar la disponibilidad de Python y del complemento. Aunque la verificación previa se complete correctamente, esto no garantiza que el análisis pueda autenticarse o iniciarse.

Para ver de antemano dónde se archivaría un directorio de resultados existente, configura archiveExisting: true:

1
2
3
4
5
6const plan = await security.preflight(repository, {
  outputDir: outputDir,
  archiveExisting: true,
});

console.log(plan.archiveDir);

El valor devuelto en archiveDir muestra cómo se asignará el nombre al directorio de archivo. La ruta final puede ser distinta porque run genera su propio destino único. Obtén la ruta real con onOutputArchived:

1
2
3
4
5
6
7
8
9
10
11try {
  await security.run(repository, {
    outputDir: outputDir,
    archiveExisting: true,
    onOutputArchived(archiveDir) {
      console.log("Archived results:", archiveDir);
    },
  });
} finally {
  await security.close();
}

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

Elegir qué analizar

El SDK puede analizar un repositorio, rutas específicas, diferencias entre commits o cambios en el árbol de trabajo. De forma predeterminada, analiza todo el repositorio.

Analizar rutas seleccionadas

Pasa un arreglo de rutas dentro del repositorio:

1
2
3
4
5
6
7try {
  const result = await security.run(repository, {
    target: ["services/billing", "packages/auth"],
  });
} finally {
  await security.close();
}

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

Analizar cambios registrados en commits

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

1
2
3
4
5
6
7
8
9
10
11
12import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "HEAD~1",
  head: "HEAD",
});

try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

La revisión final predeterminada es HEAD. Pasa la raíz del worktree de Git como repositorio y cambia a la revisión final solicitada antes de iniciar el análisis.

Analizar el árbol de trabajo

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

1
2
3
4
5
6
7import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.workingTree({ base: "HEAD" });
try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

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

Seleccionar el modo profundo

Configura mode: "deep" cuando el análisis de un repositorio o de rutas específicas requiera una revisión más amplia:

1
2
3
4
5
6
7
8
9
10
11
12
13try {
  const result = await security.run(repository, {
    target: ["services/billing"],
    mode: "deep",
    workers: 2,
    subagents: 0,
    stopAfterNoNew: 3,
    maxDiscoveryRuns: 10,
    maxTimeMinutes: 90,
  });
} finally {
  await security.close();
}

El modo profundo permite analizar repositorios y rutas. Usa el modo estándar para analizar diferencias o el árbol de trabajo. En el modo profundo, workers limita la cantidad de procesos de análisis que se ejecutan a la vez y subagents establece la cantidad de subagentes por proceso. stopAfterNoNew detiene la búsqueda cuando se alcanza el número indicado de ejecuciones consecutivas sin hallazgos nuevos. maxDiscoveryRuns limita el número total de ejecuciones de esos procesos.

Configura maxTimeMinutes para limitar la duración de la búsqueda en modo profundo. El valor predeterminado y el máximo son 5760 minutos (96 horas). Cuando se cumple el plazo, la búsqueda se detiene y el SDK combina los resultados de los procesos que terminaron. En los análisis estándar, maxTimeMinutes indica un plazo orientativo para la investigación. La generación del informe puede terminar más tarde. La validación personalizada y las instrucciones posteriores al análisis se ejecutan fuera de ese plazo.

Agregar una base de conocimientos de seguridad

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

1
2
3
4
5
6
7
8
9
10
11import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

try {
  const result = await security.run(repository, {
    knowledgeBasePaths: [knowledgeBase],
  });
} finally {
  await security.close();
}

El SDK acepta archivos o directorios y busca en los directorios de forma recursiva. Los formatos compatibles incluyen texto UTF-8 (incluidos JSON y SARIF), PDF y DOCX. El SDK rechaza las rutas de entrada que son enlaces y omite las entradas de directorio que son enlaces.

El SDK guarda el texto extraído de los documentos en el archivo privado .scan-knowledge.json, junto a los artefactos del análisis. Consérvalo en el directorio del análisis. Al reanudar un análisis profundo interrumpido, codex-security scans resume usa ese texto guardado aunque los documentos originales hayan cambiado o se hayan eliminado. Los informes canónicos no incluyen el texto de los documentos.

Agregar instrucciones para el análisis y el seguimiento

Usa scanPrompt para orientar el análisis y postScanPrompt para solicitar una tarea de seguimiento:

1
2
3
4
5
6
7
8try {
  const result = await security.run(repository, {
    scanPrompt: "Focus on tenant isolation and authorization checks.",
    postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
  });
} finally {
  await security.close();
}

Si la tarea de seguimiento falla, el SDK conserva el análisis completado e informa del error mediante onWarning. También restaura los artefactos del análisis completado que la tarea haya modificado. La tarea de seguimiento se ejecuta después de que el SDK deja de registrar los costos del análisis y queda fuera del límite de maxCostUsd.

Validar hallazgos en tu entorno

Pasa validationPrompt para comprobar posibles hallazgos con tu propio procedimiento de prueba. Por ejemplo, indica en el prompt la ruta de un script que controles y que esté fuera de la copia de trabajo. Ejecútalo contra tu servidor de pruebas local. Pasa la ruta del script de validación y la URL del servidor después de los argumentos que indican el repositorio y el directorio de resultados:

1
2
3
4
5
6
7const [validationScript, validationUrl] = process.argv.slice(4);
if (!validationScript || !validationUrl)
  throw new Error("Pass a validation script path and service URL.");
const result = await security.run(repository, {
  outputDir,
  validationPrompt: `Run ${validationScript} against ${validationUrl} and report which findings reproduce.`,
});

node scan.mjs /path/to/repository /path/outside/repository/results /path/to/validate.sh http://localhost:3000

Usa validationPrompt en análisis estándar de repositorios, rutas, diferencias entre commits o árboles de trabajo. Para usar el mismo procedimiento en cada análisis estándar de componentes, pasa scanOptions.validationPrompt a runComponentScans. Los análisis profundos rechazan la validación personalizada.

Establecer un presupuesto para el análisis

Configura maxCostUsd para detener el análisis cuando el costo estimado del modelo supere un límite. Usa onCost para seguir el costo durante el análisis y mostrar estimatedUsdRange:

1
2
3
4
5
6
7
8
9
10
11
12try {
  const result = await security.run(repository, {
    maxCostUsd: 5,
    onCost(cost) {
      console.log(cost.estimatedUsdRange);
    },
  });

  console.log(result.cost?.estimatedUsdRange);
} finally {
  await security.close();
}

El límite se basa en estimatedUsd, la estimación de referencia para contextos cortos. Las solicitudes que ya están en curso pueden hacer que la estimación supere el límite. Los precios para contextos largos pueden elevar estimatedUsdRange por encima de ese límite. Este límite no establece un tope de facturación.

Si un análisis profundo alcanza el límite después de que Codex Security combina los resultados de los procesos que terminaron, run puede devolver un resultado con manifest.scan.status establecido en "completed" y emitir una advertencia sobre el presupuesto mediante onWarning.

Si el análisis no puede producir un resultado final válido, run lanza ScanCostLimitExceededError y conserva los datos de salida disponibles.

Analizar los componentes del proyecto

Usa runComponentScans para analizar servicios o paquetes en paralelo y combinar sus hallazgos. Asigna a cada componente un nombre y una o más rutas relativas al repositorio. Elige un directorio de salida nuevo o vacío fuera del worktree de Git que contiene el código que vas a analizar.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { runComponentScans } from "@openai/codex-security";

const result = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  components: [
    { name: "API", paths: ["services/api", "packages/auth"] },
    { name: "Web", paths: ["services/billing"] },
  ],
  workers: 2,
  onProgress: ({ name, status }) => console.log(name, status),
});

console.log(result.reportPath);
if (result.failed > 0) {
  throw new Error(`${result.failed} component scans failed.`);
}

Configura workers para controlar cuántos componentes se analizan a la vez. El valor predeterminado es cuatro.

Para que Codex proponga los componentes, pasa auto: true en lugar de components. Agrega planOnly: true para guardar el plan en components.json sin ejecutar ningún análisis:

1
2
3
4
5
6
7
8
9
10import { runComponentScans } from "@openai/codex-security";

const plan = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  auto: true,
  planOnly: true,
});

console.log(plan.planPath);

Si al terminar la ejecución hay componentes cuyo análisis falló, lee el archivo JSON en result.retryPlanPath. Pasa su arreglo components a runComponentScans con un nuevo outputDir. El informe del reintento solo abarca esos componentes. Revisa los informes de ambas ejecuciones.

Trabajar con los resultados del análisis

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

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

Lee la gravedad y la primera ubicación en el código fuente de cada hallazgo:

1
2
3
4
5
6
7
8
9
10for (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
  );
}

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

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

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

Usa result.toJSON() para serializar el archivo de manifiesto, los hallazgos, las exclusiones de revisión registradas, las rutas de los artefactos y los metadatos del turno.

Leer modelos de amenazas guardados

Comprueba si threatModel y threatModelPath tienen el valor null antes de usarlos. Puedes exportar un modelo guardado aunque Codex Security no haya podido escribir su archivo Markdown. Usa la ruta que devuelve la exportación en lugar de dar por hecho el nombre del archivo.

Exportar artefactos guardados

Exporta los resultados guardados sin iniciar Codex, cargar credenciales ni llamar a un modelo. Este ejemplo exporta un modelo de amenazas guardado a la salida estándar. Pasa la ruta de un directorio de resultados de análisis existente como primer argumento de la línea de comandos:

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { exportArtifact } from "@openai/codex-security";

const directory = process.argv[2];
if (!directory) {
  throw new Error(
    "Pass an existing scan results directory as the first argument."
  );
}

await exportArtifact({
  source: { directory },
  artifact: "threat-model",
  output: "-",
});

Para seleccionar un análisis guardado por su ID, usa source: { scanId: "SCAN_ID" }. Asigna a output una ruta de destino para guardar el artefacto en un archivo.

Los modelos de amenazas se exportan en formato Markdown. La exportación devuelve un error si el análisis no tiene un modelo de amenazas guardado. Para exportar hallazgos, configura artifact: "findings" y elige format: "sarif" (el formato predeterminado), "json", "csv" o "servicenow-avit".

El resultado incluye la ruta de salida en path y, si exportas el modelo de amenazas a un archivo, los datos de procedencia en provenance, obtenidos de los mismos resultados guardados. Ambos campos tienen el valor null cuando output: "-" escribe en la salida estándar. La exportación requiere Python 3.10 o posterior.

Para usar ServiceNow Manual AVIT Ingestion, configura artifact: "findings" y format: "servicenow-avit". Prepara la plantilla de la aplicación y pasa su ruta como valor de avitTemplate. Asigna a output la ruta donde se guardará el archivo CSV, en una ubicación privada fuera del repositorio. Usa source.directory para seleccionar el directorio que contiene los resultados del análisis.

Validar un hallazgo existente

Usa validate para contrastar un hallazgo de otra herramienta o flujo de trabajo con el código fuente. Esta operación no inicia un análisis nuevo ni ejecuta la aplicación o sus pruebas. Si necesitas evidencia de lo que ocurre durante la ejecución, reproduce el problema por separado.

1
2
3
4
5
6
7
8
9
10const validation = await security.validate({
  repositoryPath: repository,
  finding: {
    title: "Possible SQL injection",
    location: "src/index.js:1",
  },
});

console.log(validation.disposition);
console.log(validation.report);

Pasa el hallazgo como texto no vacío o como objeto JSON. Si está en un archivo, lee el archivo y pasa su contenido.

El campo disposition indica si el hallazgo se puede incluir en un informe (reportable), se suprimió (suppressed), no corresponde (not_applicable) o se aplazó (deferred). El texto Markdown de validation.report explica la evidencia y qué falta por verificar. Guarda esa cadena si necesitas un archivo de informe.

Monitorear o cancelar un análisis

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27try {
  const result = await security.run(repository, {
    outputDir: outputDir,
    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);
} finally {
  await security.close();
}

Para cancelar un análisis, pasa un AbortSignal desde tu solicitud o controlador de trabajos. Si el análisis sigue en curso después de 30 minutos, este ejemplo lo interrumpe y muestra el directorio que contiene los datos de salida que se hayan guardado:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { ScanInterruptedError } from "@openai/codex-security";

try {
  await security.run(repository, {
    outputDir: outputDir,
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
} finally {
  await security.close();
}

Un análisis interrumpido puede dejar resultados parciales en scanDir. Conserva ese directorio si necesitas investigar el resultado.

Las aplicaciones que muestran el progreso de la preparación del análisis también pueden usar las funciones de callback de ScanOptions para el ciclo de vida del análisis:

El estado de Trusted Access puede ser granted, not_granted o unknown. Si no tienes acceso o se desconoce su estado, también se invoca onWarning.

onSessionEvent recibe eventos cuyos datos sensibles no se han ocultado. Pueden contener código fuente o credenciales. Fíltralos antes de enviarlos a registros compartidos o a 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 un ajuste específico de Codex. Elige un modelo disponible para tu cuenta:

1
2
3
4
5
6
7
8const security = new CodexSecurity({
  // To override the bundled plugin, add pluginPath: "/path/to/plugin".
  pythonPath: "python3",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

Para reemplazar el complemento incluido, asigna a pluginPath la ruta de un directorio de complemento o de un archivo ZIP. pythonPath selecciona el intérprete del complemento. codexOverrides incorpora los valores compatibles a la configuración aislada de Codex. Para usar Amazon Bedrock, configura model_provider y model en codexOverrides.

Establece codexOverrides.approval_policy en "never" para denegar las solicitudes de permisos. De lo contrario, los análisis usan la revisión automática de las solicitudes de aprobación. Consulta los permisos de los análisis locales para obtener detalles sobre el acceso al sistema de archivos y las credenciales heredadas.

Para OpenRouter o Fireworks, proporciona también la clave de API correspondiente y la configuración completa del proveedor en codexOverrides. Define OPENROUTER_API_KEY y pasa el ID de un modelo disponible en OpenRouter a esta función de TypeScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16function createOpenRouterClient(model: string) {
  return new CodexSecurity({
    codexOverrides: {
      model,
      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 las dos claves openrouter a fireworks, establece name en Fireworks AI y 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 ofrece estos métodos de autenticación:

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

Si hay tanto una clave de API como una sesión guardada, el SDK usa la clave de API de forma predeterminada. Para usar tu sesión de ChatGPT, selecciónala para el análisis:

1
2
3const result = await security.run(repository, {
  auth: "chatgpt",
});

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

Manejar errores del análisis

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

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