How It Works

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

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)

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

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

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.

# 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 (public, no auth)
AI analysis (explain, fix): your code snippet is sent to Anthropic/Gemini — see Security Philosophy
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)

Getting Started

Scanners

Integrations

Examples

Plans & Pricing

System architecture

Component overview

Python CLI (`zenveil`)

FastAPI scanning API

Node.js web server

Scan lifecycle

Finding ID system

AI model routing

Local-first design

Data flow for GitHub scanning

​System architecture

​Component overview

​Python CLI (zenveil)

​FastAPI scanning API

​Node.js web server

​Scan lifecycle

​Finding ID system

​AI model routing

​Local-first design

​Data flow for GitHub scanning

System architecture

Component overview

Python CLI (`zenveil`)

FastAPI scanning API

Node.js web server

Scan lifecycle

Finding ID system

AI model routing

Local-first design

Data flow for GitHub scanning