zentra

# Zentra CLI Zentra é um CLI de segurança de aplicações open-source, alimentado por IA, projetado para desenvolvedores. Ele escaneia bases de código em busca de riscos de segurança usando análise de frameworks, modelagem de ameaças, análise estática (SAST), cadeia de suprimentos, API e scanners de infraestrutura como código (IaC). Pode ser executado localmente com uma interface de terminal interativa ou sem cabeça em pipelines de CI. O binário é chamado `zentra`. ## Recursos - **Modo CI sem cabeça** para pipelines de GitHub Actions e GitLab merge request. - **Orquestração de scanner com suporte LLM** com provedores Anthropic, compatíveis com OpenAI, Claude CLI e Codex CLI experimental. - **Modo pentest dinâmico em navegador** para alvos autorizados. - **Múltiplos formatos de saída**: Markdown, JSON, SARIF e HTML estilizado em `.zentra/`. - **Armazenamento de credenciais criptografado em repouso** (DPAPI no Windows, arquivos `0600` no Unix). ## Instalação ### Instalação rápida (recomendada) Não requer toolchain Rust, clone de repositório ou etapa de build. ```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" ``` Abra uma nova janela de terminal depois para que `zentra` esteja disponível. Para instalar manualmente, baixe um build da [página de Releases](https://github.com/johannus22/zentra/releases). > **Nota Linux:** O binário vincula-se a `libdbus` em tempo de execução para acesso ao keyring do SO. Em imagens mínimas ou sem cabeça, instale-o primeiro (`sudo apt-get install -y libdbus-1-3` ou equivalente). Alternativamente, defina `ZENTRA_NO_OS_KEYCHAIN=1` para usar o armazenamento de credenciais baseado em arquivo criptografado. ### Instalar a partir do código-fonte Compile e execute localmente: ```bash cargo build ``` Instale o binário a partir do checkout do repositório: ```bash cargo install --path . ``` ## Uso A TUI é a principal experiência local para configurar provedores, iniciar escaneamentos e revisar resultados. O menu principal agrupa testes estáticos de segurança de aplicações (SAST), testes dinâmicos de segurança de aplicações (DAST) e ações diversas. ### Comandos de escaneamento Execute apenas uma família de scanners: ```bash zentra scan --only sast zentra scan --only supply-chain zentra scan --only api zentra scan --only iac ``` Use `--pack` para dar a cada scanner um pacote de repositório verificado por contexto. O estado do escaneamento é armazenado em `.zentra/checkpoint.json` para execuções incrementais. SAST pode usar até 50 rodadas de provedor ReAct; outros scanners usam até 30. Execuções locais de `zentra scan` incluem um painel de Chat somente leitura permanente. O Chat responde perguntas limitadas e redigidas sobre escaneamento e repositório com um perfil somente leitura (`list_files`, `read_file`, `grep_code` e comandos Git limitados). Ele pode propor ações de foco/re-execução ou categorias de vulnerabilidade, mas nem a saída do modelo nem uma chamada de ferramenta podem aplicá-las sem confirmação local. Ações confirmadas são armazenadas no checkpoint e aplicadas apenas no próximo escaneamento. O Chat não está disponível em `zentra ci` ou outros caminhos de escaneamento sem cabeça. ### Escaneamento de segurança em CI Zentra inclui um comando CI dedicado: ```bash zentra ci ``` `zentra ci` não é um alias para `zentra scan`. Ele detecta GitHub Actions ou GitLab CI, confirma que o job roda em um pipeline de PR/MR, executa scanners de segurança focados sem TUI, escreve artefatos de CI e falha apenas para achados no nível ou acima do limite de falha ou falhas de scanner/sistema. Por padrão, `zentra ci` bloqueia o PR/MR em qualquer achado **Crítico ou Alto**. Achados Médios, Baixos e Informativos são relatados, mas não falham o job. #### Limite de falha Defina a variável de ambiente `ZENTRA_CI_FAIL_THRESHOLD` (um de `critical`, `high`, `medium`, `low`, `info`) ou use o campo `fail_threshold` em `.zentra/config.json` para persistir a política. Exemplo de job 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 O fluxo de trabalho GitLab CI inclui um segundo job para pipelines de push para `staging`. Ele executa um escaneamento completo do repositório, nunca falha o pipeline e arquiva ou atualiza uma issue do GitLab com rótulos `security` e `zentra-triage`. Use um token de acesso pessoal com escopo `api` como variável mascarada de CI/CD. Artefatos de CI ficam em `.zentra/ci-report.md`, `.zentra/ci-report.json` e `.zentra/ci-report.html`. #### Variáveis de ambiente de CI | Variável | Obrigatória | Notas | |----------|----------|-------| | `ZENTRA_API_KEY` | sim | Segredo — a chave de API do provedor LLM | | `ZENTRA_PROVIDER_BASE_URL` | sim | Segredo ou variável — ex., `https://api.anthropic.com` | | `ZENTRA_PROVIDER_MODEL` | sim | Variável — ex., `claude-sonnet-5` | | `ZENTRA_PROVIDER_KIND` | não | Padrão para `openai_compat` | | `ZENTRA_PROVIDER_REASONING_EFFORT` | não | Repassa para provedores compatíveis com OpenAI | | `ZENTRA_PROVIDER_CONTEXT_WINDOW` | não | Substitui a janela de contexto padrão do provedor | | `ZENTRA_CI_FAIL_THRESHOLD` | não | Severidade mínima que bloqueia o PR | Se nenhum de `ZENTRA_API_KEY`, `ZENTRA_PROVIDER_BASE_URL` ou `ZENTRA_PROVIDER_MODEL` estiver definido, `zentra ci` recorre ao perfil configurado com `zentra config setup` em `~/.zentra/config.toml`. ### Gerar fluxos de trabalho de CI ```bash zentra init --ci github # criar workflow GitHub Actions zentra init --ci gitlab # criar job GitLab CI ``` ### Modo pentest Zentra inclui um modo pentest dinâmico autorizado para alvos web ao vivo: ```bash zentra pentest --url https://target.example --authorized \ --allow-host target.example \ --allow-host api.target.example ``` A flag `--authorized` é obrigatória, então um escaneamento acidental falha fechado. Execute este modo apenas contra sistemas que você possui ou tem permissão explícita para testar. Use `--exclude-path` para excluir caminhos e `--scope-domain` para permitir um domínio e todos os seus subdomínios. O modo pentest usa a imagem Docker `zentra/pentest-sandbox:0.1.0` para seu toolchain isolado. Defina `ZENTRA_SANDBOX_IMAGE` e `ZENTRA_SANDBOX_VERSION` para imagens personalizadas. Uma execução de pentest usa três agentes sandbox (Recon, Exploit, Validator) e gera relatórios com vetores base CVSS v3.1. Diretórios de saída: - Dentro de um projeto inicializado: `./.zentra/pentest/<host>/<run-id>/` - Fora: `<Documents>/Zentra/pentest/<host>/<run-id>/` (ou `output_dir` configurado) ### Outros comandos ```bash zentra init # criar .zentra/config.json zentra scan --only sast # executar uma família de scanners zentra ci # escaneamento CI de PR/MR sem cabeça zentra ci --refresh-architecture zentra ci --full --report-only # escaneamento completo sem bloquear pipeline de staging zentra security verify-audit [session] ``` ## Notas de segurança - Zentra armazena credenciais de provedores fora do diretório do projeto em um armazenamento de segredos criptografado. DPAPI protege a chave de criptografia de dados no Windows; Unix usa permissões de arquivo restritivas e o backend de keyring disponível. - Ferramentas de arquivo bloqueiam path traversal e limitam leituras de arquivos. - Chat interativo usa um perfil de ferramenta separado, limitado e somente leitura. - O envelope de segurança padrão registra uma cadeia de auditoria à prova de adulteração, controla chamadas de ferramentas e marca saída de ferramentas não confiável. Defina `ZENTRA_SECURITY=hardened` para impor vinculação de resposta e abortar em injeção; use `ZENTRA_SECURITY=off` apenas para desenvolvimento local confiável. - Verifique uma cadeia de auditoria com `zentra security verify-audit [session]`. - Ferramentas de histórico Git e auditoria de dependências degradam graciosamente quando binários ou histórico necessários não estão disponíveis. ## Estrutura do projeto - `.zentra/config.json` — configuração do projeto - `.zentra/checkpoint.json` — estado do escaneamento para execuções incrementais - `.zentra/reports/findings.html` — relatórios HTML - `.zentra/architecture.md` — saída de análise de framework usada como contexto de CI Não commite segredos ou estado de escaneamento no controle de versão.