Skip to content
Back to search

hacker-bob

A local MCP runtime that attacks what you own and only reports what it proved. 17 CVEs across 9 projects came out of this repo. Install: npx -y hacker-bob@latest install /path/to/project, then run /bob-evaluate target.com

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vmihalis--hacker-bob/badge.svg)](/listings/vmihalis--hacker-bob)

HTML

<a href="/listings/vmihalis--hacker-bob"><img src="/api/listings/vmihalis--hacker-bob/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install --global hacker-bob@latest
hacker-bob install /path/to/your/project
cd /path/to/your/project

<details> <summary><strong>Watch a clean installation</strong></summary>

<p align="center"> </p>

The installation animation uses the equivalent global-CLI form against a disposable local workspace and filters the real output to its key milestones. It was generated with [VHS](https://github.com/charmbracelet/vhs) ([view source](docs/media/hacker-bob-demo.tape)).

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 635 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">Hacker Bob</h1>
  2. <p align="center">
  3. <strong>17 Common Vulnerabilities and Exposures (CVE) IDs credited across 9 projects, all produced by Bob.</strong><br />
  4. One was co-reported with AISLE; one credits Bob as an additional reporter. <a href="#receipt-portfolio">Review the linked receipts.</a>
  5. </p>
  6. <p align="center">
  7. Hacker Bob is an open-source autonomous bug bounty hunter built around a local Model Context Protocol (MCP) runtime.<br />
  8. Run it against authorized targets or in continuous integration (CI).
  9. </p>
  10. <p align="center">
  11. <a href="https://hackerbob.ai/">
  12. <img src="docs/media/readme-hero.png" alt="Hacker Bob. Point Bob at an authorized domain, contract address, or repository; Bob reports findings that survive independent verification." width="100%" />
  13. </a>
  14. </p>
  15. <p align="center">
  16. <a href="https://github.com/vmihalis/hacker-bob/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/vmihalis/hacker-bob/ci.yml?branch=main&amp;style=flat-square&amp;label=CI&amp;labelColor=111116&amp;color=F0B510" /></a>
  17. <a href="https://www.npmjs.com/package/hacker-bob"><img alt="hacker-bob on npm" src="https://img.shields.io/npm/v/hacker-bob?style=flat-square&amp;label=hacker-bob&amp;labelColor=111116&amp;color=F0B510" /></a>
  18. <a href="LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/vmihalis/hacker-bob?style=flat-square&amp;labelColor=111116&amp;color=F0B510" /></a>
  19. <a href="https://securityscorecards.dev/viewer/?uri=github.com/vmihalis/hacker-bob"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/vmihalis/hacker-bob/badge" /></a>
  20. </p>
  21. <p align="center">
  22. <a href="#01-run-bob"><strong>01 RUN</strong></a> ·
  23. <a href="#receipt-portfolio"><strong>02 PROOF</strong></a> ·
  24. <a href="#03-the-evidence-engine"><strong>03 SYSTEM</strong></a> ·
  25. <a href="#04-ci-diff-review"><strong>04 CI</strong></a> ·
  26. <a href="#05-safety-boundary"><strong>05 SAFETY</strong></a> ·
  27. <a href="#06-reference"><strong>06 REFERENCE</strong></a> ·
  28. <a href="#07-contributing"><strong>07 CONTRIBUTE</strong></a>
  29. </p>
  30. <p align="center">
  31. <code>LOCAL MCP</code> · <code>AUTHORIZED TARGETS</code> · <code>EVIDENCE BEFORE REPORTING</code>
  32. </p>
  33. <p align="center">
  34. <img src="docs/media/readme-signal-deck.svg" alt="17 credited CVE IDs, nine open-source projects, four host adapters, and a local MCP runtime" width="100%" />
  35. </p>
  36. <p align="center">
  37. <img src="docs/media/readme-chapter-deploy.svg" alt="Chapter one: Deploy. Install, verify, and choose a host." width="100%" />
  38. </p>
  39. ## 01: Run Bob
  40. 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.
  41. ### 1. Install
  42. ```bash
  43. npm install --global hacker-bob@latest
  44. hacker-bob install /path/to/your/project
  45. cd /path/to/your/project
  46. ```
  47. <details>
  48. <summary><strong>Watch a clean installation</strong></summary>
  49. <p align="center">
  50. <img src="docs/media/hacker-bob-demo.gif" alt="Hacker Bob installing into a disposable local project" width="100%" />
  51. </p>
  52. The installation animation uses the equivalent global-CLI form against a disposable local workspace and filters the real output to its key milestones. It was generated with [VHS](https://github.com/charmbracelet/vhs) ([view source](docs/media/hacker-bob-demo.tape)).
  53. </details>
  54. ### 2. Verify the local MCP runtime
  55. ```bash
  56. node -e "require('./mcp/server.js'); console.log('MCP ok')"
  57. ```
  58. ### 3. Restart your host and run Bob
  59. Restart your host CLI from the same project directory, then run the matching command:
  60. > [!WARNING]
  61. > 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.
  62. | Host | Evaluate | Status | Update | Export |
  63. |---|---|---|---|---|
  64. | Claude Code | `/bob-evaluate <authorized-target>` | `/bob-status` | `/bob-update` | `/bob-export` |
  65. | Codex | `$bob-evaluate <authorized-target>` | `$bob-status` | `$bob-update` | `$bob-export` |
  66. | Kimi CLI | `/skill:bob-evaluate <authorized-target>` | `/skill:bob-status` | `/skill:bob-update` | `/skill:bob-export` |
  67. | Generic MCP host | Connect the generated `.mcp.json`, then follow `.hacker-bob/generic-mcp/hacker-bob.md`. | Use the host's MCP tool interface. | Re-run the shell updater. | Use the host's MCP tool interface. |
  68. | Shell | - | `hacker-bob doctor /path/to/your/project` | `hacker-bob update /path/to/your/project --adapter claude` | - |
  69. <details>
  70. <summary><strong>Watch Bob verify the installation</strong></summary>
  71. Check a local installation and reduce the full doctor report to a quick readiness signal:
  72. ```bash
  73. hacker-bob doctor ./project \
  74. --adapter claude \
  75. --json \
  76. | jq '{
  77. ready: .ok,
  78. host: .adapters[0],
  79. passed: (
  80. .checks
  81. | map(select(.status == "ok"))
  82. | length
  83. )
  84. }'
  85. ```
  86. <p align="center">
  87. <img src="docs/media/hacker-bob-doctor-demo.gif" alt="Hacker Bob checking a real isolated local installation" width="100%" />
  88. </p>
  89. The doctor demo above was generated with [VHS](https://github.com/charmbracelet/vhs) from a real, isolated Hacker Bob install ([view source](docs/media/hacker-bob-doctor-demo.tape)). It checks only a disposable local workspace: no live target, recon, signup, or scan.
  90. </details>
  91. <details>
  92. <summary><strong>View the individual real terminal captures</strong></summary>
  93. **Evaluation start against a controlled lab target**
  94. ![Hacker Bob starting an authorized evaluation in Claude Code](docs/media/evaluate-start.png)
  95. **Full installation doctor**
  96. ![Hacker Bob doctor reporting a healthy installation](docs/media/doctor-ok.png)
  97. **Fresh-session status**
  98. ![Hacker Bob status immediately after installation](docs/media/status-fresh.png)
  99. </details>
  100. <p align="center">
  101. <img src="docs/media/readme-chapter-proof.svg" alt="Chapter two: Prove. Review receipts, verification, grading, and reporting." width="100%" />
  102. </p>
  103. ## Receipt portfolio
  104. **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](https://hackerbob.ai/#receipts). rpcbind was co-reported with AISLE; Samba credits Bob as an additional reporter alongside the DREAM team.
  105. <details>
  106. <summary><strong>Watch the receipt portfolio</strong></summary>
  107. <p align="center">
  108. <img src="docs/media/hacker-bob-receipts-demo.gif" alt="Animated Hacker Bob receipt roll showing 17 CVE IDs across nine open-source projects" width="100%" />
  109. </p>
  110. The receipt roll mirrors that live portfolio; it is not simulated scan output. Red provides visual emphasis and does not assert Common Vulnerability Scoring System (CVSS) severity. Generated with [VHS](https://github.com/charmbracelet/vhs) from a checked-in [tape](docs/media/hacker-bob-receipts-demo.tape) and [receipt source](docs/media/hacker-bob-receipts-demo.sh).
  111. </details>
  112. <details>
  113. <summary><strong>Read the CVE receipt list</strong></summary>
  114. | Project | CVE IDs | Public source status | Reporter role |
  115. |---|---|---|---|
  116. | `stable-diffusion.cpp` | [`CVE-2026-47747`](https://www.cve.org/CVERecord?id=CVE-2026-47747), [`CVE-2026-47748`](https://www.cve.org/CVERecord?id=CVE-2026-47748), [`CVE-2026-47749`](https://www.cve.org/CVERecord?id=CVE-2026-47749), [`CVE-2026-47750`](https://www.cve.org/CVERecord?id=CVE-2026-47750) | Published CVE records | Sole reporter |
  117. | `netatalk` | [`CVE-2026-49387`](https://netatalk.io/security/CVE-2026-49387.html), [`CVE-2026-49388`](https://netatalk.io/security/CVE-2026-49388.html), [`CVE-2026-49389`](https://netatalk.io/security/CVE-2026-49389.html), [`CVE-2026-49390`](https://netatalk.io/security/CVE-2026-49390.html) | Published project advisories | Sole reporter |
  118. | `libcupsfilters` | [`CVE-2026-64611`](https://www.cve.org/CVERecord?id=CVE-2026-64611), [`CVE-2026-64612`](https://www.cve.org/CVERecord?id=CVE-2026-64612) | Published CVE records | Sole reporter |
  119. | `libtirpc` | `CVE-2026-66714`, `CVE-2026-66715` | Assigned; public records pending | Sole reporter |
  120. | `OpenSSH` | [`CVE-2026-35388`](https://www.cve.org/CVERecord?id=CVE-2026-35388) | Published CVE record | Sole reporter |
  121. | `libheif` | [`CVE-2026-49271`](https://www.cve.org/CVERecord?id=CVE-2026-49271) | Published CVE record | Sole reporter |
  122. | `Samba` | [`CVE-2026-3012`](https://www.cve.org/CVERecord?id=CVE-2026-3012) | Published CVE record | Additional reporter alongside the DREAM team |
  123. | `rpcbind` | [`CVE-2026-16277`](https://www.cve.org/CVERecord?id=CVE-2026-16277) | Published CVE record | Co-reported with AISLE |
  124. | `OpenEXR` | `CVE-2026-65979` | Assigned; public record pending | Sole reporter |
  125. </details>
  126. ## 03: The evidence engine
  127. 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.
  128. ### Discover. Test. Prove.
  129. | Discover | Test | Prove |
  130. |---|---|---|
  131. | Maps subdomains, live hosts, archives, crawled URLs, JavaScript hints, and repository surfaces. | Establishes authorized auth profiles and runs parallel evaluators against prioritized attack surfaces. | Independently verifies findings, collects bounded evidence, grades impact, and produces submission-ready reports. |
  132. | Imports local artifacts and optional public-intelligence leads without rewriting the canonical attack surface. | Evaluates whether isolated findings combine into higher-impact chains. | Keeps run state, telemetry, reports, and evidence local under a session-owned root. |
  133. Bob can evaluate staging or authorized live applications, checked-out open-source repositories, smart-contract surfaces, and pull-request diffs in continuous integration.
  134. ### Seven stages. One evidence chain.
  135. Bob follows a structured workflow:
  136. ```mermaid
  137. flowchart LR
  138. SD["SURFACE<br/>DISCOVERY"] --> AU["AUTH"]
  139. AU --> EV["EVALUATE"]
  140. EV --> CH["CHAIN"]
  141. CH --> VE["VERIFY"]
  142. VE --> GR["GRADE"]
  143. GR --> RE["REPORT"]
  144. classDef stage fill:#111116,stroke:#F5B83B,color:#F4F0E6,stroke-width:2px
  145. classDef report fill:#F5B83B,stroke:#F5B83B,color:#050508,stroke-width:2px
  146. class SD,AU,EV,CH,VE,GR stage
  147. class RE report
  148. linkStyle default stroke:#F5B83B,stroke-width:2px
  149. ```
  150. - `SURFACE_DISCOVERY`: Collects subdomains, live hosts, archived URLs, crawled URLs, nuclei signals, JavaScript hints, and optional deep-surface-discovery lead data.
  151. - `AUTH`: Attempts authorized account setup when possible and records usable profiles for later differential testing.
  152. - `EVALUATE`: Starts parallel evaluators against runtime-prioritized attack surfaces.
  153. - `CHAIN`: Evaluates whether individual findings combine into higher-impact scenarios.
  154. - `VERIFY`: Runs independent verification passes and collects bounded evidence for surviving reportable findings.
  155. - `GRADE`: Scores confirmed findings and decides whether they are ready to submit, should be held, or should be discarded.
  156. - `REPORT`: Produces a clean report with verified proof and evidence references.
  157. MCP ranking computes runtime priority for status views and evaluator briefs. Imports and public-intel fetches do not rewrite `attack_surface.json`.
  158. ### Supported surfaces
  159. | Surface | How Bob approaches it |
  160. |---|---|
  161. | **Web applications and application programming interfaces (APIs)** | Surface discovery, authorized account setup, first-party target-host requests, browser-assisted flows, parallel evaluation, and independent verification. |
  162. | **Smart contracts** | Public HTTPS RPC/REST ladders and preflighted endpoints, with dedicated fork runners for Foundry, Anchor, Aptos, Sui, Substrate, CosmWasm, and Halmos workflows. |
  163. | **Open-source repositories** | Repository inventory, session-scoped Docker plans, read-only repo mounts by default, and a dedicated native C/C++ parser, protocol, and memory-safety surface. |
  164. | **Pull-request diffs** | Headless GitHub Actions review with inline findings, a Check Run summary, and a full report artifact. |
  165. ### Open-source software (OSS) project review mode
  166. 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.
  167. ### Local multi-session dashboard
  168. For a local read-only dashboard over multiple concurrent sessions:
  169. ```bash
  170. hacker-bob dashboard --repo-only
  171. ```
  172. 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.
  173. <p align="center">
  174. <img src="docs/media/readme-chapter-operate.svg" alt="Chapter three: Operate. Configure CI, safety, reference, and contribution." width="100%" />
  175. </p>
  176. ## 04: CI diff review
  177. Bob can review pull request (PR) diffs automatically using GitHub Actions. The
  178. review runs headless inside GitHub-hosted runners and posts inline comments
  179. plus a Check Run result on every PR.
  180. ### Quick setup
  181. 1. **Set org-level secrets and variables** once in your GitHub organization
  182. (Settings > Secrets and variables > Actions):
  183. | Name | Type | Description |
  184. |---|---|---|
  185. | `ANTHROPIC_OAUTH_TOKEN` | Secret | Recommended Anthropic OAuth token from `claude setup-token` for the headless Claude reviewer. |
  186. | `ANTHROPIC_API_KEY` | Secret | Anthropic API key fallback for the headless Claude reviewer. Required only when `ANTHROPIC_OAUTH_TOKEN` is not set. |
  187. | `BOB_INSTALL_TOKEN` | Secret | Classic personal access token with `read:packages` for installing `@bobnetsec/*` packages. Add classic `repo` scope only if this same secret must check out a private source repository; otherwise keep checkout credentials separate. |
  188. | `BOB_VERSION` | Variable | Bob release tag to cache, e.g. `v1.2.3`. Shared across repos in the org so they reuse the same warm workspace cache. |
  189. 2. **Add the caller workflow** to each repository you want reviewed. Create
  190. `.github/workflows/bob-review.yml` with the minimal content below:
  191. ```yaml
  192. name: Bob Diff Review
  193. on:
  194. pull_request:
  195. types: [opened, synchronize, reopened]
  196. permissions:
  197. pull-requests: write
  198. checks: write
  199. contents: read
  200. jobs:
  201. bob-review:
  202. uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1
  203. secrets: inherit
  204. ```
  205. That is the complete file. `secrets: inherit` propagates the org-level
  206. secrets automatically; no per-repository secret declarations are required.
  207. <details>
  208. <summary><strong>Optional inputs, findings, fork PRs, and versioning</strong></summary>
  209. ### Optional inputs
  210. Pass these under `with:` on the `bob-review` job if you need to override the
  211. reusable workflow defaults:
  212. | Input | Default | Description |
  213. |---|---|---|
  214. | `min-severity-for-failure` | `high` | Minimum severity that sets the PR check to failed. Accepts `critical`, `high`, `medium`, or `low`. Set to `critical` to fail only on critical findings; set to `low` to fail on any finding. |
  215. Example with `min-severity-for-failure` overridden:
  216. ```yaml
  217. jobs:
  218. bob-review:
  219. uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1
  220. secrets: inherit
  221. with:
  222. min-severity-for-failure: critical
  223. bob-workflows-ref: v1
  224. ```
  225. ### Viewing findings
  226. - **Inline PR comments**: Bob posts a comment on each changed line that
  227. contains a finding. Comments include severity, a short description, and a
  228. suggested fix when available.
  229. - **Check Run**: A "Bob Diff Review" check appears in the PR Checks tab. The
  230. summary shows `findings_count`, `critical_count`, and links to the full
  231. report artifact.
  232. - **Actions log**: The "Log review outputs" step in the run log prints
  233. `findings_count`, `critical_count`, and `review_url` for quick triage.
  234. ### Fork PRs
  235. Forked PRs do not receive org-level secrets, and same-repo PRs may also run
  236. before reviewer credentials are configured. The workflow detects missing
  237. Anthropic credentials and skips the Bob review steps instead of failing the PR
  238. check in setup. No additional guard is needed in the caller workflow.
  239. ### Versioning
  240. Pin the reusable workflow to a release tag or full commit SHA. If you override
  241. `bob-workflows-ref`, set it to the same immutable ref so the workflow checks out
  242. the matching local action source:
  243. ```yaml
  244. uses: bobnetsec/bob-workflows/.github/workflows/bob-review.yml@v1
  245. ```
  246. </details>
  247. ## 05: Safety boundary
  248. > [!WARNING]
  249. > 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.
  250. 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.
  251. <details>
  252. <summary><strong>Full authorization, egress, browser, and smart-contract networking model</strong></summary>
  253. 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.
  254. 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.
  255. 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.
  256. 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.
  257. If your Claude Code workflow uses `--dangerously-skip-permissions`, use it only in a dedicated workspace for authorized security testing.
  258. </details>
  259. <details>
  260. <summary><strong>Session roots, concurrent engines, proxy handling, and stored data</strong></summary>
  261. ### Data and security model
  262. 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.
  263. ### Session roots and concurrent engines
  264. 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`.
  265. `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.
  266. 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`.
  267. **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.
  268. 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.
  269. 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.
  270. Read [DISCLAIMER.md](DISCLAIMER.md) before using Bob on any target.
  271. </details>
  272. ## 06: Reference
  273. Dense operational details stay here: complete, searchable, and out of the quick path.
  274. <details>
  275. <summary><strong>Installation, adapters, migrations, and installed files</strong></summary>
  276. ### Installation
  277. `hacker-bob` is the canonical npm package:
  278. ```bash
  279. npm install --global hacker-bob@latest
  280. hacker-bob install /path/to/your/project
  281. ```
  282. Adapter-specific installs are available when you want to choose the host explicitly:
  283. ```bash
  284. hacker-bob install /path/to/your/project --adapter claude
  285. hacker-bob install /path/to/your/project --adapter codex
  286. hacker-bob install /path/to/your/project --adapter generic-mcp
  287. hacker-bob install /path/to/your/project --adapter kimi
  288. hacker-bob install /path/to/your/project --adapter all
  289. ```
  290. 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.
  291. 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.
  292. ### OSS Project Review Mode
  293. | Adapter | Installed files |
  294. |---|---|
  295. | `claude` | `.claude/` commands, skills, agents, hooks, statusline setup, and MCP settings. |
  296. | `codex` | `$bob-*` skills in `~/.codex/skills`, a local `.codex/plugins/hacker-bob` plugin, `.agents/plugins/marketplace.json`, and Codex MCP activation metadata. |
  297. | `kimi` | `.kimi/skills`, `.kimi/mcp.json`, and `.kimi/bob` compatibility metadata. Installs PreToolUse session-guard hooks registered in `~/.kimi/config.toml`. |
  298. | `generic-mcp` | A root `.mcp.json` entry plus prompt guide files under `.hacker-bob/generic-mcp/`. |
  299. 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.
  300. 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.
  301. Source installs are for contributors and local development:
  302. ```bash
  303. git clone https://github.com/vmihalis/hacker-bob.git
  304. cd hacker-bob
  305. npm ci
  306. ./install.sh /path/to/your/project
  307. ```
  308. </details>
  309. <details>
  310. <summary><strong>Complete host command reference</strong></summary>
  311. ### Commands
  312. Claude Code commands:
  313. ```text
  314. /bob-evaluate <authorized-target> # start a normal evaluation
  315. /bob-evaluate <authorized-target> --deep # broaden discovery and follow-up
  316. /bob-evaluate resume <authorized-target> # resume an existing session
  317. /bob-status # show latest session status
  318. /bob-debug # inspect the latest local run
  319. /bob-update # preview and install the latest release
  320. /bob-export # create a release-scoped improvement bundle
  321. /bob-egress # manage operator-controlled egress profiles
  322. ```
  323. Codex uses the same command names with a `$` prefix:
  324. ```text
  325. $bob-evaluate <authorized-target>
  326. $bob-status
  327. $bob-debug
  328. $bob-update
  329. $bob-export
  330. $bob-egress
  331. ```
  332. Kimi CLI uses a `/skill:` prefix:
  333. ```text
  334. /skill:bob-evaluate <authorized-target>
  335. /skill:bob-status
  336. /skill:bob-debug
  337. /skill:bob-update
  338. /skill:bob-export
  339. /skill:bob-egress
  340. ```
  341. For install diagnostics:
  342. ```bash
  343. hacker-bob doctor /path/to/your/project
  344. hacker-bob doctor /path/to/your/project --adapter codex
  345. hacker-bob doctor /path/to/your/project --adapter kimi
  346. ```
  347. </details>
  348. <details>
  349. <summary><strong>Requirements and optional surface-discovery tools</strong></summary>
  350. ### Requirements
  351. - Node.js 20 or newer
  352. - One supported host: Claude Code, Codex, Kimi CLI, or another MCP-capable host
  353. - `curl` and `python3`
  354. - A dedicated project directory for the installed runtime
  355. Optional surface-discovery tools improve coverage when they are installed:
  356. ```bash
  357. go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
  358. go install github.com/projectdiscovery/httpx/cmd/httpx@latest
  359. go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
  360. go install github.com/owasp-amass/amass/v4/...@latest
  361. go install github.com/tomnomnom/assetfinder@latest
  362. go install github.com/projectdiscovery/chaos-client/cmd/chaos@latest
  363. go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
  364. go install github.com/projectdiscovery/tlsx/cmd/tlsx@latest
  365. go install github.com/projectdiscovery/katana/cmd/katana@latest
  366. go install -v github.com/PentestPad/subzy@latest
  367. git clone https://github.com/ticarpi/jwt_tool ~/jwt_tool
  368. python3 -m pip install -r ~/jwt_tool/requirements.txt
  369. ```
  370. Bob still runs without the optional tools; the installed toolset determines which surface-discovery paths are available.
  371. </details>
  372. <details>
  373. <summary><strong>Updating Hacker Bob</strong></summary>
  374. ### Updates
  375. From Claude Code:
  376. ```text
  377. /bob-update
  378. ```
  379. From Codex:
  380. ```text
  381. $bob-update
  382. ```
  383. From Kimi:
  384. ```text
  385. /skill:bob-update
  386. ```
  387. From a shell:
  388. ```bash
  389. hacker-bob update /path/to/your/project --adapter claude
  390. ```
  391. After an update, fully restart your host CLI in the project directory so it reloads commands, MCP config, hooks, and skills.
  392. 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.
  393. </details>
  394. <details>
  395. <summary><strong>Exporting run data</strong></summary>
  396. ### Exporting run data
  397. 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:
  398. ```text
  399. ~/bounty-agent-telemetry/release-bundles/v<version>/
  400. ```
  401. 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.
  402. </details>
  403. <details>
  404. <summary><strong>Troubleshooting and detailed guides</strong></summary>
  405. ### Troubleshooting
  406. Use the doctor command first:
  407. ```bash
  408. hacker-bob doctor /path/to/your/project --adapter all
  409. ```
  410. Common checks:
  411. - `node -e "require('./mcp/server.js'); console.log('MCP ok')"` should pass from the installed project.
  412. - Claude Code must be restarted after install or update before `/bob-*` commands and MCP settings load.
  413. - Codex must be restarted after install or update before `$bob-*` skills and local plugin wiring load.
  414. - Kimi CLI must be restarted after install or update before `/skill:bob-*` skills and MCP config load.
  415. - `.mcp.json` should contain an `mcpServers["hacker-bob"]` entry pointing at the installed project's `mcp/server.js`. v1.x installs are auto-migrated to this canonical key on next install or update.
  416. - If an upgrade leaves `mcp/tools/` missing, rerun the installer with `hacker-bob@latest`.
  417. Detailed guides:
  418. - [First Run](docs/FIRST_RUN.md)
  419. - [Troubleshooting](docs/TROUBLESHOOTING.md)
  420. - [Adapters](docs/ADAPTERS.md)
  421. - [Package surfaces](docs/PACKAGE_SURFACES.md)
  422. - [Roadmap](docs/ROADMAP.md)
  423. </details>
  424. <details>
  425. <summary><strong>Developing Hacker Bob locally</strong></summary>
  426. ### Development
  427. For local development on Bob itself:
  428. ```bash
  429. npm test
  430. npm run test:native-darwin # Darwin arm64 + Node.js 20 qualification
  431. npm run release:check
  432. npm run release:check:dependencies
  433. ```
  434. To push the current checkout into a separate test workspace:
  435. ```bash
  436. ./dev-sync.sh /absolute/path/to/test-workspace
  437. ./dev-sync.sh /absolute/path/to/test-workspace --adapter codex
  438. ./dev-sync.sh /absolute/path/to/test-workspace --adapter kimi
  439. ```
  440. The maintainer workflow is documented in [CLAUDE.md](CLAUDE.md).
  441. </details>
  442. ## 07: Contributing
  443. <p align="center">
  444. <img src="docs/media/readme-footer.svg" alt="Contribute, report securely, and reuse under Apache 2.0" width="100%" />
  445. </p>
  446. | Contribute | Report securely | Reuse |
  447. |---|---|---|
  448. | Pull requests are welcome. Read **[CONTRIBUTING.md](CONTRIBUTING.md)** before opening an issue or PR. | Report vulnerabilities in Hacker Bob itself through the private flow in **[SECURITY.md](SECURITY.md)**. Do not open a public issue or discussion. | Hacker Bob is licensed under the **[Apache License 2.0](LICENSE)**. See [NOTICE](NOTICE). |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.