zenveil 1.0.2

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	Details
Secrets scanning	AWS, GitHub, Slack, JWT, private keys, .env commits, frontend-exposed vars
Supply chain	Lockfile checks, unpinned npm/pip deps, dep confusion, OSV CVE lookup
CI/CD	GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, Jenkinsfile
API scanning	Security headers, exposed endpoints, CORS, data leakage
AI explain	Stream a Claude explanation: what it is, how it's exploited, business impact
AI fix	Stream a Claude-generated patch or config change
AI triage	Prioritized remediation plan across all findings at once
PR automation	--auto-pr opens a GitHub PR with the fix automatically
Reports	Export to JSON or styled HTML
OWASP tagging	Every finding mapped to OWASP Top 10 2021

---

Installation

pip install zenveil

Requires Python 3.8+.

---

Quick start

# 1. Save your API key (get one at https://zenveil.dev)
zenveil login <your-api-key>

# 2. Scan a GitHub repository
zenveil scan github owner/repo

# 3. List the findings
zenveil list

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

# 5. Generate a fix
zenveil fix ZV-ABC123

---

Example scan

$ zenveil scan github acme/backend

Scanning acme/backend…

  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  (2 critical/high · 1 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

ACCOUNT
  zenveil login <api-key>                   Save your API key

SCANNING
  zenveil scan github <owner/repo>          Scan a GitHub repository
  zenveil scan github <owner/repo> --token  Use a GitHub token for private repos
  zenveil scan github <owner/repo> --ref    Scan a specific branch or commit
  zenveil scan github <owner/repo> --check-cves  Include CVE lookup via OSV.dev
  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
  zenveil explain <id>                      AI explanation of a finding (streams)
  zenveil fix <id>                          AI-generated fix (streams)
  zenveil fix <id> --auto-pr --repo <o/r>  Open a GitHub PR with the fix automatically
  zenveil triage                            Prioritized remediation plan for all findings

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

Environment variables

Variable	Purpose
ZENVEIL_API_KEY	Your ZenVeil API key (alternative to zenveil login)
ZENVEIL_API_URL	Override the API base 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

---

Roadmap

• Dashboard — browser-based view of findings, trends, and team activity (coming soon)
• Slack / webhook alerts — notify your team when a scan finds CRITICAL or HIGH issues
• 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
• 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