Revisar cambios locales pendientes de commit

Puedes usar la CLI para revisar cambios locales pendientes de commit si le proporcionas de antemano contexto sobre el repositorio y las políticas de seguridad.

Ejecuta los ejemplos en la misma sesión de shell desde tu copia local del repositorio Git. Los ejemplos suponen que tu política de seguridad está en SECURITY.md y que la documentación de apoyo está en docs/security/. Los comandos de preparación crean un directorio temporal para los resultados del análisis.

northstar_repo="$(git rev-parse --show-toplevel)"
northstar_kb="$northstar_repo/docs/security"
northstar_results="$(mktemp -d)"

npx @openai/codex-security scan "$northstar_repo" \
  --working-tree \
  --base HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/working-tree"

Este comando revisa los cambios con respecto a HEAD, tanto los preparados para el commit como los que aún no lo están.

Antes de empezar, confirma que el árbol de trabajo contiene el cambio que quieres evaluar. Las modificaciones ajenas a ese cambio amplían el alcance de la investigación y pueden dificultar que relaciones los hallazgos con la pregunta que motivó la revisión.

Revisar Pull requests o commits de una rama

Otra opción es revisar un PR o una rama para detectar problemas de seguridad. Cambia a la rama que quieres revisar y obtén del repositorio remoto la versión actual de la rama de destino. En este ejemplo se usa origin/main.

northstar_pr_base="$(git -C "$northstar_repo" merge-base origin/main HEAD)"

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$northstar_pr_base" \
  --head HEAD \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/branch"

El análisis de diferencias se limita a los cambios propuestos. Cuando termine, encontrarás los siguientes archivos en el directorio de salida:

• report.md contiene el informe de la revisión en un formato fácil de leer.

• scan-manifest.json confirma los commits exactos de base y de punta, el objetivo del análisis y los artefactos.

• findings.json detalla la gravedad, el nivel de confianza, las ubicaciones y las medidas de corrección de los hallazgos.

• coverage.json indica qué partes se revisaron, cuáles se excluyeron, qué trabajo se pospuso y en qué medida se completó la revisión.

Analizar monorepos

En un monorepo, un cambio en una biblioteca compartida puede afectar a varios servicios. Codex debe recibir suficiente contexto para revisar esas interacciones, mientras que la integración continua determina qué componentes y verificaciones se necesitan.

Contexto del repositorio

Guarda las instrucciones de ingeniería comunes en AGENTS.md y los criterios de seguridad en SECURITY.md. Un repositorio típico podría tener esta estructura:

monorepo/
├── AGENTS.md
├── SECURITY.md
├── docs/security/
│   ├── architecture.md
│   └── threat-model.md
├── packages/auth/
└── services/
    ├── billing/
    └── reporting/

Usa los metadatos existentes sobre los responsables y el proceso de compilación para vincular cada componente con sus dependencias, los componentes que lo usan y sus pruebas. Por ejemplo, un cambio en packages/auth puede requerir que revises ambos servicios, aunque sus archivos sigan intactos. Tu organización mantiene estas relaciones para definir el alcance de la revisión. Agregar Codex no las configura automáticamente.

Evaluación de componentes

En repositorios grandes, no siempre es necesario analizar todo el código en cada PR. Si un monorepo contiene servicios o paquetes independientes, puedes ejecutar un análisis por rutas. Repite la opción –path para evaluar una biblioteca compartida junto con los componentes que la usan.

npx @openai/codex-security scan "$northstar_repo" \
  --path packages/auth \
  --path services/billing \
  --path services/reporting \
  --knowledge-base "$northstar_repo/SECURITY.md" \
  --knowledge-base "$northstar_kb" \
  --output-dir "$northstar_results/paths"

Este comando analiza únicamente las rutas seleccionadas.

Análisis de PR y de diferencias

Para analizar un PR, usa los hashes exactos del commit base y del commit de punta que figuran en los metadatos autenticados de GitHub. Ambas revisiones y su historial deben estar disponibles en la copia local del repositorio. El siguiente ejemplo reutiliza las variables anteriores y guarda por separado los resultados del análisis de diferencias:

BASE_SHA="<full PR base commit SHA>"
HEAD_SHA="<full PR head commit SHA>"

BASE_REVISION="$(
  git -C "$northstar_repo" merge-base "$BASE_SHA" "$HEAD_SHA"
)" || exit

npx @openai/codex-security scan "$northstar_repo" \
  --diff "$BASE_REVISION" \
  --head "$HEAD_SHA" \
  --knowledge-base "$northstar_kb" \
  --auth chatgpt \
  --output-dir "$northstar_results/pr"

El análisis de diferencias se centra en los cambios propuestos. Si un cambio en una biblioteca compartida requiere una revisión más amplia de los componentes que la usan, ejecuta también la evaluación de componentes en una copia local limpia del commit de punta de ese PR. Mantén los resultados separados. Las opciones --diff y --path corresponden a modos de análisis distintos y no se pueden combinar.

Analizar alertas de GitHub

También puedes usar la CLI de Codex Security para evaluar las alertas del análisis de código de la rama predeterminada.

northstar_github_repository="example/northstar"
northstar_github_alerts="$northstar_results/github-alerts.json"

# Import all open alerts as complete JSON.
npx @openai/codex-security import github "$northstar_github_repository" \
  --format json \
  > "$northstar_github_alerts"

# Or import a selected subset.
npx @openai/codex-security import github "$northstar_github_repository" \
  --github-alert 12 \
  --github-alert 18 \
  --format json \
  > "$northstar_github_alerts"

# Run from the corresponding local repository; imported contents are data.
cd "$northstar_repo"
npx @openai/codex-security validate "$northstar_github_alerts"