Sobre el proyecto

# Zentra CLI Zentra es una CLI de seguridad de aplicaciones de código abierto impulsada por IA, diseñada para desarrolladores. Escanea bases de código en busca de riesgos de seguridad mediante análisis de frameworks, modelado de amenazas, análisis estático (SAST), cadena de suministro, API y escáneres de infraestructura como código (IaC). Puede ejecutarse localmente con una interfaz de terminal interactiva o sin interfaz en pipelines de CI. El binario se llama `zentra`. ## Características - **Modo CI sin interfaz** para pipelines de GitHub Actions y GitLab merge request. - **Orquestación de escáner basada en LLM** con proveedores Anthropic, compatibles con OpenAI, Claude CLI y Codex CLI experimental. - **Modo de pentest dinámico en navegador** para objetivos autorizados. - **Múltiples formatos de salida**: Markdown, JSON, SARIF y HTML con estilos bajo `.zentra/`. - **Almacenamiento de credenciales cifrado en reposo** (DPAPI en Windows, archivos con permisos `0600` en Unix). ## Instalación ### Instalación rápida (recomendada) No requiere toolchain de Rust, clonar el repositorio ni paso de compilación. ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.sh | sh ``` Para Windows PowerShell: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.ps1 | iex" ``` Abre una nueva ventana de terminal después para que `zentra` esté disponible. Para instalar manualmente, descarga una compilación desde la [página de Releases](https://github.com/johannus22/zentra/releases). > **Nota para Linux:** El binario enlaza con `libdbus` en tiempo de ejecución para el acceso al keyring del sistema. En imágenes mínimas o sin interfaz, instálalo primero (`sudo apt-get install -y libdbus-1-3` o equivalente). Alternativamente, configura `ZENTRA_NO_OS_KEYCHAIN=1` para usar el almacén de credenciales cifrado basado en archivos. ### Instalar desde el código fuente Compila y ejecuta localmente: ```bash cargo build ``` Instala el binario desde la copia del repositorio: ```bash cargo install --path . ``` ## Uso La TUI es la experiencia local principal para configurar proveedores, iniciar escaneos y revisar resultados. El menú principal agrupa pruebas estáticas de seguridad de aplicaciones (SAST), pruebas dinámicas de seguridad de aplicaciones (DAST) y acciones misceláneas. ### Comandos de escaneo Ejecuta solo una familia de escáneres: ```bash zentra scan --only sast zentra scan --only supply-chain zentra scan --only api zentra scan --only iac ``` Usa `--pack` para dar a cada escáner un paquete de repositorio verificado por contexto. El estado del escaneo se almacena en `.zentra/checkpoint.json` para ejecuciones incrementales. SAST puede usar hasta 50 rondas de proveedor ReAct; otros escáneres usan hasta 30. Las ejecuciones locales de `zentra scan` incluyen un panel de Chat de solo lectura permanente. El Chat responde preguntas acotadas y redactadas sobre escaneo y repositorio con un perfil de solo lectura (`list_files`, `read_file`, `grep_code` y comandos Git acotados). Puede proponer acciones de enfoque/reejecución tipadas o de categoría de vulnerabilidad, pero ni la salida del modelo ni una llamada de herramienta pueden aplicarlas sin confirmación local. Las acciones confirmadas se almacenan en el checkpoint y se aplican solo en el siguiente escaneo. El Chat no está disponible en `zentra ci` ni en otras rutas de escaneo sin interfaz. ### Escaneo de seguridad en CI Zentra incluye un comando dedicado de CI: ```bash zentra ci ``` `zentra ci` no es un alias de `zentra scan`. Detecta GitHub Actions o GitLab CI, confirma que el trabajo se ejecuta en un pipeline de PR/MR, ejecuta escáneres de seguridad enfocados sin TUI, escribe artefactos de CI y falla solo por hallazgos en o por encima del umbral de fallo o fallos de escáner/sistema. Por defecto, `zentra ci` bloquea el PR/MR ante cualquier hallazgo **Crítico o Alto**. Hallazgos de gravedad Media, Baja e Informativa se reportan pero no fallan el trabajo. #### Umbral de fallo Configura la variable de entorno `ZENTRA_CI_FAIL_THRESHOLD` (una de `critical`, `high`, `medium`, `low`, `info`) o usa el campo `fail_threshold` en `.zentra/config.json` para persistir la política. Ejemplo de trabajo de GitHub Actions: ```yaml - name: Run Zentra CI env: ZENTRA_API_KEY: ${{ secrets.ZENTRA_API_KEY }} ZENTRA_PROVIDER_MODEL: ${{ vars.ZENTRA_PROVIDER_MODEL }} ZENTRA_CI_FAIL_THRESHOLD: critical run: zentra ci ``` #### GitLab CI El flujo de trabajo de GitLab CI incluye un segundo trabajo para pipelines de push a `staging`. Ejecuta un escaneo completo del repositorio, nunca falla el pipeline y crea o actualiza un issue de GitLab con etiquetas `security` y `zentra-triage`. Usa un token de acceso personal con alcance `api` como variable CI/CD enmascarada. Los artefactos de CI viven en `.zentra/ci-report.md`, `.zentra/ci-report.json` y `.zentra/ci-report.html`. #### Variables de entorno de CI | Variable | Requerida | Notas | |----------|-----------|-------| | `ZENTRA_API_KEY` | sí | Secreto — la clave de API del proveedor LLM | | `ZENTRA_PROVIDER_BASE_URL` | sí | Secreto o variable — ej., `https://api.anthropic.com` | | `ZENTRA_PROVIDER_MODEL` | sí | Variable — ej., `claude-sonnet-5` | | `ZENTRA_PROVIDER_KIND` | no | Se establece por defecto en `openai_compat` | | `ZENTRA_PROVIDER_REASONING_EFFORT` | no | Se pasa a proveedores compatibles con OpenAI | | `ZENTRA_PROVIDER_CONTEXT_WINDOW` | no | Sobrescribe la ventana de contexto predeterminada del proveedor | | `ZENTRA_CI_FAIL_THRESHOLD` | no | Gravedad mínima que bloquea el PR | Si ninguna de `ZENTRA_API_KEY`, `ZENTRA_PROVIDER_BASE_URL` o `ZENTRA_PROVIDER_MODEL` está configurada, `zentra ci` recurre al perfil configurado con `zentra config setup` en `~/.zentra/config.toml`. ### Generar flujos de trabajo de CI ```bash zentra init --ci github # crea un flujo de trabajo de GitHub Actions zentra init --ci gitlab # crea un trabajo de GitLab CI ``` ### Modo pentest Zentra incluye un modo de pentest dinámico autorizado para objetivos web en vivo: ```bash zentra pentest --url https://target.example --authorized \ --allow-host target.example \ --allow-host api.target.example ``` El flag `--authorized` es requerido, por lo que un escaneo accidental falla de forma segura. Solo ejecuta este modo contra sistemas que posees o para los que tienes permiso explícito de prueba. Usa `--exclude-path` para excluir rutas y `--scope-domain` para permitir un dominio y todos sus subdominios. El modo pentest usa la imagen Docker `zentra/pentest-sandbox:0.1.0` para su toolchain aislado. Configura `ZENTRA_SANDBOX_IMAGE` y `ZENTRA_SANDBOX_VERSION` para imágenes personalizadas. Una ejecución de pentest usa tres agentes sandbox (Recon, Exploit, Validator) y genera informes con vectores base CVSS v3.1. Directorios de salida: - Dentro de un proyecto inicializado: `./.zentra/pentest/<host>/<run-id>/` - Fuera: `<Documents>/Zentra/pentest/<host>/<run-id>/` (o `output_dir` configurado) ### Otros comandos ```bash zentra init # crea .zentra/config.json zentra scan --only sast # ejecuta una familia de escáneres zentra ci # escaneo de CI de PR/MR sin interfaz zentra ci --refresh-architecture zentra ci --full --report-only # escaneo completo sin bloquear un pipeline de staging zentra security verify-audit [session] ``` ## Notas de seguridad - Zentra almacena las credenciales del proveedor fuera del directorio del proyecto en un almacén secreto cifrado. DPAPI protege la clave de cifrado de datos en Windows; Unix usa permisos de archivo restrictivos y el backend de keyring disponible. - Las herramientas de archivo bloquean el path traversal y limitan las lecturas de archivos. - El Chat interactivo usa un perfil de herramientas de solo lectura, acotado y separado. - El envelope de seguridad predeterminado registra una cadena de auditoría a prueba de manipulación, controla las llamadas de herramientas y marca la salida de herramientas no confiable. Configura `ZENTRA_SECURITY=hardened` para aplicar el binding de respuesta y abortar ante inyección; usa `ZENTRA_SECURITY=off` solo para desarrollo local confiable. - Verifica una cadena de auditoría con `zentra security verify-audit [session]`. - Las herramientas de historial de Git y auditoría de dependencias degradan correctamente cuando los binarios o el historial requeridos no están disponibles. ## Estructura del proyecto - `.zentra/config.json` — configuración del proyecto - `.zentra/checkpoint.json` — estado del escaneo para ejecuciones incrementales - `.zentra/reports/findings.html` — informes HTML - `.zentra/architecture.md` — salida del análisis de frameworks usada como contexto de CI No confirmes secretos ni estado de escaneo en el control de versiones.