zentra

# Zentra CLI Zentra is an open-source, AI-powered application security CLI designed for developers. It scans codebases for security risks using framework analysis, threat modeling, static analysis (SAST), supply-chain, API, and infrastructure-as-code (IaC) scanners. It can run locally with an interactive terminal interface or headlessly in CI pipelines. The binary is named `zentra`. ## Features - **Headless CI mode** for GitHub Actions and GitLab merge request pipelines. - **LLM-backed scanner orchestration** with Anthropic, OpenAI-compatible, Claude CLI, and experimental Codex CLI providers. - **Dynamic browser pentest mode** for authorized targets. - **Multiple output formats**: Markdown, JSON, SARIF, and styled HTML under `.zentra/`. - **Encrypted-at-rest credential storage** (DPAPI on Windows, `0600` files on Unix). ## Installation ### Quick install (recommended) No Rust toolchain, repository clone, or build step required. ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.sh | sh ``` For Windows PowerShell: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.ps1 | iex" ``` Open a new terminal window afterward so `zentra` is available. To install manually, download a build from the [Releases page](https://github.com/johannus22/zentra/releases). > **Linux note:** The binary links to `libdbus` at runtime for OS keyring access. On minimal or headless images, install it first (`sudo apt-get install -y libdbus-1-3` or equivalent). Alternatively, set `ZENTRA_NO_OS_KEYCHAIN=1` to use the encrypted file-based credential store. ### Install from source Build and run locally: ```bash cargo build ``` Install the binary from the repository checkout: ```bash cargo install --path . ``` ## Usage The TUI is the primary local experience for configuring providers, starting scans, and reviewing results. The main menu groups static application security testing (SAST), dynamic application security testing (DAST), and miscellaneous actions. ### Scan commands Run only one scanner family: ```bash zentra scan --only sast zentra scan --only supply-chain zentra scan --only api zentra scan --only iac ``` Use `--pack` to give each scanner a context-checked repository pack. Scan state is stored at `.zentra/checkpoint.json` for incremental runs. SAST can use up to 50 ReAct provider rounds; other scanners use up to 30. Local `zentra scan` runs include a permanent read-only Chat pane. Chat answers bounded, redacted scan and repository questions with a read-only profile (`list_files`, `read_file`, `grep_code`, and bounded Git commands). It can propose typed focus/rerun or vulnerability-category actions, but neither model output nor a tool call can apply one without local confirmation. Confirmed actions are stored in the checkpoint and applied only at the next scan. Chat is not available in `zentra ci` or other headless scan paths. ### CI security scanning Zentra includes a dedicated CI command: ```bash zentra ci ``` `zentra ci` is not an alias for `zentra scan`. It detects GitHub Actions or GitLab CI, confirms the job runs in a PR/MR pipeline, runs focused security scanners with no TUI, writes CI artifacts, and fails only for findings at or above the fail threshold or scanner/system failures. By default, `zentra ci` blocks the PR/MR on any **Critical or High** finding. Medium, Low, and Info findings are reported but do not fail the job. #### Fail threshold Set `ZENTRA_CI_FAIL_THRESHOLD` environment variable (one of `critical`, `high`, `medium`, `low`, `info`) or use the `fail_threshold` field in `.zentra/config.json` to persist the policy. Example GitHub Actions job: ```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 The GitLab CI workflow ships a second job for push-to-`staging` pipelines. It runs a full repository scan, never fails the pipeline, and files or updates one GitLab issue with labels `security` and `zentra-triage`. Use a personal access token with `api` scope as a masked CI/CD variable. CI artifacts live at `.zentra/ci-report.md`, `.zentra/ci-report.json`, and `.zentra/ci-report.html`. #### CI environment variables | Variable | Required | Notes | |----------|----------|-------| | `ZENTRA_API_KEY` | yes | Secret — the LLM provider API key | | `ZENTRA_PROVIDER_BASE_URL` | yes | Secret or variable — e.g., `https://api.anthropic.com` | | `ZENTRA_PROVIDER_MODEL` | yes | Variable — e.g., `claude-sonnet-5` | | `ZENTRA_PROVIDER_KIND` | no | Defaults to `openai_compat` | | `ZENTRA_PROVIDER_REASONING_EFFORT` | no | Passes through to OpenAI-compatible providers | | `ZENTRA_PROVIDER_CONTEXT_WINDOW` | no | Overrides provider's default context window | | `ZENTRA_CI_FAIL_THRESHOLD` | no | Minimum severity that blocks the PR | If none of `ZENTRA_API_KEY`, `ZENTRA_PROVIDER_BASE_URL`, or `ZENTRA_PROVIDER_MODEL` are set, `zentra ci` falls back to the profile configured with `zentra config setup` in `~/.zentra/config.toml`. ### Generate CI workflows ```bash zentra init --ci github # create GitHub Actions workflow zentra init --ci gitlab # create GitLab CI job ``` ### Pentest mode Zentra includes an authorized dynamic pentest mode for live web targets: ```bash zentra pentest --url https://target.example --authorized \ --allow-host target.example \ --allow-host api.target.example ``` The `--authorized` flag is required, so an accidental scan fails closed. Only run this mode against systems you own or have explicit permission to test. Use `--exclude-path` to exclude paths and `--scope-domain` to allow a domain and all its subdomains. Pentest mode uses the `zentra/pentest-sandbox:0.1.0` Docker image for its isolated toolchain. Set `ZENTRA_SANDBOX_IMAGE` and `ZENTRA_SANDBOX_VERSION` for custom images. A pentest run uses three sandbox agents (Recon, Exploit, Validator) and generates reports with CVSS v3.1 base vectors. Output directories: - Inside an initialized project: `./.zentra/pentest/<host>/<run-id>/` - Outside: `<Documents>/Zentra/pentest/<host>/<run-id>/` (or configured `output_dir`) ### Other commands ```bash zentra init # create .zentra/config.json zentra scan --only sast # run one scanner family zentra ci # headless PR/MR CI scan zentra ci --refresh-architecture zentra ci --full --report-only # full scan without blocking a staging pipeline zentra security verify-audit [session] ``` ## Security notes - Zentra stores provider credentials outside the project directory in an encrypted secret store. DPAPI protects the data-encryption key on Windows; Unix uses restrictive file permissions and the available keyring backend. - File tools block path traversal and cap file reads. - Interactive Chat uses a separate bounded, read-only tool profile. - The default security envelope records a tamper-evident audit chain, gates tool calls, and marks untrusted tool output. Set `ZENTRA_SECURITY=hardened` to enforce response binding and abort-on-injection; use `ZENTRA_SECURITY=off` only for trusted local development. - Verify an audit chain with `zentra security verify-audit [session]`. - Git history and dependency audit tools degrade gracefully when required binaries or history are unavailable. ## Project structure - `.zentra/config.json` — project configuration - `.zentra/checkpoint.json` — scan state for incremental runs - `.zentra/reports/findings.html` — HTML reports - `.zentra/architecture.md` — framework analysis output used as CI context Do not commit secrets or scan state to version control.