Choose the project directory where you want to run Bob. Install into that project, not into this source checkout unless you are developing Bob itself.
1. Install
npm install --global hacker-bob@latest
hacker-bob install /path/to/your/project
cd /path/to/your/project
2. Verify the local MCP runtime
node -e "require('./mcp/server.js'); console.log('MCP ok')"
3. Restart your host and run Bob
Restart your host CLI from the same project directory, then run the matching command:
[!WARNING] Run Bob only against targets you own or are explicitly authorized to test. Replace
<authorized-target>with an approved domain, contract address, or repository path.
Check a local installation and reduce the full doctor report to a quick readiness signal:
hacker-bob doctor ./project \
--adapter claude \
--json \
| jq '{
ready: .ok,
host: .adapters[0],
passed: (
.checks
| map(select(.status == "ok"))
| length
)
}'
The doctor demo above was generated with VHS from a real, isolated Hacker Bob install (view source). It checks only a disposable local workspace: no live target, recon, signup, or scan.
Evaluation start against a controlled lab target
Full installation doctor
Fresh-session status
17 CVE IDs credited across nine open-source projects, all produced by Bob. Fourteen IDs link to a public CVE record or project advisory; the remaining three are assigned but not public yet. The portfolio matches Hacker Bob's live receipts. rpcbind was co-reported with AISLE; Samba credits Bob as an additional reporter alongside the DREAM team.
03: The evidence engine
Hacker Bob installs a local MCP runtime into a project directory and connects it to Claude Code, Codex, Kimi CLI, or another MCP-capable host. The runtime coordinates surface mapping, authentication setup, parallel surface testing, finding verification, grading, reporting, and local evidence handling.
Discover. Test. Prove.
Bob can evaluate staging or authorized live applications, checked-out open-source repositories, smart-contract surfaces, and pull-request diffs in continuous integration.
Seven stages. One evidence chain.
Bob follows a structured workflow:
flowchart LR
SD["SURFACE<br/>DISCOVERY"] --> AU["AUTH"]
AU --> EV["EVALUATE"]
EV --> CH["CHAIN"]
CH --> VE["VERIFY"]
VE --> GR["GRADE"]
GR --> RE["REPORT"]
classDef stage fill:#111116,stroke:#F5B83B,color:#F4F0E6,stroke-width:2px
classDef report fill:#F5B83B,stroke:#F5B83B,color:#050508,stroke-width:2px
class SD,AU,EV,CH,VE,GR stage
class RE report
linkStyle default stroke:#F5B83B,stroke-width:2px
SURFACE_DISCOVERY: Collects subdomains, live hosts, archived URLs, crawled URLs, nuclei signals, JavaScript hints, and optional deep-surface-discovery lead data.AUTH: Attempts authorized account setup when possible and records usable profiles for later differential testing.EVALUATE: Starts parallel evaluators against runtime-prioritized attack surfaces.CHAIN: Evaluates whether individual findings combine into higher-impact scenarios.VERIFY: Runs independent verification passes and collects bounded evidence for surviving reportable findings.GRADE: Scores confirmed findings and decides whether they are ready to submit, should be held, or should be discarded.REPORT: Produces a clean report with verified proof and evidence references.
MCP ranking computes runtime priority for status views and evaluator briefs. Imports and public-intel fetches do not rewrite attack_surface.json.
Supported surfaces
Open-source software (OSS) project review mode
Local open-source project review runs against a checked-out repository instead of a live target domain. It inventories repository files, writes a session-scoped Docker plan, and keeps requested dependency installs and build reproductions inside a Docker image. Docker command replay mounts the repository read-only by default and uses a session-owned writable work directory. Native C/C++ projects receive dedicated parser, protocol, and memory-safety analysis grounded in reachable files and functions.
Local multi-session dashboard
For a local read-only dashboard over multiple concurrent sessions:
hacker-bob dashboard --repo-only
The dashboard binds to 127.0.0.1:4873 by default and reads ~/hacker-bob-sessions. It shows OSS/repo progress, pending handoffs, claims, verification/evidence/grade state, and cross-session bottlenecks.
04: CI diff review
Bob can review pull request (PR) diffs automatically using GitHub Actions. The review runs headless inside GitHub-hosted runners and posts inline comments plus a Check Run result on every PR.
Quick setup
-
Set org-level secrets and variables once in your GitHub organization (Settings > Secrets and variables > Actions):
-
Add the caller workflow to each repository you want reviewed. Create
.github/workflows/bob-review.ymlwith the minimal content below:name: Bob Diff Review on: pull_request: types: [opened, synchronize, reopened] permissions: pull-requests: write checks: write contents: read jobs: bob-review: uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1 secrets: inheritThat is the complete file.
secrets: inheritpropagates the org-level secrets automatically; no per-repository secret declarations are required.
Optional inputs
Pass these under with: on the bob-review job if you need to override the
reusable workflow defaults:
Example with min-severity-for-failure overridden:
jobs:
bob-review:
uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1
secrets: inherit
with:
min-severity-for-failure: critical
bob-workflows-ref: v1
Viewing findings
- Inline PR comments: Bob posts a comment on each changed line that contains a finding. Comments include severity, a short description, and a suggested fix when available.
- Check Run: A "Bob Diff Review" check appears in the PR Checks tab. The
summary shows
findings_count,critical_count, and links to the full report artifact. - Actions log: The "Log review outputs" step in the run log prints
findings_count,critical_count, andreview_urlfor quick triage.
Fork PRs
Forked PRs do not receive org-level secrets, and same-repo PRs may also run before reviewer credentials are configured. The workflow detects missing Anthropic credentials and skips the Bob review steps instead of failing the PR check in setup. No additional guard is needed in the caller workflow.
Versioning
Pin the reusable workflow to a release tag or full commit SHA. If you override
bob-workflows-ref, set it to the same immutable ref so the workflow checks out
the matching local action source:
uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1
05: Safety boundary
[!WARNING] Only run Bob against targets, accounts, applications, APIs, and infrastructure you own or are explicitly authorized to test. Bob does not prove authorization, enforce a program policy, guarantee containment, or control arbitrary host shell commands and unrelated browser activity.
Bob runs offensive security on surfaces you control: your own code in CI, your staging environments, and authorized live targets. It can send real network requests, run local surface-discovery tools, import local artifacts, and preserve sensitive run data on disk. You are responsible for using it only where you have permission.
Only run Bob against targets, accounts, applications, APIs, and infrastructure you own or are explicitly authorized to test. Read the scope and rules of engagement before starting an evaluation.
Bob does not prove authorization, enforce a program policy, or guarantee containment. For session-bound MCP tools, caller target_domain is only a lookup key: Bob authorizes against initialized session state, validates the stored target and target_url, and rejects drift before handlers run. Bob's MCP-scoped HTTP tools additionally require a public target_domain and only send first-party target-host requests; browser auto-signup routes page HTTP requests through a target-host guard but refuses effective block_internal_hosts: true because Chromium resolves network destinations outside Bob's safeFetch transport. Bob does not control arbitrary host shell commands, unrelated browser activity, or external surface-discovery binaries. By default, normal, yolo, and compatible legacy sessions allow public first-party hostnames that resolve to private infrastructure; paranoid sessions default to direct-egress DNS/private-address blocking unless the operator starts the session with --allow-internal-hosts for an explicitly authorized internal/lab program. First-party host scope is not DNS-rebinding or SSRF protection. Bob uses the packaged Public Suffix List via psl to reject public-suffix-only target_domain values and isolate registrable tenant domains. If that packaged list is stale, an operator can set BOB_PSL_OVERLAY_FILE to a local suffix file before running Bob; overlay matches are recorded in HTTP audit rows with public_suffix_source and psl_overlay_file, and the overlay is not a per-request bypass. For tools that support it, pass --block-internal-hosts or block_internal_hosts: true when you need local DNS/private-address blocking outside paranoid mode. The effective value is persisted in state and HTTP audit rows. That stricter mode is only available on direct egress, not proxy-backed egress profiles where target DNS and routing happen outside Bob.
Bob binds the selected egress_profile to the session at bob_init_session and records a redacted egress_profile_identity_hash in state, HTTP audit, evaluator briefs, signup responses, pipeline events, and analytics. Egress-bound HTTP and signup tools require initialized session state; legacy sessions may default presentation/progress fields, but missing or drifted authority fields such as target, target_url, internal-host policy, or egress identity fail closed for tools that rely on them. Bob hashes the profile name, region, proxy-configured bit, proxy route, and env/source identity, excluding raw credentials and description text; credential rotation on the same proxy route is allowed, but profile, route, or source drift fails closed.
Smart-contract RPC/REST tools use a separate direct-only model: shipped public ladders, explicit endpoints / fork_urls, and BOB_<FAMILY>_RPCS_<NETWORK> env overrides must be public HTTPS endpoints. Bob filters localhost/private/internal literals and performs bounded DNS private-address preflight for SC endpoints. Bob-owned Node SC reads and EVM source fetches then pin the HTTPS socket lookup to one of those preflighted public DNS answers. Fork runners are different: Foundry, Anchor, Aptos, Sui, Substrate, CosmWasm, and Halmos subprocesses run with proxy/RPC/secret env scrubbed, then receive only runner-created fork URL env or CLI args that came from preflighted public endpoints; Bob does not control or DNS-pin the downstream CLI socket. SC RPC does not use egress_profile proxy routing, and private/localnet RPC is unsupported by default until a per-family opt-in policy exists. Returned endpoint evidence and policy rejections redact credentials and query values.
If your Claude Code workflow uses --dangerously-skip-permissions, use it only in a dedicated workspace for authorized security testing.
Data and security model
Bob stores local run state, telemetry, and evidence under a session root that all reads and writes resolve to. The pre-v2.0 ~/bounty-agent-sessions/ root is no longer auto-resolved or auto-copied; inspect a leftover legacy root with hacker-bob install /path/to/your/project --purge-legacy-session-root (dry-run by default, --yes to delete). Treat these directories as sensitive. They can contain target names, request metadata, notes, credentials metadata, and report evidence from authorized testing.
Session roots and concurrent engines
Bob elects exactly one engine per session root. To run engines concurrently, give each workspace a disjoint root. An engine sharing state with another engine cannot enforce gates safely while that state is changing. The installer creates ~/hacker-bob-sessions-<workspace>-<hash> from the workspace path and writes it as BOB_SESSIONS_ROOT in that workspace's .mcp.json server environment and .claude/settings.json.
BOB_SESSIONS_ROOT is operator configuration. The engine reads and freezes it at boot; no agent or MCP tool can change it. Keep the path absolute, private to your user, and outside every other session root.
Existing workspaces that still have sessions under ~/hacker-bob-sessions/ keep using that shared root. To move one, run mv ~/hacker-bob-sessions/<target-domain> ~/hacker-bob-sessions-<workspace>-<hash>/ using the exact destination printed by the installer, then reinstall. The standalone dashboard reads the BOB_SESSIONS_ROOT exported by its shell. Point it at one root explicitly with BOB_SESSIONS_ROOT=~/hacker-bob-sessions-<workspace>-<hash> hacker-bob dashboard.
Operator caution: disjoint roots make concurrent engines safe; they do not make concurrent evaluations of the same target safe. Rate limits, circuit breakers, and request budgets are per engine. Two engines evaluating one target double its request volume without coordinating. Evaluate different targets.
During an evaluation, Bob may make outbound HTTP requests, run local surface-discovery tools, import HTTP or static artifacts, and use host-side reasoning over the collected context. Optional third-party services and dependencies, such as browser automation dependencies, CAPTCHA solving, public-intel sources, or external surface-discovery tools, are used only when you configure the relevant dependencies or credentials.
The npm packages are published through the project release workflow with npm provenance. hacker-bob is the canonical package; hacker-bob-cc, hacker-bob-codex, and hacker-bob-kimi are small wrapper packages that depend on the matching canonical version.
Read DISCLAIMER.md before using Bob on any target.
06: Reference
Dense operational details stay here: complete, searchable, and out of the quick path.
Installation
hacker-bob is the canonical npm package:
npm install --global hacker-bob@latest
hacker-bob install /path/to/your/project
Adapter-specific installs are available when you want to choose the host explicitly:
hacker-bob install /path/to/your/project --adapter claude
hacker-bob install /path/to/your/project --adapter codex
hacker-bob install /path/to/your/project --adapter generic-mcp
hacker-bob install /path/to/your/project --adapter kimi
hacker-bob install /path/to/your/project --adapter all
The installer is idempotent and preserves unrelated host configuration. It writes the shared MCP runtime to mcp/, neutral Bob resources to .hacker-bob/, and adapter-specific files for the selected host.
Underneath that narrative, the engine drives a strict six-state lifecycle FSM (SETUP -> OPEN_FRONTIER -> CLAIM_FREEZE -> VERIFY -> GRADE -> REPORT, with defined back-edges so an operator can re-enter OPEN_FRONTIER from any later state). The persisted SessionNucleus (session-nucleus.json) is the sole authority for a session's identity, scope, and lifecycle state; state.json is a grant-free READ PROJECTION derived from it, never a second write path; and session-events.jsonl is provenance/audit only. A session that predates (or somehow lost) its nucleus gains one exactly once through migrateLegacySessionAuthority, and its legacy projection stays readable but grant-free until that migration runs. bob_read_session_nucleus and bob_read_session_summary both surface a verified boolean alongside the nucleus so callers can distinguish a cryptographically verified nucleus from an unverified state-derived fallback.
OSS Project Review Mode
When --adapter is omitted, Bob chooses an adapter from prior install metadata, host environment markers, project files, and installed host CLIs. Claude is the final fallback.
The MCP server name is hacker-bob. You will see hacker-bob in .mcp.json, in claude mcp list, and as the prefix on tool names such as mcp__hacker-bob__bob_*. Existing v1.x installs are auto-migrated on the next install or update: the legacy bountyagent server key and mcp__bountyagent__* permission strings are rewritten to the canonical hacker-bob form while operator-managed sibling servers and custom permissions are preserved.
Source installs are for contributors and local development:
git clone https://github.com/vmihalis/hacker-bob.git
cd hacker-bob
npm ci
./install.sh /path/to/your/project
Commands
Claude Code commands:
/bob-evaluate <authorized-target> # start a normal evaluation
/bob-evaluate <authorized-target> --deep # broaden discovery and follow-up
/bob-evaluate resume <authorized-target> # resume an existing session
/bob-status # show latest session status
/bob-debug # inspect the latest local run
/bob-update # preview and install the latest release
/bob-export # create a release-scoped improvement bundle
/bob-egress # manage operator-controlled egress profiles
Codex uses the same command names with a $ prefix:
$bob-evaluate <authorized-target>
$bob-status
$bob-debug
$bob-update
$bob-export
$bob-egress
Kimi CLI uses a /skill: prefix:
/skill:bob-evaluate <authorized-target>
/skill:bob-status
/skill:bob-debug
/skill:bob-update
/skill:bob-export
/skill:bob-egress
For install diagnostics:
hacker-bob doctor /path/to/your/project
hacker-bob doctor /path/to/your/project --adapter codex
hacker-bob doctor /path/to/your/project --adapter kimi
Requirements
- Node.js 20 or newer
- One supported host: Claude Code, Codex, Kimi CLI, or another MCP-capable host
curlandpython3- A dedicated project directory for the installed runtime
Optional surface-discovery tools improve coverage when they are installed:
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install github.com/owasp-amass/amass/v4/...@latest
go install github.com/tomnomnom/assetfinder@latest
go install github.com/projectdiscovery/chaos-client/cmd/chaos@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install github.com/projectdiscovery/tlsx/cmd/tlsx@latest
go install github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/PentestPad/subzy@latest
git clone https://github.com/ticarpi/jwt_tool ~/jwt_tool
python3 -m pip install -r ~/jwt_tool/requirements.txt
Bob still runs without the optional tools; the installed toolset determines which surface-discovery paths are available.
Updates
From Claude Code:
/bob-update
From Codex:
$bob-update
From Kimi:
/skill:bob-update
From a shell:
hacker-bob update /path/to/your/project --adapter claude
After an update, fully restart your host CLI in the project directory so it reloads commands, MCP config, hooks, and skills.
Bob also checks for available updates once per day on session start and stores the result under ~/.cache/hacker-bob/update-checks/. Status views read that local cache.
Exporting run data
After testing with an installed release, run /bob-export in Claude, $bob-export in Codex, or /skill:bob-export in Kimi. Bob writes a timestamped bundle under:
~/bounty-agent-telemetry/release-bundles/v<version>/
The bundle includes summaries, filtered telemetry, session references, and a handoff document for improving future releases. Export is read-only and does not touch targets.
Troubleshooting
Use the doctor command first:
hacker-bob doctor /path/to/your/project --adapter all
Common checks:
node -e "require('./mcp/server.js'); console.log('MCP ok')"should pass from the installed project.- Claude Code must be restarted after install or update before
/bob-*commands and MCP settings load. - Codex must be restarted after install or update before
$bob-*skills and local plugin wiring load. - Kimi CLI must be restarted after install or update before
/skill:bob-*skills and MCP config load. .mcp.jsonshould contain anmcpServers["hacker-bob"]entry pointing at the installed project'smcp/server.js. v1.x installs are auto-migrated to this canonical key on next install or update.- If an upgrade leaves
mcp/tools/missing, rerun the installer withhacker-bob@latest.
Detailed guides:
Development
For local development on Bob itself:
npm test
npm run test:native-darwin # Darwin arm64 + Node.js 20 qualification
npm run release:check
npm run release:check:dependencies
To push the current checkout into a separate test workspace:
./dev-sync.sh /absolute/path/to/test-workspace
./dev-sync.sh /absolute/path/to/test-workspace --adapter codex
./dev-sync.sh /absolute/path/to/test-workspace --adapter kimi
The maintainer workflow is documented in CLAUDE.md.
