🛡️ SecureVibes

<div align="center">

🌐 securevibes.ai — Visit our website for docs, features & blog

</div> <p align="center"> <a href="https://securevibes.ai/how-it-works">How It Works</a> • <a href="https://securevibes.ai/features">Features</a> • <a href="https://securevibes.ai/blog">Blog</a> • <a href="https://discord.gg/2hWGpZz3z">Discord</a> </p>

---

AI-Native Security System for Vibecoded Applications

SecureVibes uses Claude's multi-agent architecture to autonomously find security vulnerabilities in your codebase. Five specialized AI agents (4 required + 1 optional DAST) work together to deliver comprehensive, context-aware security analysis with concrete evidence.

---

✨ Features

True Agent Architecture

• 🤖 Autonomous Orchestration: Claude intelligently coordinates agents
• 📐 Assessment Agent: Maps your codebase architecture
• 🎯 Threat Modeling Agent: Architecture-driven STRIDE threat analysis with technology-specific skills (agentic AI, APIs)
• 🔍 Code Review Agent: Security thinking methodology to find vulnerabilities
• 🧪 DAST Agent: Dynamic testing with auto-bundled skills
• 📊 Report Generator: Compiles comprehensive scan results

Agentic Application Detection

• 🤖 Automatic Detection: Identifies agentic applications by scanning for LLM APIs, agent frameworks, and tool execution patterns
• 🔒 ASI Threat Enforcement: Requires OWASP ASI (Agentic Security Issues) threats in threat models for detected agentic apps
• 🔄 Auto-Retry Validation: Invalid threat models are rejected with guidance; agent retries once before failing
• ⚙️ Override Flags: Use --agentic or --no-agentic to force classification

Multi-Language Support

• 11 Languages: Python, JavaScript, TypeScript, Go, Ruby, Java, PHP, C#, Rust, Kotlin, Swift
• Smart Detection: Automatically detects languages in your project
• Language-Aware Exclusions: Python projects exclude venv/, JS projects exclude node_modules/, Go projects exclude vendor/
• Mixed Projects: Handles polyglot codebases intelligently

---

🚀 Quick Start

# Install for the latest release on PyPi (might not have all the latest changes in the code)
pip install securevibes

# NOTE: the package uploaded on PyPi might not have all the latest changes. 
# I will try to release a new version of the package whenever there are significant changes/developments
# If you would rather use the version with the latest changes, you can do the following:

# Install for the latest version (might be buggy)
git clone https://github.com/anshumanbh/securevibes.git
cd securevibes
virtualenv env

# Linux/macOS
. env/bin/activate

# Windows
# Create & activate venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install the core package in editable mode
# Linux/macOS
pip install -e packages/core

# Windows
pip install -e .\packages\core

# Authenticate (choose one method)
# Method 1: Session-based (recommended)
# You could use your Claude subscription here, if you don't want to pay per API requests
claude  # Run interactive CLI, then type: /login

# Method 2: API key
# Linux/macOS
export ANTHROPIC_API_KEY="your-api-key-here"

# Windows (Set for *current* PowerShell session)
$env:ANTHROPIC_API_KEY = "your-api-key-here"

# Scan your project
securevibes scan /path/to/code --debug

# The most important part
# Sit back and relax. Please be patient as the scans might take some time, depending upon the model being used.

---

🔐 Runtime Safety Model

SecureVibes runs scan orchestration with Claude SDK permission_mode="default". Runtime safety depends on explicit tool surfaces and scanner hooks (including repository-boundary guardrails, PR review artifact constraints, and DAST database CLI blocking).

Operational guidance:

• Run scans only on trusted repositories.
• Prefer isolated CI runners/containers for scans.
• Avoid running scans with access to production credentials or sensitive networks.

For package-level details, see packages/core/README.md.

---

🎯 Usage

Basic Commands

# Full security scan
securevibes scan .

# View results
securevibes report

Common Options

# Default: creates .securevibes/scan_report.md (markdown format)
securevibes scan .

# Export results as JSON
securevibes scan . --format json --output results.json

# Custom markdown report (saved to .securevibes/custom_report.md)
securevibes scan . --format markdown --output custom_report.md

# Terminal table output (no file saved)
securevibes scan . --format table

# Filter by severity
securevibes scan . --severity high

# Use different model
securevibes scan . --model haiku

# Verbose debug output (shows agent narration)
securevibes scan . --debug

# Quiet mode
securevibes scan . --quiet

PR Review

PR review compares diffs against existing scan artifacts in .securevibes/:

# Compare branches
securevibes pr-review . --base main --head feature-branch

# Commit range
securevibes pr-review . --range abc123~1..abc123

# Patch file
securevibes pr-review . --diff changes.patch

# Commit tracking (requires baseline scan and scan_state.json)
securevibes pr-review . --since-last-scan
securevibes pr-review . --since 2026-02-01
securevibes pr-review . --last 10

# Update base artifacts from PR findings
securevibes pr-review . --range abc123~1..abc123 --update-artifacts

# Clean transient PR artifacts before reruns
securevibes pr-review . --range abc123~1..abc123 --clean-pr-artifacts

# Output formats (default: markdown)
securevibes pr-review . --base main --head feature-branch --format markdown
securevibes pr-review . --base main --head feature-branch --format json --output pr_review.json
securevibes pr-review . --base main --head feature-branch --format json --quiet
securevibes pr-review . --base main --head feature-branch --format table

# Filter by severity
securevibes pr-review . --base main --head feature-branch --severity high

# Model + debug
securevibes pr-review . --base main --head feature-branch --model haiku --debug

# Catchup: pull latest + review since last full scan
securevibes catchup . --branch main

securevibes catchup requires a clean working tree (commit, stash, or discard local changes first).

# Override PR review budget via CLI flags
securevibes pr-review . --range abc123~1..abc123 --pr-attempts 2 --pr-timeout 120

# Auto-triage: reduce budget for low-risk diffs (docs, tests, etc.)
securevibes pr-review . --range abc123~1..abc123 --auto-triage

PR review runtime controls (CLI flags take precedence over env vars):

# Timeout per PR review attempt in seconds (default: 240)
export SECUREVIBES_PR_REVIEW_TIMEOUT_SECONDS=300

# Number of PR review attempts before giving up (default: 4)
export SECUREVIBES_PR_REVIEW_ATTEMPTS=5

--auto-triage runs a deterministic pre-filter that classifies diffs as low-risk (docs, tests, config-only changes) and reduces retry budget for those diffs.

PR review fails closed if diff context would be truncated (more than 16 prioritized files or any hunk over 200 lines). PR review also fails closed when PR_VULNERABILITIES.json is not produced after retry attempts. Split large reviews with smaller --range, --last, or --since windows.

PR review artifacts (written to .securevibes/):

• DIFF_CONTEXT.json (parsed diff summary)
• PR_VULNERABILITIES.json (raw findings)
• pr_review_report.md (default markdown report)
• scan_state.json (commit tracking for pr-review/catchup)

Agentic Detection Override

SecureVibes automatically detects agentic applications and requires OWASP ASI threats in threat models. Override with:

# Force agentic classification (require ASI threats like THREAT-ASI01-xxx)
securevibes scan . --agentic

# Force non-agentic classification (ASI threats optional)
securevibes scan . --no-agentic

Running Individual Sub-Agents

SecureVibes breaks down security scanning into 5 sub-agents. You can run them individually to save time and API costs:

# Run specific sub-agent only
securevibes scan . --subagent assessment
securevibes scan . --subagent threat-modeling
securevibes scan . --subagent code-review
securevibes scan . --subagent report-generator
securevibes scan . --subagent dast --target-url http://localhost:3000

# Resume from specific sub-agent onwards
securevibes scan . --resume-from code-review
securevibes scan . --resume-from dast --dast --target-url http://localhost:3000

# Force execution without prompts (CI/CD mode)
securevibes scan . --subagent dast --target-url http://localhost:3000 --force

# Skip artifact validation checks
securevibes scan . --subagent code-review --skip-checks

Sub-Agent Dependencies:

• assessment → Creates SECURITY.md
• threat-modeling → Needs SECURITY.md → Creates THREAT_MODEL.json
• code-review → Needs THREAT_MODEL.json → Creates VULNERABILITIES.json
• report-generator → Needs VULNERABILITIES.json → Creates scan_results.json
• dast → Needs VULNERABILITIES.json → Creates DAST_VALIDATION.json

Interactive Workflow:

When running a sub-agent, SecureVibes checks for existing artifacts:

$ securevibes scan . --subagent dast --target-url http://localhost:3000

🔍 Checking prerequisites for 'dast' sub-agent...
✓ Found: .securevibes/VULNERABILITIES.json (modified: 2h ago, 10 issues)

⚠️  Re-running DAST will overwrite existing results.

Options:
  1. Use existing VULNERABILITIES.json and run DAST only [default]
  2. Re-run entire scan (all sub-agents)
  3. Cancel

Choice [1]:

Example output:

$ securevibes scan . --debug

🛡️ SecureVibes Security Scanner
AI-Pow