Metadata-Version: 2.1
Name: zenveil
Version: 1.0.2
Summary: AI-powered security scanner for repositories and APIs.
License: MIT
Project-URL: Homepage, https://zenveil.dev
Project-URL: Documentation, https://zenveil.dev/docs
Keywords: security,devsecops,secrets-scanning,supply-chain,vulnerability-scanner,cicd-security,sast,ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```bash
pip install zenveil
```

Requires Python 3.8+.

---

## Quick start

```bash
# 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](https://zenveil.dev/license) for details.

---

Get your API key and view your dashboard at **[zenveil.dev](https://zenveil.dev)**
