> ## Documentation Index
> Fetch the complete documentation index at: https:// zenveil.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# zenveil scan

> Scan local repositories, GitHub repos, and API endpoints for security vulnerabilities.

## Overview

`zenveil scan` is the primary command. It dispatches the appropriate scanners based on the target type and returns a prioritized list of findings.

## Scan a local repository

```bash theme={null}
zenveil scan repo <path>
```

### Arguments

| Argument | Description                               |
| -------- | ----------------------------------------- |
| `path`   | Path to the local repository or directory |

### Flags

| Flag            | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| `--check-cves`  | Query [OSV.dev](https://osv.dev) for known CVEs in pinned dependencies. Adds \~2–5 seconds. |
| `--json <file>` | Write scan results to a JSON file in addition to terminal output                            |

### Examples

```bash theme={null}
# Scan current directory
zenveil scan repo .

# Scan a specific project
zenveil scan repo ~/projects/my-api

# Scan with CVE checks
zenveil scan repo . --check-cves

# Write results to JSON
zenveil scan repo . --json results.json

# All flags combined
zenveil scan repo . --check-cves --json scan-$(date +%Y%m%d).json
```

### Sample output

```
╭──────────────────────────────────────────────────────────────────────╮
│  ZenVeil Security Scan                                               │
│  Target: /home/user/my-api  ·  2 scanner(s) active                  │
│  Started: 2026-05-25T09:41:22Z  ·  Completed: 2026-05-25T09:41:24Z  │
╰──────────────────────────────────────────────────────────────────────╯

┌──────────┬──────────┬───────────────┬─────────────────────────────────────────┬─────────────────────┐
│ ID       │ Severity │ Scanner       │ Title                                   │ Location            │
├──────────┼──────────┼───────────────┼─────────────────────────────────────────┼─────────────────────┤
│ ZG-A1B2  │ CRITICAL │ secrets       │ AWS access key                          │ src/config.js:14    │
│ ZG-C3D4  │ HIGH     │ secrets       │ .env file committed to repository       │ .env                │
│ ZG-E5F6  │ HIGH     │ secrets       │ Token stored in browser storage         │ src/auth/login.js:8 │
│ ZG-G7H8  │ HIGH     │ supply_chain  │ Missing lockfile                        │ package.json        │
│ ZG-I9J0  │ MEDIUM   │ secrets       │ Debug mode enabled                      │ config/app.js:3     │
└──────────┴──────────┴───────────────┴─────────────────────────────────────────┴─────────────────────┘

5 finding(s) · CRITICAL: 1 · HIGH: 3 · MEDIUM: 1

Run `zenveil explain <id>` for AI analysis.
Run `zenveil fix <id> --auto-pr --repo owner/repo` to open a GitHub PR.
```

### What the secrets scanner checks

* **Hardcoded credentials** — AWS keys, GitHub tokens, Slack tokens, private key blocks, hardcoded passwords, API keys, JWT tokens
* **Environment file hygiene** — `.env` files committed to the repo, missing `.env*` in `.gitignore`
* **OWASP patterns** — XSS-accessible token storage, predictable JWT secrets, client-side admin gates, weak password hashing, debug mode, open redirects, long-lived sessions

### What the supply chain scanner checks

* **Missing lockfiles** — `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Pipfile.lock`, `poetry.lock`
* **Floating npm versions** — `^`, `~`, `*`, `latest` ranges that allow breaking updates
* **Dependency confusion** — internal package names that could be squatted on public registries
* **Known CVEs** — OSV.dev lookups for pinned versions (requires `--check-cves`)

***

## Scan a GitHub repository

```bash theme={null}
zenveil scan github <repository>
```

Scan any GitHub repository without cloning it. ZenVeil downloads the archive, scans it in a temporary directory, and deletes it — no code is stored.

Progress is shown as an animated five-step panel in the terminal:

```
  Scanning  owner/repo

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

### Arguments

| Argument     | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `repository` | `owner/repo`, `https://github.com/owner/repo`, or `git@github.com:owner/repo` |

### Flags

| Flag              | Description                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--token <tok>`   | GitHub personal access token. Defaults to `GITHUB_TOKEN` env var. Required for private repos.                                  |
| `--ref <ref>`     | Branch, tag, or commit SHA to scan. Defaults to the default branch.                                                            |
| `--check-cves`    | Query OSV.dev for known CVEs                                                                                                   |
| `--exclude-tests` | Skip findings in test, fixture, mock, and example files entirely. See [Context-aware scanning](#context-aware-scanning) below. |

### Examples

```bash theme={null}
# Scan a public repository
zenveil scan github owner/repo

# Scan a private repository with a token
zenveil scan github owner/private-repo --token ghp_your_token

# Scan a specific branch
zenveil scan github owner/repo --ref feature/new-auth

# Scan a specific commit
zenveil scan github owner/repo --ref abc123def456

# With CVE checks
zenveil scan github owner/repo --check-cves

# Scan only production files (skip test/fixture/example files)
zenveil scan github owner/repo --exclude-tests
```

***

## Context-aware scanning

ZenVeil scans **all files by default** — including test, fixture, mock, and example directories. This is intentional. Some of the most damaging credential leaks in the industry originated in files developers considered "safe":

```
tests/test_auth.py       → AWS_SECRET_KEY = "AKIA..."
payment.test.js          → STRIPE_KEY = "sk_live_..."
fixtures/mock_config.yml → DB_PASSWORD = "prod-password-123"
```

Rather than ignoring these files and creating blind spots, ZenVeil **classifies findings by context** and adjusts severity accordingly.

### How severity is downgraded

| Original severity | In test/fixture/example file |
| ----------------- | ---------------------------- |
| CRITICAL          | → MEDIUM                     |
| HIGH              | → LOW                        |
| MEDIUM            | → LOW                        |
| LOW               | → LOW                        |

### Context labels in output

Every finding includes a context badge so you know exactly where it came from:

| Badge     | Directories matched                                                      |
| --------- | ------------------------------------------------------------------------ |
| `prod`    | `src/`, `lib/`, `app/`, all other paths                                  |
| `test`    | `tests/`, `test/`, `spec/`, `__tests__/`, `e2e/`, `*.test.*`, `*.spec.*` |
| `fixture` | `fixtures/`, `mocks/`, `stubs/`, `fakes/`, `seeds/`, `testdata/`         |
| `example` | `examples/`, `demos/`, `samples/`                                        |

### Example output

```
╭─────────────────────────────────────────────────────────────────────╮
│ ⚡ ZenVeil  Security Scan                                           │
│   Target  github acme-corp/payments-api                             │
│   Results 4 production  /  2 test/fixture (severity downgraded)     │
╰─────────────────────────────────────────────────────────────────────╯

  ID               SEVERITY    CONTEXT   SCANNER   TITLE                        LOCATION
  ZG-A1B2C3D4E5   ● CRITICAL   prod      secrets   AWS access key               src/config.py:14
  ZG-F6G7H8I9J0   ● MEDIUM     test      secrets   AWS access key (test file)   tests/test_auth.py:8
```

The same pattern detected. Different context. Different severity. This reduces alert fatigue without blind-spotting real leaks.

### When to use `--exclude-tests`

Use `--exclude-tests` only when:

* You have already audited your test files and confirmed no real credentials exist
* You want a tighter signal-to-noise ratio for a specific scan

The default (scan everything) is recommended. Credentials committed to test history are still in your git history — and still exploitable.

### GitHub token permissions

| Use case                    | Required scope         |
| --------------------------- | ---------------------- |
| Public repo scanning        | None (no token needed) |
| Private repo scanning       | `repo`                 |
| Opening pull requests       | `repo`                 |
| Read-only scanning (public) | `public_repo`          |

Create a token with minimum required scopes at [github.com/settings/tokens/new](https://github.com/settings/tokens/new).

### Rate limits

Without a token, GitHub allows \~60 requests/hour. With a token, this increases to \~5,000. For CI/CD pipelines, always set `GITHUB_TOKEN`.

***

## Scan an API endpoint

```bash theme={null}
zenveil scan api <url>
```

Scan an HTTP API for security header misconfigurations.

### Arguments

| Argument | Description                                |
| -------- | ------------------------------------------ |
| `url`    | API base URL (must be publicly accessible) |

### Flags

| Flag            | Description           |
| --------------- | --------------------- |
| `--json <file>` | Write results to JSON |

### What it checks

* `Strict-Transport-Security` — HSTS presence and configuration
* `X-Content-Type-Options` — MIME sniffing protection
* `X-Frame-Options` — clickjacking protection
* `Content-Security-Policy` — XSS policy
* `Referrer-Policy` — referrer information leakage
* `Permissions-Policy` — browser feature control
* `X-XSS-Protection` — legacy XSS filter header
* CORS misconfiguration — wildcard `Access-Control-Allow-Origin`

### Examples

```bash theme={null}
# Scan your API
zenveil scan api https://api.your-app.com

# Scan with JSON output
zenveil scan api https://api.your-app.com --json api-headers.json
```

### Sample output

```
╭─────────────────────────────────────────────────────────╮
│  ZenVeil API Scan                                       │
│  Target: https://api.your-app.com                       │
╰─────────────────────────────────────────────────────────╯

┌──────────┬──────────┬──────────────┬──────────────────────────────────────────────┐
│ ID       │ Severity │ Scanner      │ Title                                        │
├──────────┼──────────┼──────────────┼──────────────────────────────────────────────┤
│ ZG-H1I2  │ HIGH     │ api_headers  │ Missing Content-Security-Policy              │
│ ZG-J3K4  │ MEDIUM   │ api_headers  │ Missing X-Frame-Options                      │
│ ZG-L5M6  │ MEDIUM   │ api_headers  │ Missing Referrer-Policy                      │
└──────────┴──────────┴──────────────┴──────────────────────────────────────────────┘

3 finding(s) · HIGH: 1 · MEDIUM: 2
```

<Note>
  API scanning only tests publicly reachable endpoints. Private or localhost URLs are blocked (SSRF protection). Use `scan repo` for scanning application code.
</Note>