Securevibes Scanner

SecureVibes Scanner

AI-native security platform that detects vulnerabilities using Claude AI. Multi-subagent pipeline: assessment → threat modeling → code review → report generation → optional DAST. Supports incremental scanning for continuous monitoring.

Prerequisites

1. Install the CLI: pipx install securevibes (preferred) or uv tool install securevibes. Avoid pip install — it can create stale shims if you have multiple Python environments.
2. Authenticate with Anthropic (one of):
   • Max/Pro subscription (recommended): If you're authenticated via Claude Code or Claude CLI OAuth, no API key is needed. The Claude Agent SDK picks up your OAuth session automatically. When running inside OpenClaw, leave ANTHROPIC_API_KEY unset or blank — the SDK handles auth.
   • API key: export ANTHROPIC_API_KEY=your-key-here (from console.anthropic.com)

Security Notes

• Always use the scripts/scan.sh wrapper for full scans — it validates paths and rejects shell metacharacters before invoking securevibes.
• Never interpolate unsanitized user input into shell commands.
• The wrapper uses realpath to resolve paths safely and rejects any path containing ;, |, &, $, backticks, or other metacharacters.
• Scan targets must be local directories. Clone remote repos to a known safe location first, then pass the resolved path to the wrapper.
• DAST scans make network requests to the --target-url you provide. Only use against apps you own or have permission to test.

Execution Model

Full scans take 10-30 minutes across 4 phases. Run them as background jobs (cron or subagent), not inline.

Incremental scans take 2-10 minutes — they only scan commits since the last run.

Full Scan (One-Shot)

Running a Scan

1. Clone the target repo to a local directory
2. Run the wrapper script: bash scripts/scan.sh /path/to/repo --force --debug
3. Results appear in /path/to/repo/.securevibes/

Background Execution (Recommended)

For OpenClaw users, schedule scans as cron jobs:

• Use sessionTarget: "isolated" with payload.kind: "agentTurn"
• Set payload.timeoutSeconds: 2700 (45 minutes) to allow all phases to complete
• Use delivery.mode: "announce" to get notified when done

The agentTurn message should instruct the subagent to:

1. cd into the repo and git pull for latest code
2. Clean previous .securevibes/ artifacts
3. Run securevibes scan . --force via the wrapper script
4. Read and summarize the results from .securevibes/scan_report.md

Incremental Scan (Continuous Monitoring)

The incremental scanner (ops/incremental_scan.py) tracks the last-scanned commit and only scans new commits. Designed for cron-driven continuous security monitoring.

How It Works

1. Tracks an anchor commit in .securevibes/incremental_state.json
2. On each run: fetches remote, compares HEAD to anchor
3. If new commits exist: runs securevibes pr-review on the diff
4. Updates anchor to new HEAD after successful scan
5. If no new commits: exits cleanly (no scan, no cost)

Setup

Step 1: Run an initial full scan (if not already done)

The incremental scanner requires .securevibes/SECURITY.md and .securevibes/THREAT_MODEL.json to exist. These come from an initial full scan:

securevibes scan <repo-path> --model sonnet

Skip this step if the repo already has a .securevibes/ directory with these files.

Step 2: Bootstrap incremental state

Run the wrapper once to seed the anchor commit (no scan runs, just records current HEAD):

python3 ops/incremental_scan.py --repo <repo-path> --remote origin --branch main

This creates .securevibes/incremental_state.json with status: "bootstrap".

Step 3: Configure the cron

For OpenClaw users, create a cron job:

openclaw cron create \
  --name "securevibes-incremental" \
  --cron "*/30 * * * *" \
  --tz "America/Los_Angeles" \
  --agent main \
  --session isolated \
  --timeout-seconds 900 \
  --announce \
  --message "Run incremental security scan: python3 <skill-path>/ops/incremental_scan.py --repo <repo-path> --remote origin --branch main --model sonnet --severity medium --scan-timeout-seconds 600. Read .securevibes/incremental_scan.log for results. If new findings, summarize them."

Replace <skill-path> with the installed skill path and <repo-path> with the target repo.

Step 4: Verify

# Check state
cat <repo-path>/.securevibes/incremental_state.json

# After first scheduled run, check logs
tail -10 <repo-path>/.securevibes/incremental_scan.log

# Check findings
cat <repo-path>/.securevibes/PR_VULNERABILITIES.json

Incremental Scanner Options

python3 ops/incremental_scan.py [options]

Operational Guarantees

• File lock at .securevibes/.incremental_scan.lock prevents overlapping runs
• Atomic state writes (fsync + os.replace) prevent corruption
• Structured logging at .securevibes/incremental_scan.log
• Run records saved to .securevibes/incremental_runs/ (one JSON per run)

Rewrite Policy

When last_seen_sha is not an ancestor of the new remote HEAD (e.g., force push):

Full Scan Commands Reference

Scan

securevibes scan <path> [options]

Report

securevibes report <path> — Display a previously saved scan report.

Mapping Requests to Actions

Subagent Pipeline

Runs sequentially. Each phase builds on the previous:

1. assessment → Architecture & attack surface → .securevibes/SECURITY.md
2. threat-modeling → STRIDE-based analysis → .securevibes/THREAT_MODEL.json
3. code-review → Vulnerability detection → .securevibes/VULNERABILITIES.json
4. report-generator → Consolidated report → .securevibes/scan_report.md
5. dast (optional) → Dynamic validation against running app

Presenting Results

After a scan completes:

1. Read .securevibes/scan_report.md (or .securevibes/scan_results.json for structured data)
2. Summarize: total findings by severity (Critical > High > Medium > Low)
3. Highlight top 3 most critical with file locations and remediation
4. Offer next steps: run DAST, fix specific issues, re-scan after changes

Links

• Website: https://securevibes.ai
• PyPI: https://pypi.org/project/securevibes/
• GitHub: https://github.com/anshumanbh/securevibes