> ## Documentation Index
> Fetch the complete documentation index at: https:// zenveil.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> ZenVeil's architecture — from CLI command to AI-generated pull request.

## System architecture

ZenVeil has three components that work together to deliver end-to-end security scanning:

```
┌─────────────────────────────────────────────────────────────┐
│                        Developer                            │
│                    zenveil scan repo .                      │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Python CLI (zenveil)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   Scanners   │  │  AI Agent    │  │   Integrations   │  │
│  │  secrets     │  │  explain     │  │   GitHub PR      │  │
│  │  supply_chain│  │  fix         │  │   GitLab         │  │
│  │  api_headers │  │  triage      │  │   Slack          │  │
│  │  cicd        │  │  agent REPL  │  │   Email          │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
              ▼          ▼          ▼
     ┌──────────────┐  ┌────────┐  ┌─────────────────┐
     │  FastAPI     │  │Anthropic│  │  GitHub API     │
     │  Scanning    │  │ Claude  │  │  (scan/PR)      │
     │  API         │  │ Gemini  │  │                 │
     └──────────────┘  └────────┘  └─────────────────┘
              │
              ▼
     ┌──────────────────────────────────────┐
     │         Node.js / Express            │
     │         Web Server (Dashboard)       │
     │  ┌──────────┐  ┌──────────────────┐  │
     │  │  Clerk   │  │  Stripe Billing  │  │
     │  │  Auth    │  │  Subscriptions   │  │
     │  └──────────┘  └──────────────────┘  │
     │           MongoDB Atlas              │
     └──────────────────────────────────────┘
```

## Component overview

### Python CLI (`zenveil`)

The CLI is the primary interface for developers. It orchestrates all scanning, AI analysis, and integrations.

**Scanning orchestrator** — coordinates multiple scanners against a target and aggregates results into a unified `ScanResult` with consistent finding IDs, severities, OWASP categories, and evidence.

**Scanners** — each scanner is independent and targets specific vulnerability classes:

| Scanner | Target | What it finds |
| - | - | - |
| `secrets` | Local repos | Hardcoded credentials, .env hygiene, OWASP patterns |
| `supply_chain` | Local repos | Lockfiles, floating versions, dependency confusion, CVEs |
| `api_headers` | API URLs | Missing security headers, CORS, HTTPS enforcement |
| `cicd` | Workflow files | Injection, unpinned actions, overprivileged tokens |

**AI agent** — Claude-backed modules for `explain`, `fix`, `triage`, and the interactive REPL. All AI calls stream token-by-token to the terminal.

### FastAPI scanning API

The scanning API runs as a standalone Python service. It wraps the same scanning engine used by the CLI and exposes it over HTTP for use by the web dashboard and third-party integrations.

* Auth: `X-API-Key` header
* Base URL: `https://api.zenveil.dev`
* Endpoints: `/v1/scan/github`, `/v1/scan/api`, `/v1/explain`, `/v1/fix`, `/v1/triage`, `/v1/fix/pr`
* AI responses stream as `text/plain`

### Node.js web server

The web server handles everything that isn't scanning:

* **Dashboard** — Clerk JWT authentication, user management, scan history
* **Billing** — Stripe subscriptions (free / pro / team), checkout flow, webhook handling
* **API key management** — issue and revoke CLI API keys tied to Stripe plan limits

## Scan lifecycle

**1. Target resolution**

ZenVeil resolves the scan target:

* `repo` — validates the path exists and is readable
* `github` — parses `owner/repo` or full GitHub URL, downloads the archive via the GitHub API
* `api` — validates the URL and checks for SSRF targets (private IP ranges are blocked)

**2. Scanner dispatch**

The orchestrator runs applicable scanners in sequence. Each scanner returns a list of `Finding` objects with:

* Unique ID (e.g., `ZG-A1B2C3`)
* Severity (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`)
* OWASP categories
* Location (file, line, column)
* Evidence (what matched, with secrets redacted)
* Confidence score (0.0–1.0)
* Remediation guidance

**3. Result aggregation**

All findings are merged into a `ScanResult` and:

* Rendered to the terminal as a rich table
* Cached locally as `.zenveil-last-scan.json` for subsequent `explain`, `fix`, `list`, and `triage` commands
* Optionally written to a JSON or HTML report file

**4. Exit code**

ZenVeil exits with code `1` if any `CRITICAL` or `HIGH` finding exists — perfect for CI/CD gates. All other severities exit `0`.

## Finding ID system

Every finding gets a stable, deterministic ID of the form `ZG-XXXXXX` (6 hex characters). The ID is based on the finding content — same code, same vulnerability, same ID. This makes ignoring, tracking, and referencing findings reliable across scans.

```bash theme={null}
# Reference a specific finding across commands
zenveil explain ZG-A1B2C3
zenveil fix ZG-A1B2C3
zenveil ignore ZG-A1B2C3 --reason "Handled by secret manager migration"
zenveil feedback ZG-A1B2C3 false_positive
```

## AI model routing

ZenVeil uses Claude (Anthropic) as the primary AI model for all analysis. Google Gemini is used as a fallback when Anthropic is unavailable. The model routing is transparent — you set your API keys and ZenVeil handles the rest.

```
ANTHROPIC_API_KEY set → Claude (primary)
GEMINI_API_KEY set    → Gemini (fallback)
Neither set           → AI commands disabled (HTTP 503)
```

## Local-first design

For `scan repo` commands, **no code leaves your machine**. The scanning engine runs entirely locally:

* File traversal and pattern matching: local Python process
* CVE lookups (`--check-cves`): read-only requests to [osv.dev](https://osv.dev) (public, no auth)
* AI analysis (`explain`, `fix`): your code snippet is sent to Anthropic/Gemini — see [Security Philosophy](https:// zenveil.dev/docs/security/philosophy.md)
* GitHub scanning: the repository archive is downloaded to a temporary directory and deleted after scanning

## Data flow for GitHub scanning

```
zenveil scan github owner/repo
    │
    ├── Download archive from api.github.com (authenticated if --token provided)
    ├── Extract to /tmp/zenveil-XXXXXX/
    ├── Run all scanners against extracted files
    ├── Delete /tmp/zenveil-XXXXXX/
    └── Return findings (no code stored, no code sent to ZenVeil servers)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.