π · VIBEHACKER

The autonomous security testing harness for pi-mono. Hypothesis-tree REPL · tool auto-install · pipeline chaining · 30+ bug-bounty tools · self-evolving skills.

⚠️ Authorized testing only. This harness has unleashed scope by design. You are responsible for written authorization, scope boundaries, and legal exposure. Every action is audit-logged. See docs/SECURITY.md.

What is VIBEHACKER?

VIBEHACKER is a proactive, autonomous security testing agent that turns your terminal into an offensive-security cockpit. It doesn't just answer questions — it drives the attack surface, runs real bug-bounty tools, chains exploits, and generates HackerOne-quality reports.

| Instead of this... | VIBEHACKER does this | |---|---| | "Describe how to test for XSS" | vibehack_run_httpx → vibehack_run_nuclei → browser verify → report | | "Can you check this endpoint?" | Full autonomous mode for 10-50 turns, no hand-holding | | "How do I install subfinder?" | vibehack_install_tool({tool:"subfinder"}) — auto skills | | A long chat with strategy essays | Tool output and evidence, nothing else |

One-Second Install

# Linux / WSL / macOS — one line
curl -fsSL https://raw.githubusercontent.com/m4xx101/pi-vibehack/main/install.sh | bash

# npm — any platform
npm install -g @m4xx101/vibeshack
pi-vibehack install

# Windows PowerShell (as admin)
Set-ExecutionPolicy Bypass -Scope Process -Force
irm https://raw.githubusercontent.com/m4xx101/pi-vibehack/main/install.ps1 | iex

Your First 30 Seconds

pi                          # boot the agent
/vibehack juice-shop.local  # point it at a target

The agent immediately:

1. Creates the hypothesis tree
2. Searches for relevant tools
3. Loads and runs them
4. Records evidence
5. Confirms or dead-ends findings

That's it. You don't write a strategy — the agent executes one.

What Makes It Different

🔧 Tool Auto-Install — Install Any Tool, Get a Skill Instantly

VIBEHACKER isn't limited to the bundled 30+ tools. If it needs a tool that's not installed:

vibehack_install_tool({tool:"rustscan", source:"cargo"})

It detects the package manager (Go, npm, pip, cargo, apt, git), installs the binary, runs --help to understand usage, and auto-creates a categorized <toolname>-skill.md. The tool is immediately available in the catalogue. This works for ANY tool on GitHub/GitHub/pkg.go.dev/npm/pip.

🔗 Pipeline Chaining — Chain Tools Like Unix Pipes

vibehack_pipeline({
  name: "Full Recon Pipeline",
  steps: [
    {tool_id:"vibehack_run_subfinder", args:["-d","target.com","-silent"]},
    {tool_id:"vibehack_run_httpx",     read_from_step:0, args:["-silent","-status-code","-tech-detect"]},
    {tool_id:"vibehack_run_ffuf",      read_from_step:1, args:["-u","FUZZ","-w","-","-mc","200,301,302"]}
  ]
})

Subfinder discovers domains → httpx checks which are alive → ffuf fuzzes them. All in a single call. Results stream incrementally.

🧠 VIBEHACKER Persona — Expert Hacker, Not Chatbot

The agent thinks like an offensive security researcher:

• Chains vulnerabilities — open redirect → SSRF → IMDS → credential theft
• Never gives up — dead end means pivot, not stop
• Probes everything — JS source maps, API endpoints, GraphQL introspection, request smuggling, cache poisoning, prototype pollution
• Documents in real-time — evidence recorded before moving on

📊 Live Status — Know What's Happening

⚡ 2026-05-06-juice-shop-local
3✓ 1○ 0✗  runs:12  cost:$0.14  pipes:1  vulns:2  persona:web-application
█████████████████████░░░░░ 3/4

Confirmed, open, dead nodes. Tool run count. Cost in USD. Pipelines executed. Vulnerabilities found. Active persona. Updated every tool call.

17 Tools at Your Fingertips

| Category | Tools | When to Use | |----------|-------|-------------| | Tree mutations | expand, prune, confirm, evidence, dead_end | Always active — structure every finding | | Proposals | propose_chain, propose_specialist | Stage multi-step exploits, request specialist help | | Recon | tool_search, load_tools, unload_tools | Discover and load the right tool for the surface | | Run wrappers | 30+ vibehack_run_* | Subfinder, nuclei, sqlmap, ffuf, httpx, nmap, etc. | | Install | install_tool | Install any new tool — auto creates skill | | Pipeline | pipeline | Chain multiple tools back-to-back | | Verification | browser_verify, canary_verify | Browser DOM verification, OOB canary planting | | Reporting | report_vuln | HackerOne-style markdown reports | | Persona | use_persona | Swap specialist persona mid-engagement | | Recall | recall | Query cross-engagement memory |

Slash Commands

| Command | When to Use | Example | |---------|-------------|---------| | /vibehack <target> | Start every engagement | /vibehack api.target.com | | /vibehack-auto <N> | Let the agent drive itself | /vibehack-auto 20 | | /steer <instruction> | Course-correct mid-engagement | /steer focus on API auth | | /vibehack-tree | View the hypothesis tree | /vibehack-tree | | /vibehack-cost | Check spending | /vibehack-cost | | /persona <name> | Switch specialist hat | /persona ssrf | | /vibehack-complete | Wrap up, get report | /vibehack-complete | | /vibehack-pin <fact> [--global] | Remember across turns | /vibehack-pin admin: admin:admin | | /vibehack-update | Self-update | /vibehack-update |

Full reference: docs/COMMANDS.md

Worked Example: Full Engagement

$ pi

# Point at target
/vibehack https://api.target.com

# Agent creates root node, loads tools, runs httpx probe
# (happens automatically — no strategy essays)

# Steer toward a specific surface
/steer focus on the /api/v1/fetch endpoint — looks like an SSRF candidate

# Agent switches to SSRF persona, runs curl against the endpoint,
# tests blind SSRF with canary_verify, gets callback

# Agent reports the finding automatically:
# vibehack_confirm → vibehack_report_vuln({severity:"critical", ...})
# Report written to findings.md

# View what happened
/vibehack-tree
# n_root → target
# └─ n_1a [confirmed] SSRF on /api/v1/fetch (CVSS 9.1, CWE-918)

# Check cost
/vibehack-cost
# Engagement: $0.08 — cheaper than a coffee

# Wrap up
/vibehack-complete

Architecture (One Paragraph)

VIBEHACKER is a pi-mono extension. It registers 17+ tools (tree mutations + tool wrappers), 8 lifecycle hooks (session_start, before_agent_start, tool_call, tool_result, before_provider_request, agent_end, session_before_compact, resources_discover), and 15+ slash commands. Engagement state lives at ~/.pi/agent/vibehack/engagements/<id>/events.jsonl — append-only, schema-validated. Tools are eagerly registered but inactive; vibehack_load_tools exposes them via pi.setActiveTools(). The agent_end hook drives the autonomous loop. New tools are installed and auto-skilled via vibehack_install_tool.

Docs

| Doc | Covers | |-----|--------| | QUICKSTART.md | 5-minute first engagement | | COMMANDS.md | Slash commands & planner tools reference | | INSTALL.md | Profiles, soft deps, local-model setup | | TROUBLESHOOTING.md | Common problems | | FAQ.md | Frequently asked questions | | ARCHITECTURE.md | Deep dive into how it works |

Testing

npm test

350 tests across 62 vitest files. All passing. Tests cover: tool result shape, engagement bootstrap, lazy tool loading, persona switching, report generation, browser verify, auto-loop, events schema, and more.

Quick Reference URLs

| Action | URL / Command | |--------|---------------| | Bug reports | github.com/m4xx101/pi-vibehack/issues | | npm package | @m4xx101/vibeshack | | Source | git clone https://github.com/m4xx101/pi-vibehack | | Bash install | curl -fsSL https://raw.githubusercontent.com/m4xx101/pi-vibehack/main/install.sh \| bash | | Windows install | irm https://raw.githubusercontent.com/m4xx101/pi-vibehack/main/install.ps1 \| iex |

v1.5.0 — MIT. Authorized testing only.