zenveil 1.0.10

AI-powered security scanner for repositories and APIs.

ZenVeil

AI-powered security scanner for repositories and APIs.

ZenVeil scans your GitHub repositories and API endpoints for secrets, supply chain risks, CI/CD misconfigurations, and vulnerable dependencies — then uses AI to explain every finding and generate a fix, all from the terminal.

---

What is ZenVeil?

ZenVeil is a developer-first security tool that catches the vulnerabilities that slip through code review:

• Leaked secrets — AWS keys, GitHub tokens, Slack tokens, JWT secrets, hardcoded passwords, .env files committed by accident
• Supply chain risks — unpinned dependencies, missing lockfiles, dependency confusion attacks, known CVEs via OSV.dev
• CI/CD misconfigurations — unpinned GitHub Actions, pull_request_target privilege escalation, script injection, overly broad token scopes
• API security gaps — missing security headers, exposed admin/debug endpoints, insecure CORS, sensitive data leakage

Every finding is tagged with its OWASP Top 10 2021 category and includes a severity rating (CRITICAL / HIGH / MEDIUM / LOW). When you want to dig deeper, AI-powered explain, fix, and triage commands stream a Claude-generated analysis right to your terminal.

---

Features

Capability	Free	Pro
Secrets scanning	✓	✓
Supply chain scanning	✓	✓
CI/CD scanning	✓	✓
API scanning	✓	✓
List, stats, reports	✓	✓
AI triage (prioritized plan)	✓	✓
AI explain (per-finding)	—	✓
AI fix (streamed patch)	—	✓
Auto-PR (GitHub PR with fix)	—	✓
OWASP tagging	✓	✓

Free plan includes unlimited scanning, all scanners, triage, and reports.
Pro plan adds per-finding AI explanation, AI-generated fixes, and automatic GitHub PR creation.

---

Installation

pip install zenveil

Requires Python 3.8+.

---

Quick start

# 1. Authenticate — shows a step-by-step guide, then prompts securely
zenveil login

# 2. Scan a GitHub repository (animated multi-step progress)
zenveil scan github owner/repo

# 3. List the findings
zenveil list

# 4. Explain a finding with AI  [Pro]
zenveil explain ZV-ABC123

# 5. Generate a fix  [Pro]
zenveil fix ZV-ABC123

# 6. Open a GitHub PR with the fix automatically  [Pro]
zenveil fix ZV-ABC123 --auto-pr --repo owner/repo --token $GITHUB_TOKEN

---

Example scan

$ zenveil scan github acme/backend

  Scanning  acme/backend

  ✓  🔍  Cloning repository
  ✓  🔐  Running secrets scanner
  ✓  📦  Running supply-chain scanner
  ✓  🧪  Running code analysis
  ✓  🔬  Aggregating results

  CRITICAL  ZV-001  AWS access key exposed in source code
            secrets · src/config.py : line 12

  HIGH      ZV-002  .env file committed to repository
            secrets · .env

  HIGH      ZV-003  Unpinned GitHub Action (actions/checkout@v3)
            cicd · .github/workflows/deploy.yml : line 8

  MEDIUM    ZV-004  Missing Content-Security-Policy header
            headers · https://api.acme.com

4 findings  (1 critical · 2 high · 1 medium)

$ zenveil explain ZV-001

Finding ZV-001: AWS access key exposed in source code

The string 'AKIA...' matches the AWS access key format and is hardcoded
in src/config.py. Any developer with read access to this repository —
or anyone who ever cloned it — has permanent access to this key until
it is rotated in the AWS console.

Attack scenario: An attacker discovers the key via GitHub search or a
leaked repo archive, authenticates to AWS, and exfiltrates data from S3
or spins up resources for cryptomining. AWS bills accrue to your account.

Remediation: Rotate the key immediately in the AWS IAM console, then
store it as a GitHub Actions secret or in a secrets manager. Never
hardcode credentials in source code.

---

All commands

DISCOVER
  zenveil demo                              Offline preview — no API key needed
  zenveil version                           Show installed version

ACCOUNT
  zenveil login                             Step-by-step guide + secure key prompt
  zenveil login <api-key>                   Save key directly (scripts; prefer env var)
  zenveil whoami                            Show your email and current plan

SCANNING
  zenveil scan github <owner/repo>          Scan a GitHub repository
  zenveil scan github <owner/repo> --token  GitHub token for private repos
  zenveil scan github <owner/repo> --ref    Specific branch, tag, or commit
  zenveil scan github <owner/repo> --check-cves   CVE lookup via OSV.dev
  zenveil scan github <owner/repo> --exclude-tests  Skip test/fixture files
  zenveil scan api <url>                    Scan an API endpoint

FINDINGS
  zenveil list                              List findings from the last scan
  zenveil list --severity high,critical     Filter by severity
  zenveil list --scanner secrets            Filter by scanner
  zenveil stats                             Findings breakdown by severity and scanner

AI ANALYSIS  [Pro]
  zenveil explain <id>                      AI explanation of a finding
  zenveil fix <id>                          AI-generated fix with syntax highlighting
  zenveil fix <id> --auto-pr --repo <o/r>  Open a GitHub PR with the fix
  zenveil triage                            Prioritized remediation plan  [Free + Pro]

REPORTING
  zenveil report json <file>                Export last scan to JSON
  zenveil report html <file>                Export last scan to styled HTML

MANAGEMENT
  zenveil ignore <id>                       Suppress a finding
  zenveil ignore <id> --reason "text"       Suppress with a reason
  zenveil help                              Show all commands

BILLING
  zenveil upgrade                           Upgrade to Pro (opens Stripe checkout)
  zenveil upgrade pro --annual              Pro with annual billing
  zenveil billing                           Manage subscription, cancel, update card

DOCS
  zenveil docs                              Open documentation in browser
  zenveil docs auth                         Authentication guide
  zenveil docs secrets                      Secrets scanner guide
  zenveil docs supply-chain                 Supply-chain scanner guide
  zenveil docs api                          API scanner guide

Environment variables

Variable	Purpose
ZENVEIL_API_KEY	Your ZenVeil API key (alternative to zenveil login)
ZENVEIL_API_URL	Override the scanning API base URL
ZENVEIL_WEB_URL	Override the web server URL
GITHUB_TOKEN	GitHub token for private repo scans and PR automation

Exit codes

Code	Meaning
0	Scan completed — no HIGH or CRITICAL findings
1	Scan completed — at least one HIGH or CRITICAL finding
2	Command or scan error

---

Context-aware severity

ZenVeil scans test, fixture, and example files by default — because real credentials are routinely leaked there. Instead of ignoring these files, ZenVeil classifies findings by context and adjusts severity accordingly.

Context label	Paths	Behaviour
prod	src/, lib/, app/	Full severity
test	tests/, spec/, __tests__/	Severity downgraded
fixture	fixtures/, mocks/, stubs/	Severity downgraded
example	examples/, demos/, samples/	Severity downgraded

Use --exclude-tests to skip non-production files entirely.

---

Roadmap

• Local repo scanning — zenveil scan repo <path> for air-gapped or pre-push workflows
• GitLab & Bitbucket — native integrations beyond GitHub
• SARIF output — upload results to GitHub Advanced Security or any SARIF-compatible tool
• Policy as code — define fail conditions in a zenveil.yml config file
• Slack / webhook alerts — notify your team on CRITICAL or HIGH findings
• IDE extension — surface findings inline in VS Code as you code

---

License

MIT — see LICENSE for details.

---

Get your API key and view your dashboard at zenveil.dev