[![CI](https://github.com/AliAmmar15/Velonus/actions/workflows/ci.yml/badge.svg)](https://github.com/AliAmmar15/Velonus/actions)
[![PyPI](https://img.shields.io/pypi/v/velonus)](https://pypi.org/project/velonus)
[![Python](https://img.shields.io/pypi/pyversions/velonus)](https://pypi.org/project/velonus)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Alpha](https://img.shields.io/badge/status-alpha-orange)]()

# Velonus

**Security scanning for Python developers that actually tells you how to fix things.**  
One command. Five scanners. Zero noise.

```bash
pip install velonus
velonus scan ./your-project
```

> Requires Python 3.10+

---

## Demo

```
$ velonus scan ./myapp

  Scanning with 5 tools...

  secrets    ████████████████████  0.3s
  bandit     ████████████████████  2.1s
  semgrep    ████████████████████  4.2s
  pip-audit  ████████████████████  1.8s
  safety     ████████████████████  1.2s

 ┌──────────────┬──────────────────────────────────────────┬──────────────────┬──────────┐
 │ Severity     │ Finding                                  │ Location         │ Tool     │
 ├──────────────┼──────────────────────────────────────────┼──────────────────┼──────────┤
 │ 🔴 CRITICAL  │ Hardcoded AWS secret key                 │ config.py:14     │ secrets  │
 │ 🔴 CRITICAL  │ Hardcoded OpenAI API key                 │ llm_client.py:8  │ secrets  │
 │ 🔴 CRITICAL  │ SQL injection via string format          │ db/queries.py:41 │ semgrep  │
 │ 🟠 HIGH      │ Use of MD5 for password hashing          │ auth/utils.py:27 │ bandit   │
 │ 🟠 HIGH      │ requests 2.28.0 — CVE-2023-32681 (8.1)  │ requirements.txt │ pip-aud  │
 │ 🟡 MEDIUM    │ Shell injection via subprocess           │ runner.py:19     │ bandit   │
 │ 🟡 MEDIUM    │ Hardcoded JWT secret                     │ auth/tokens.py:3 │ secrets  │
 └──────────────┴──────────────────────────────────────────┴──────────────────┴──────────┘

  3 CRITICAL  │  7 HIGH  │  12 MEDIUM  │  34 LOW
```

---

## What It Detects

| Category | Tool | What it catches |
|---|---|---|
| Hardcoded secrets | detect-secrets + entropy | API keys, AWS creds, JWT tokens, PEM keys |
| Python SAST | Bandit | Injections, weak crypto, unsafe shell exec |
| Pattern analysis | Semgrep | OWASP Top 10 vulnerability patterns |
| Dependency CVEs | pip-audit | Known CVEs with CVSS v3 scores |
| Vulnerability DB | Safety | Package vulnerability cross-reference |

All findings are normalized to a unified schema with **CWE tags**, **OWASP Top 10 categories**, and **deterministic fingerprints** for deduplication.

---

## Output Formats

```bash
velonus scan ./                         # Rich terminal table (default)
velonus scan ./ --format json           # JSON array — pipe to jq, scripts, etc.
velonus scan ./ --sarif                 # Write SARIF to velonus-results.sarif
velonus scan ./ -o results/scan.sarif   # Write SARIF to a custom path
velonus scan ./ --severity high         # Filter to HIGH and CRITICAL only
velonus scan ./ --exclude tests/ --exclude migrations/  # Exclude paths
velonus scan ./ --verbose               # Per-tool timing + debug info
```

---

## CI Integration

```yaml
- name: Velonus security scan
  run: |
    pip install velonus
    velonus scan . --sarif -o velonus.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: velonus.sarif
```

Velonus exits `1` on CRITICAL or HIGH findings — use it as a hard CI gate.

---

## Roadmap

| | Phase | Status |
|---|---|---|
| ✅ | Phase 0 — CLI + secret detection | Done |
| ✅ | Phase 1 — Full scanner pipeline (Bandit, Semgrep, pip-audit, Safety) | Done |
| 🔨 | Phase 2 — AI context engine (exploitability scoring + fix generation) | Building |
| 🔜 | Phase 3 — GitHub PR integration (inline fixes, one-click accept) | Planned |
| 🔜 | Phase 4 — Web dashboard | Planned |

---

## Alpha Notice

Velonus is in alpha. It works — we use it ourselves — and we want your feedback.  
Expect rough edges. [Report issues](https://github.com/AliAmmar15/Velonus/issues) and we will fix them fast.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, test instructions, and PR guidelines.  
Found a security issue? See [SECURITY.md](SECURITY.md).  
All contributions welcome — especially scanner improvements and false-positive reports.

---

## License

MIT — see [LICENSE](LICENSE).


## Quick Start

### 1. Install

```bash
# Basic install (entropy-based secret detection)
pip install velonus

# Full install (with detect-secrets for better secret detection)
pip install velonus[detect-secrets]

# Include optional Semgrep patterns
pip install velonus[semgrep]

# All extras
pip install velonus[detect-secrets,semgrep]
```

### 2. Scan

```bash
# Scan current directory
velonus scan ./

# Scan with verbose output (shows per-tool timing)
velonus scan ./ --verbose

# Verify install
velonus --help
```

---

## How to Use

### Basic Scanning

```bash
# Scan the current directory (default)
velonus scan ./

# Scan a specific path
velonus scan ./src
velonus scan ./apps/backend
```

### Filter by Severity

```bash
# Only show CRITICAL and HIGH findings (strict CI gate)
velonus scan ./ --severity high

# Only show MEDIUM and above
velonus scan ./ --severity medium
```

### Exclude Paths

```bash
# Exclude specific directories
velonus scan ./ --exclude tests/ --exclude migrations/

# Exclude multiple patterns
velonus scan ./ --exclude "**/test_*.py" --exclude "venv/"

# By default, scans exclude: tests/, test_*/, */test_*.py, conftest.py
```

### Output Formats

```bash
# Terminal table (default — Rich formatted)
velonus scan ./

# JSON output (pipe to jq, scripts, etc.)
velonus scan ./ --format json

# Write SARIF file (GitHub Security tab)
velonus scan ./ --sarif

# Write SARIF to custom path
velonus scan ./ -o results/scan.sarif
```

### Verbose & Debug

```bash
# Show per-tool timing and execution details
velonus scan ./ --verbose

# Combine with JSON for structured debug output
velonus scan ./ --format json --verbose
```

### What Gets Detected

Run a scan to see:
- **Secrets**: Hardcoded API keys, credentials, tokens, database strings
- **SAST**: SQL injection, unsafe subprocess calls, weak crypto
- **Patterns**: OWASP Top 10 vulnerability patterns
- **Dependencies**: Known CVEs in requirements (with CVSS scores)
- **Vulnerabilities**: Packages with publicly disclosed vulnerabilities

All findings include:
- **CWE tags** — reference to MITRE Common Weakness Enumeration
- **OWASP Top 10** — categorization (e.g., A03:2021 for Injection)
- **Deterministic fingerprints** — same issue never scanned twice

---

## CI/CD Integration

### GitHub Actions

```yaml
- name: Velonus security scan
  run: |
    pip install velonus[detect-secrets]
    velonus scan . --sarif -o velonus-results.sarif

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: velonus-results.sarif
```

Velonus exits with code `1` on CRITICAL or HIGH findings — use as a hard gate.

### Exit Codes

- **0**: No critical/high findings
- **1**: CRITICAL or HIGH findings detected (blocks merge)
- **Other**: Scan failed

---

## Development Setup

### For Contributors

```bash
# Install uv (Python package manager)
pip install uv

# Clone and setup
git clone https://github.com/AliAmmar15/Velonus.git
cd Velonus

# Install all workspace packages in dev mode
uv sync --all-extras --dev

# Activate virtual environment
source .venv/bin/activate        # macOS/Linux
.venv\Scripts\Activate.ps1       # Windows PowerShell

# Install CLI for testing
pip install -e apps/cli
```

### Run Tests

```bash
# All tests
pytest apps/cli/tests/ -v

# Just secrets detector tests
pytest apps/cli/tests/test_secrets.py -v

# With coverage
pytest apps/cli/tests/ --cov=shield
```

### Lint & Type Check

```bash
# Format code
ruff format apps/cli/ packages/

# Check formatting
ruff check apps/cli/ packages/

# Type check (strict mode)
mypy --strict apps/cli/shield/
```

---

## Pre-commit Hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: velonus
        name: Velonus security scan
        entry: velonus scan
        language: system
        pass_filenames: false
        args: ["./", "--severity", "high"]
```

---

## Example Output

```
✓ Running secret detection...          [0.3s]
✓ Running Bandit...                    [2.1s]
✓ Running Semgrep...                   [4.2s]
✓ Running pip-audit...                 [1.8s]
✓ Running Safety...                    [1.2s]
──────────────────────────────────────────────
  3 CRITICAL  │  7 HIGH  │  12 MEDIUM  │  34 LOW

⚠ CRITICAL  Hardcoded AWS key detected
  → src/config.py:14
  CWE-798 · A07:2021
```
---

## Tech Stack

- **CLI** — Python, Typer, Rich
- **API** — FastAPI, PostgreSQL, ARQ
- **AI** — Anthropic Claude (Sonnet for fixes, Haiku for triage)
- **Scanners** — Semgrep, Bandit, pip-audit, Safety
- **Dashboard** — Next.js, Tailwind, shadcn/ui
- **Auth** — Clerk
- **Infra** — Docker, Railway

---

## Target Users

- Python developers and AI startups
- Small SaaS teams without a dedicated security team
- Engineers who want security that fits into their workflow

---

## Contributing

Velonus is currently in private development. Contribution guidelines will be published when the CLI core is open sourced after Phase 5.

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions that apply today.