Metadata-Version: 2.4
Name: herozion
Version: 1.2.0
Summary: Security audit and performance analysis CLI tool for developers
Author: Herozion Team
License: Proprietary
Project-URL: Homepage, https://github.com/herozion/herozion
Project-URL: Documentation, https://docs.herozion.io
Keywords: security,audit,vulnerability,cli,owasp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9.0,>=8.4.1
Requires-Dist: rich<16.0,>=13.0.0
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: pydantic<3.0,>=2.13.4
Requires-Dist: pydantic-settings<3.0,>=2.14.1
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: certifi>=2026.5.20
Requires-Dist: idna>=3.17
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pygls>=1.3.1; extra == "dev"
Requires-Dist: lsprotocol>=2023.0.1; extra == "dev"
Provides-Extra: lsp
Requires-Dist: pygls>=1.3.1; extra == "lsp"
Requires-Dist: lsprotocol>=2023.0.1; extra == "lsp"
Provides-Extra: pdf
Requires-Dist: fpdf2>=2.7.0; extra == "pdf"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Dynamic: license-file

# Herozion

**Local-first security scanner for developers** — detect vulnerabilities before they reach production, without exposing your code.

![Version](https://img.shields.io/badge/Version-1.2.0-blue)
![Platforms](https://img.shields.io/badge/Platforms-Windows%20|%20Linux%20|%20macOS-brightgreen)
![Analysis](https://img.shields.io/badge/Analysis-100%25%20local-green)
![License](https://img.shields.io/badge/License-Proprietary-red)

---

## Quick start

```bash
npx herozion@latest scan .
```

Analysis runs entirely on your machine. **Nothing leaves your machine** unless you explicitly opt in with `--push`.

---

## Privacy & security

- Reads **only** the directory you pass as argument — read-only, no code execution
- Writes reports to `~/.herozion/reports/` (configurable via `HEROZION_REPORT_DIR`)
- Makes **no network requests** without `--push`
- With `--push`, only the **report** (scores, file names, findings) is sent — never source code
- **API credentials** (`HEROZION_API_KEY`, `HEROZION_API_URL`) are read from `~/.herozion/.env` or your shell — a malicious project `.env` cannot override them (only `HEROZION_PROJECT_ID` is read from the repo)
- No daemons, no background services, no root privileges required

Every release includes a `CHECKSUMS.sha256` file for binary verification:
```bash
sha256sum -c CHECKSUMS.sha256
```

---

## Installation

**macOS (Homebrew):**
```bash
brew tap Herozion/herozion
brew trust herozion/herozion   # required once on recent Homebrew
brew install herozion
brew update && brew upgrade herozion   # to update (re-run trust if prompted)
```

**Windows / Linux (npx — no install):**
```bash
npx herozion@latest scan .
```

**Linux (CI / servers):**
```bash
curl -fSL -o herozion \
  https://github.com/Herozion/scanner-releases/releases/latest/download/herozion-linux-amd64
chmod +x herozion && ./herozion scan .
```

---

## Usage

```bash
herozion scan .                                 # scan current directory
herozion scan . --verbose                       # show files scanned + confirm no network
herozion scan . -e vendor -e dist               # exclude directories
herozion scan . --fail-on=critical,high --min-score 80  # CI quality gate
herozion scan . -o json > report.json           # JSON output
herozion scan . --docker myapp:latest           # include Docker image CVEs
herozion scan . --liveness-check                # verify hardcoded secrets are still active
herozion scan . --profile                       # show timing, cache stats, peak memory after scan
herozion --lang fr scan .                       # French output (en/fr/pt)
```

**Export & compliance:**
```bash
herozion export                                 # JSON to stdout (dev+)
herozion export --format html -o report.html
herozion export --format pdf  -o report.pdf
herozion export --compliance soc2               # soc2 / iso27001 / pci-dss / nis2
```

**Auto-fix** (dev+):
```bash
herozion fix 3          # patch a single finding (shows diff, asks confirmation)
herozion fix-all --yes  # patch all fixable findings (CI/CD)
```

**SBOM** (enterprise):
```bash
herozion sbom . -o sbom.json                   # CycloneDX 1.5 JSON
herozion sbom . --format spdx -o sbom.spdx     # SPDX 2.3
```

**Cloud & auth:**
```bash
herozion register / login / logout
herozion scan . --push         # push report to dashboard
herozion history               # scan history
herozion badge                 # README security badge (free)
```

### Exit codes

| Code | Condition |
|------|-----------|
| `0`  | All thresholds passed |
| `1`  | Score below `--min-score` (default: 60), or a `--fail-on` severity matched |

### `.herozionignore` and `.gitignore`

Place a `.herozionignore` at your project root (`.gitignore` syntax) to permanently exclude paths without repeating `-e` flags:
```gitignore
vendor
*.min.js
legacy/old_auth.py
src/generated/*.js
```

Herozion also respects your project **`.gitignore`** during file discovery. Gitignored files (e.g. local `credentials.json`, `firebase-service-account.json`) are not scanned — they are treated as local-only artifacts, not deployed secrets.

---

### Free plan — partial results

On the **free plan**, the CLI and JSON output show only the **top 5** findings by severity. The full scan still runs locally; additional findings are not lost.

JSON output includes:
```json
{
  "partial_results": true,
  "shown_vulnerabilities": 5,
  "total_vulnerabilities": 10,
  "upgrade_hint": "..."
}
```

Use a **Dev / Team / Enterprise** plan (or inspect the saved scan via `herozion export`) to see every finding.

---

## What Herozion detects

Each finding includes a **confidence level** (`HIGH` / `MEDIUM` / `LOW`), a **CWE identifier**, and an **OWASP Top 10** category — visible in the terminal table and in JSON/CSV exports.

### 22 security categories

| # | Category | What it catches | CWE |
|---|----------|-----------------|-----|
| 1 | **BOLA** | Direct object access without authorization checks | CWE-639 |
| 2 | **Broken Authentication** | Hardcoded passwords, static tokens, JWT weak secrets, API keys in storage | CWE-798 / CWE-321 |
| 3 | **BFLA** | Unprotected admin endpoints | CWE-284 |
| 4 | **Mass Assignment** | User input passed directly to models | CWE-915 |
| 5 | **Injection** | SQL (CWE-89), NoSQL (CWE-943), command (CWE-78), XSS (CWE-79), `eval()`, path traversal (CWE-22), prototype pollution (CWE-1321), SSRF (CWE-918) | CWE-74 |
| 6 | **Rate Limiting** | Endpoints with no request throttling | CWE-770 |
| 7 | **Security Misconfiguration** | `DEBUG=True`, permissive CORS, tab-napping, open redirects (CWE-601) | CWE-16 |
| 8 | **Excessive Data Exposure** | Full object serialization, sensitive fields exposed | CWE-213 |
| 9 | **MITM** | SSL verification disabled, plaintext HTTP | CWE-295 |
| 10 | **Replay Attacks** | Tokens without expiry, missing nonce | CWE-294 |
| 11 | **Webhook Abuse** | Webhooks without signature verification | CWE-345 |
| 12 | **DDoS / Flood** | Missing timeouts, full in-memory reads | CWE-400 |
| 13 | **Insecure File Upload** | Missing MIME validation, unsafe paths | CWE-434 |
| 14 | **Input Validation** | Missing schema validation for user input | CWE-20 |
| 15 | **Sensitive Data Exposure** | Plaintext secrets, passwords, tokens in code or logs | CWE-312 |
| 16 | **Insecure Dependencies** | Outdated or CVE-affected dependencies (with reachability analysis) | CWE-1104 |
| 17 | **IaC Security** | Terraform open security groups, public S3, Kubernetes privileged containers | CWE-16 |
| 18 | **License Risk** | GPL/AGPL/LGPL dependencies incompatible with proprietary use | — |
| 19 | **Dockerfile Security** | Unpinned images, root user, secrets in `ARG`/`ENV` | CWE-1188 |
| 20 | **CI/CD Security** | Unpinned Actions, `permissions: write-all`, secrets in `env:` | CWE-829 |
| 21 | **AI/LLM Security** | Prompt injection, hardcoded API keys, unsafe LLM output, excessive agency | CWE-74 |
| 22 | **Memory Leaks** | Global accumulators, orphaned listeners, unbounded caches, asyncio task leaks | CWE-401 |

### Performance

| # | Category | What it catches |
|---|----------|-----------------|
| 23 | **Performance** | N+1 queries, `list()` on full querysets, `import *` |

---

## CI/CD integration

**GitHub Actions:**
```yaml
- name: Security scan
  run: |
    curl -fSL -o herozion \
      https://github.com/Herozion/scanner-releases/releases/latest/download/herozion-linux-amd64
    chmod +x herozion
    SCAN_ID=$(./herozion scan . -o json --fail-on=critical,high --min-score 80 | jq -r '.scan_id')
    ./herozion push
    ./herozion notify-pr "$SCAN_ID" \
      --repo "${{ github.repository }}" --pr "${{ github.event.pull_request.number }}"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

**GitLab CI:**
```yaml
security_scan:
  stage: test
  script:
    - curl -fSL -o herozion https://github.com/Herozion/scanner-releases/releases/latest/download/herozion-linux-amd64
    - chmod +x herozion && ./herozion scan . --push
  artifacts:
    paths: [security-report.json]
    when: always
```

---

## Configuration

Settings load in this order (highest wins): **shell environment** → **`~/.herozion/.env`** → **project `.env`** (restricted — see below).

```env
# ── Credentials (use ~/.herozion/.env — never commit these) ──
HEROZION_API_KEY=hz_...                        # CI/CD or dashboard API key (--push)
HEROZION_API_URL=https://api.herozion.io       # API endpoint (--push only)

# ── Per-repo (safe in project .env — auto-set after herozion push) ──
HEROZION_PROJECT_ID=your-project-uuid

# ── General ──
HEROZION_REPORT_DIR=~/.herozion/reports        # report storage
HEROZION_LANG=en                               # en | fr | pt
HEROZION_PARALLEL_WORKERS=4                    # analysis workers
HEROZION_INCREMENTAL_FILE_CACHE=true           # reuse per-file results on unchanged files
HEROZION_CACHE_MAX_MB=2048                     # analysis cache size limit (MiB)
HEROZION_PROFILE=1                             # same as --profile on scan
HEROZION_SCAN_TESTS=1                          # include test/ fixture paths (dev only)
```

> **Security:** scanning a third-party repo cannot redirect your API traffic. Keys such as `HEROZION_API_URL` and `HEROZION_API_KEY` in a project `.env` are **ignored** (a warning is logged). Store credentials in `~/.herozion/.env` or export them in your shell.

---

## Plans

| | Free | Dev ($15/mo) | Team ($49/mo) | Enterprise ($299/mo) |
|---|---|---|---|---|
| Local scans | Unlimited | Unlimited | Unlimited | Unlimited |
| Vulnerabilities shown | Top 5 | All | All | All |
| Recommendations | Top 3 (preview) | Top 5 with fixes | Unlimited | Unlimited |
| Score regression / history | — | 30 days | Unlimited | Unlimited |
| Cloud push + dashboard | — | ✓ | ✓ | ✓ |
| Export (JSON, CSV, HTML, PDF) | — | ✓ | ✓ | ✓ |
| Auto-fix | — | Guided | 1-click | 1-click |
| CI/CD quality gates | — | — | ✓ | ✓ |
| Compliance reports | — | — | ✓ | ✓ |
| Users | — | 1 | 5 | Unlimited |
| SSO / SAML / RBAC | — | — | — | ✓ |
| Dedicated support & SLA | — | — | — | ✓ |
| README badge | ✓ | ✓ | ✓ | ✓ |

Upgrade at [herozion.io](https://herozion.io).

---

## FAQ

**Does Herozion require Python, Node, or any runtime?**
No. The binary is self-contained.

**Which languages are analysed?**
Python, JavaScript/TypeScript, Java, Go, Ruby, PHP, C#, Rust, plus config files (YAML, JSON, TOML, `.env`, Dockerfile) and IaC (Terraform, Kubernetes, Helm).

**Is my source code sent anywhere?**
No. `--push` sends only the report (scores, file names, findings) — never source code.

**How do I verify Herozion only reads what I pass?**
Run `herozion scan . --verbose` — every file opened is printed, and no-network is confirmed explicitly.

**How do I update?**
- macOS: `brew update && brew upgrade herozion`
- npm (global): `npm install -g herozion@latest --foreground-scripts` (downloads the matching binary)
- npm (project): `npm install herozion@latest --save-dev`

**How do I uninstall?**
- npm (global): `npm uninstall -g herozion`
- If an older npm package re-downloads the binary during uninstall: `npm uninstall -g herozion --ignore-scripts`

**Why do I see only 5 findings on the free plan?**
The free plan shows the top 5 vulnerabilities by severity. The full scan still runs — check `partial_results` and `total_vulnerabilities` in JSON output, or upgrade to see every finding.

**Does Herozion scan gitignored files?**
No. Files matched by your project `.gitignore` are excluded from discovery (e.g. local credential JSON files that are never committed).

---

## Roadmap

**Coming:**
- [ ] VS Code extension — inline analysis, zero CLI setup
- [ ] Web version — scan via `herozion.io/scan`, no installation
- [ ] Watch mode — continuous analysis as you code (foreground only, no daemon)

**Shipped:** memory leak detection, SBOM generation, reachability analysis, secret liveness detection, AI/LLM security, compliance reports, container image scanning, score regression, custom failure policies, README badge, `.herozionignore`, auto-fix engine, cloud sync, GitHub PR comments, exportable reports, Express middleware-chain validation, `.gitignore`-aware discovery, npm lockfile dependency resolution, incremental per-file analysis cache, scan profiling (`--profile`), hardened `.env` loading (v1.2.0).

---

## License

Proprietary software — see [LICENSE](LICENSE) for terms of use.

Copyright © 2026 Herozion Team. All rights reserved.

