Security scanning for Python developers that actually tells you how to fix things.
One command. Five scanners. Zero noise.
pip install velonus
velonus scan ./your-projectRequires Python 3.10+
$ 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
| 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.
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- 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.sarifVelonus exits 1 on CRITICAL or HIGH findings — use it as a hard CI gate.
| 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 |
Velonus is in alpha. It works — we use it ourselves — and we want your feedback.
Expect rough edges. Report issues and we will fix them fast.
See CONTRIBUTING.md for dev setup, test instructions, and PR guidelines.
Found a security issue? See SECURITY.md.
All contributions welcome — especially scanner improvements and false-positive reports.
MIT — see LICENSE.
# 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]# Scan current directory
velonus scan ./
# Scan with verbose output (shows per-tool timing)
velonus scan ./ --verbose
# Verify install
velonus --help# Scan the current directory (default)
velonus scan ./
# Scan a specific path
velonus scan ./src
velonus scan ./apps/backend# Only show CRITICAL and HIGH findings (strict CI gate)
velonus scan ./ --severity high
# Only show MEDIUM and above
velonus scan ./ --severity medium# 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# 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# Show per-tool timing and execution details
velonus scan ./ --verbose
# Combine with JSON for structured debug output
velonus scan ./ --format json --verboseRun 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
- 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.sarifVelonus exits with code 1 on CRITICAL or HIGH findings — use as a hard gate.
- 0: No critical/high findings
- 1: CRITICAL or HIGH findings detected (blocks merge)
- Other: Scan failed
# 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# 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# 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-config.yaml
repos:
- repo: local
hooks:
- id: velonus
name: Velonus security scan
entry: velonus scan
language: system
pass_filenames: false
args: ["./", "--severity", "high"]✓ 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
- 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
- Python developers and AI startups
- Small SaaS teams without a dedicated security team
- Engineers who want security that fits into their workflow
Velonus is currently in private development. Contribution guidelines will be published when the CLI core is open sourced after Phase 5.
See CONTRIBUTING.md for setup instructions that apply today.