Skip to main content

​
Your first scan

1

Install ZenVeil

ZenVeil requires Python 3.8+. Install from PyPI:
pip install zenveil
Verify the install:
zenveil --help
Use a virtual environment to keep your global Python environment clean:
python -m venv .venv && source .venv/bin/activate
pip install zenveil
2

Log in to ZenVeil

zenveil login
This displays a step-by-step guide, then prompts you to paste your API key — the input is hidden (like a sudo password). The key is saved to ~/.zenveil/credentials and never appears in shell history or process listings.
╭──────────────────────────────────────────────────────────────────╮
│                                                                  │
│  🔐 ZenVeil Authentication                                       │
│                                                                  │
│  1  Open  https://zenveil.dev                                    │
│  2  Sign up — free, no credit card needed                        │
│  3  Go to  Settings → API Keys  and copy your key               │
│  4  Paste below — key is hidden, never saved to shell history    │
│                                                                  │
╰──────────────────────────────────────────────────────────────────╯

  Paste your API key (hidden):
Check your email and plan any time with zenveil whoami.
3

Scan your repository

Point ZenVeil at any directory:
zenveil scan repo .
Or scan a remote GitHub repository directly — no clone required:
zenveil scan github owner/repo
You’ll see output like this:
╭──────────────────────────────────────────────────────────────────╮
│  ZenVeil Security Scan                                           │
│  Target: /your/project  ·  Scanners: secrets, supply_chain      │
╰──────────────────────────────────────────────────────────────────╯

┌──────────┬──────────┬───────────────┬─────────────────────────────────────────┐
│ ID       │ Severity │ Scanner       │ Title                                   │
├──────────┼──────────┼───────────────┼─────────────────────────────────────────┤
│ ZG-A1B2  │ CRITICAL │ secrets       │ AWS access key                          │
│ ZG-C3D4  │ HIGH     │ secrets       │ .env file committed to repository       │
│ ZG-E5F6  │ HIGH     │ supply_chain  │ Dependency confusion risk               │
│ ZG-G7H8  │ MEDIUM   │ secrets       │ Token stored in browser storage         │
└──────────┴──────────┴───────────────┴─────────────────────────────────────────┘

4 finding(s) · CRITICAL: 1 · HIGH: 2 · MEDIUM: 1

Run `zenveil explain ZG-A1B2` for AI analysis.
Run `zenveil fix ZG-A1B2` for an AI-generated fix.
4

Explain a finding

ZenVeil uses Claude to explain what every finding means and why it matters:
zenveil explain ZG-A1B2

Explaining ZG-A1B2: AWS access key

An AWS access key (AKIA...) was found committed in plain text at
src/config.js:14. AWS access keys grant programmatic access to your
AWS account. If this key is in a public or shared repository, anyone
can use it to access your S3 buckets, spin up EC2 instances, query
your databases, or run up significant AWS charges.

AWS automatically detects and notifies you of exposed keys, but the
window between exposure and detection can be hours. Attackers scan
GitHub continuously for newly committed AWS keys.

OWASP Category: A02:2021 — Cryptographic Failures
Confidence: 95%

Immediate actions:
1. Revoke this key in the AWS IAM console right now
2. Run `git rm --cached src/config.js` to untrack the file
3. Add `.env` to `.gitignore`
4. Use AWS Secrets Manager or environment variables for runtime access
5

Fix it — with a PR

Generate an AI fix and open a GitHub pull request automatically:
zenveil fix ZG-A1B2 --auto-pr --repo owner/your-repo

Generating fix for ZG-A1B2: AWS access key

Applying redaction directly (no API key needed).

Opened pull request: https://github.com/owner/your-repo/pull/42
ZenVeil creates a PR that redacts the secret and adds .env to .gitignore. Review and merge.

​
What’s next?

Scan a GitHub repo

Scan any public repository — or private ones with a token — without cloning.

Add to CI/CD

Gate your pull requests on security findings. ZenVeil exits with code 1 on CRITICAL/HIGH.

AI triage

Get a prioritized remediation plan for all findings, ranked by risk and effort.

API integration

Embed ZenVeil scanning directly into your platform via REST API.

​
Environment variables cheatsheet

VariableRequired forExample
ZENVEIL_API_KEYAll CLI commands (alternative to zenveil login)zvk_live_...
GITHUB_TOKENGitHub scanning, fix --auto-prghp_...
ZENVEIL_API_URLSelf-hosted scanning APIhttps://api.zenveil.dev
ZENVEIL_WEB_URLSelf-hosted billing serverhttps://zenveil-server.onrender.com
Set them in your shell profile or CI secrets: 
export ZENVEIL_API_KEY="zvk_live_your_key_here"
export GITHUB_TOKEN="ghp_your_github_token"