bug-bounty-intelligence-mcp 1.0.2 → 1.0.5

package/BENCHMARK.md

@@ -1,160 +1,174 @@
-# Benchmark: Bug Bounty Intelligence vs Slither
-
-**Target protocol:** 3FLabs/grunt — leveraged strategies for on-chain funds  
-**Protocol type:** ERC-4626/ERC-7540 vaults + Morpho lending + flash loan requests  
-**Scope:** `src/` (218 Solidity files)  
-**Slither version:** 0.10.x  
-**Date:** 2026-07-20
-
----
-
-## TL;DR
-
-| Metric | Slither | Bug Bounty Intelligence |
-|--------|---------|------------------------|
-| "High" findings reported | 27 | 0 |
-| True positives (real bugs) | 0 | 0 |
-| False positives | 27 (100%) | 0 |
-| Out-of-scope library noise | 24 (89%) | 0 |
-| Signals requiring human review | n/a | 17 |
-| Reading time to triage all "Highs" | ~4 hours | ~15 min |
-
-**Slither false positive rate on this codebase: 100%.**
-
----
-
-## Test setup
-
-We ran Slither on the full repo (including `lib/`), and Bug Bounty Intelligence on `src/` only. The scope for any real audit is `src/` — dependencies in `lib/` are battle-tested third-party code that has its own audit history.
-
----
-
-## Slither's 27 "High" findings — breakdown
-
-### Group A: 24 findings in `lib/solady/` (out of scope)
-
-Slither flagged 24 High-severity issues, all in the `lib/solady/` dependency:
-
-- 5x `incorrect-exp` — Solady uses XOR (`^`) for bitwise operations, not exponentiation. Slither confuses the two.
-- 19x `incorrect-shift` — Solady uses `<<` / `>>` inside assembly blocks. Slither's detector fires on these but they are intentional and correct.
-
-**Why these are not bugs:**
-
-Solady is one of the most audited Solidity libraries in existence, used by hundreds of protocols. Its math implementations deliberately use low-level bit operations for gas efficiency. Slither's `incorrect-exp` and `incorrect-shift` detectors are known to produce false positives on Solady. Every human auditor knows to ignore these. Slither does not.
-
-**Example:**
-
-```
-incorrect-shift | FixedPointMathLib.lnWad(int256) (lib/solady/src/utils/FixedPointMathLib.sol#269-341)
-contains an incorrect shift operation: ...
-```
-
-This is in `lib/solady/`, a third-party library. It is out of scope for any 3FLabs audit.
-
-### Group B: 3 findings in `src/` — all false positives
-
-Slither flagged 3 uses of `safeTransferFrom(offer.maker, ...)` as "arbitrary from in transferFrom":
-
-```
-arbitrary-send-erc20 | Request.consume() uses arbitrary from in transferFrom:
-  _asset().safeTransferFrom(offer.maker, address(this), ptAmount)
-```
-
-**Why this is not a bug:**
-
-`offer.maker` is not arbitrary. The offer is validated via EIP-712 signature before the transfer (`_validateOffer(offer, signature)` is called on line 421). The maker explicitly signed the offer, authorizing exactly this transfer of exactly this amount. Additionally, `consume()` is gated by `onlyOwnerOrRoles(_ROLE_CONSUMER)` — only trusted consumers can call it.
-
-This is a correct and standard EIP-712 off-chain order pattern. Slither has no understanding of EIP-712 and cannot reason about signature-based authorization.
-
----
-
-## What Bug Bounty Intelligence flags instead
-
-After filtering to `src/` and applying Al-Mizaan validation gates, we identified **17 signals requiring human review** — none rising to a confirmed finding:
-
-| Category | Count | Description |
-|----------|-------|-------------|
-| `unsafe_keyword` | 15 | Explicit `forge-lint: disable-next-line(unsafe-typecast)` annotations — developer acknowledged unsafe casts. Require review for truncation risk. |
-| `delegatecall` | 2 | `MorphoFlashLoanRequest.execute()` delegatecalls to whitelisted scripts. By design — whitelist check present. |
-
-**What we do not flag:**
-- Library code in `lib/` (out of scope)
-- EIP-712 signed transfers (intentional pattern, not a vulnerability)
-- Standard Solady bit operations (well-audited library behavior)
-
----
-
-## Al-Mizaan filtering — why the 17 signals do not become findings
-
-The 15 `unsafe_keyword` signals (explicit forge-lint disables) were put through Al-Mizaan's reachability chain:
-
-1. **Code** — read the actual casts in `LibTokenController.sol`, `TokenController.sol`, and `PositionManagerLP.sol`
-2. **Reachability** — are the truncated values reachable by an untrusted caller?
-3. **Threat model** — who triggers these paths? In all cases, the entry points are role-gated (owner, ROLE_CONSUMER, ROLE_MANAGER)
-4. **Invariant** — does the truncation break any accounting invariant?
-
-Verdict: The typecasts are `uint256 → uint128` in share accounting. The values come from internal calculations that are capped by deposit limits. Overflow requires either extremely large TVL or a role-gated actor. **Trusted actor as sole trigger → ELIMINATE.**
-
-The 2 `delegatecall` signals: `MorphoFlashLoanRequest` maintains an explicit `isScriptWhitelisted` mapping. Only the owner can whitelist. **Trusted actor (owner) as sole attacker → ELIMINATE.**
-
-**Result: 0 confirmed findings.** This matches the expected difficulty level of a mature protocol with prior audits.
-
----
-
-## Why Slither's false positive rate matters
-
-A 100% false positive rate on High findings is not an edge case. It happens because:
-
-1. **No scope awareness** — Slither scans everything, including dependencies. A real audit scopes to `src/` only.
-2. **No protocol context** — Slither cannot distinguish between an arbitrary `transferFrom` and an EIP-712-authorized one.
-3. **No library knowledge** — Solady's assembly patterns trigger false positives on multiple detectors.
-
-For a developer running Slither for the first time, triaging 27 "High" findings (all false positives) takes hours. For a developer using Bug Bounty Intelligence, the 17 signals that remain after scope filtering take 15 minutes to review.
-
----
-
-## When Slither IS useful
-
-Slither is best used as a first-pass tool before human review, with explicit exclusions:
-
-```bash
-slither src/ --exclude incorrect-exp,incorrect-shift --filter-paths "lib/"
-```
-
-After filtering, Slither's Medium and Low findings become more useful starting points.
-
-Bug Bounty Intelligence is designed to do this filtering for you, and adds protocol-context reasoning that static analysis cannot.
-
----
-
-## Reproduce this benchmark
-
-The 3FLabs/grunt codebase is public at [github.com/3FLabs/grunt](https://github.com/3FLabs/grunt).
-
-To reproduce Slither's output:
-```bash
-git clone https://github.com/3FLabs/grunt
-cd grunt
-pip install slither-analyzer
-slither . --json slither-output.json
-```
-
-To use Bug Bounty Intelligence:
-```bash
-npx -y bug-bounty-intelligence-mcp@latest
-```
-
-Then in your MCP client:
-```
-scan_contract({ repo_url: "https://github.com/3FLabs/grunt", protocol_type: "LENDING" })
-```
-
----
-
-## About Bug Bounty Intelligence
-
-Trained on 27,681 real accepted audit findings from Sherlock and Code4rena. Uses the Al-Mizaan v3 framework — a 7-gate validation chain (Code, Reachability, Threat-Model, Invariant, Protocol-Intent, Impact, Proof) — to filter signals into confirmed findings.
-
-**Cost:** $5 USDC on Base (eip155:8453) via x402.  
-**Install:** `npx -y bug-bounty-intelligence-mcp@latest`  
-**npm:** [npmjs.com/package/bug-bounty-intelligence-mcp](https://www.npmjs.com/package/bug-bounty-intelligence-mcp)
+# Benchmark: Bug Bounty Intelligence vs Slither
+
+**Target protocol:** 3FLabs/grunt — leveraged strategies for on-chain funds  
+**Protocol type:** ERC-4626/ERC-7540 vaults + Morpho lending + flash loan requests  
+**Scope:** `src/` (218 Solidity files)  
+**Slither version:** 0.10.x  
+**Date:** 2026-07-20
+
+---
+
+## TL;DR
+
+| Metric | Slither | Bug Bounty Intelligence |
+|--------|---------|------------------------|
+| "High" findings reported | 27 | 0 |
+| True positives (real bugs) | 0 | 0 |
+| False positives | 27 (100%) | 0 |
+| Out-of-scope library noise | 24 (89%) | 0 |
+| Signals requiring human review | n/a | 17 |
+| Reading time to triage all "Highs" | ~4 hours | ~15 min |
+
+**Slither false positive rate on this codebase: 100%.**
+
+---
+
+## Test setup
+
+We ran Slither on the full repo (including `lib/`), and Bug Bounty Intelligence on `src/` only. The scope for any real audit is `src/` — dependencies in `lib/` are battle-tested third-party code that has its own audit history.
+
+---
+
+## Slither's 27 "High" findings — breakdown
+
+### Group A: 24 findings in `lib/solady/` (out of scope)
+
+Slither flagged 24 High-severity issues, all in the `lib/solady/` dependency:
+
+- 5x `incorrect-exp` — Solady uses XOR (`^`) for bitwise operations, not exponentiation. Slither confuses the two.
+- 19x `incorrect-shift` — Solady uses `<<` / `>>` inside assembly blocks. Slither's detector fires on these but they are intentional and correct.
+
+**Why these are not bugs:**
+
+Solady is one of the most audited Solidity libraries in existence, used by hundreds of protocols. Its math implementations deliberately use low-level bit operations for gas efficiency. Slither's `incorrect-exp` and `incorrect-shift` detectors are known to produce false positives on Solady. Every human auditor knows to ignore these. Slither does not.
+
+**Example:**
+
+```
+incorrect-shift | FixedPointMathLib.lnWad(int256) (lib/solady/src/utils/FixedPointMathLib.sol#269-341)
+contains an incorrect shift operation: ...
+```
+
+This is in `lib/solady/`, a third-party library. It is out of scope for any 3FLabs audit.
+
+**Update:** while triaging these, we noticed a related pattern on the same `lib/solady` code:
+`divide-before-multiply` fired 38 times on `FixedPointMathLib`'s `fullMulDivUnchecked`, `cbrt`,
+`invMod`, `rpow`, and `cbrtWad`. We initially described all 38 as the same false-positive class
+(divided variable fully reassigned before the multiply) and reported it upstream —
+[crytic/slither#3039](https://github.com/crytic/slither/issues/3039). That was an overclaim on our
+part. A maintainer merged a fix for the specific reassignment pattern we described
+([crytic/slither#3040](https://github.com/crytic/slither/pull/3040), not yet in a PyPI release as
+of 2026-08-01), and re-testing against the merged code ourselves shows it correctly resolves 11 of
+the 38 (down to 27 remaining on this file). The other 27 keep the divided variable in the same
+expression rather than through a clean reassignment, which is a different pattern this fix
+correctly leaves untouched — we haven't yet re-analyzed whether those are genuine false positives
+too or something else. Filed as a lesson: verify a fix against the actual code before describing
+it as resolving the full scope of what you reported.
+
+### Group B: 3 findings in `src/` — all false positives
+
+Slither flagged 3 uses of `safeTransferFrom(offer.maker, ...)` as "arbitrary from in transferFrom":
+
+```
+arbitrary-send-erc20 | Request.consume() uses arbitrary from in transferFrom:
+  _asset().safeTransferFrom(offer.maker, address(this), ptAmount)
+```
+
+**Why this is not a bug:**
+
+`offer.maker` is not arbitrary. The offer is validated via EIP-712 signature before the transfer (`_validateOffer(offer, signature)` is called on line 421). The maker explicitly signed the offer, authorizing exactly this transfer of exactly this amount. Additionally, `consume()` is gated by `onlyOwnerOrRoles(_ROLE_CONSUMER)` — only trusted consumers can call it.
+
+This is a correct and standard EIP-712 off-chain order pattern. Slither has no understanding of EIP-712 and cannot reason about signature-based authorization.
+
+---
+
+## What Bug Bounty Intelligence flags instead
+
+After filtering to `src/` and applying Al-Mizaan validation gates, we identified **17 signals requiring human review** — none rising to a confirmed finding:
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| `unsafe_keyword` | 15 | Explicit `forge-lint: disable-next-line(unsafe-typecast)` annotations — developer acknowledged unsafe casts. Require review for truncation risk. |
+| `delegatecall` | 2 | `MorphoFlashLoanRequest.execute()` delegatecalls to whitelisted scripts. By design — whitelist check present. |
+
+**What we do not flag:**
+- Library code in `lib/` (out of scope)
+- EIP-712 signed transfers (intentional pattern, not a vulnerability)
+- Standard Solady bit operations (well-audited library behavior)
+
+---
+
+## Al-Mizaan filtering — why the 17 signals do not become findings
+
+The 15 `unsafe_keyword` signals (explicit forge-lint disables) were put through Al-Mizaan's reachability chain:
+
+1. **Code** — read the actual casts in `LibTokenController.sol`, `TokenController.sol`, and `PositionManagerLP.sol`
+2. **Reachability** — are the truncated values reachable by an untrusted caller?
+3. **Threat model** — who triggers these paths? In all cases, the entry points are role-gated (owner, ROLE_CONSUMER, ROLE_MANAGER)
+4. **Invariant** — does the truncation break any accounting invariant?
+
+Verdict: The typecasts are `uint256 → uint128` in share accounting. The values come from internal calculations that are capped by deposit limits. Overflow requires either extremely large TVL or a role-gated actor. **Trusted actor as sole trigger → ELIMINATE.**
+
+The 2 `delegatecall` signals: `MorphoFlashLoanRequest` maintains an explicit `isScriptWhitelisted` mapping. Only the owner can whitelist. **Trusted actor (owner) as sole attacker → ELIMINATE.**
+
+**Result: 0 confirmed findings.** This matches the expected difficulty level of a mature protocol with prior audits.
+
+---
+
+## Why Slither's false positive rate matters
+
+A 100% false positive rate on High findings is not an edge case. It happens because:
+
+1. **No scope awareness** — Slither scans everything, including dependencies. A real audit scopes to `src/` only.
+2. **No protocol context** — Slither cannot distinguish between an arbitrary `transferFrom` and an EIP-712-authorized one.
+3. **No library knowledge** — Solady's assembly patterns trigger false positives on multiple detectors.
+
+For a developer running Slither for the first time, triaging 27 "High" findings (all false positives) takes hours. For a developer using Bug Bounty Intelligence, the 17 signals that remain after scope filtering take 15 minutes to review.
+
+---
+
+## When Slither IS useful
+
+Slither is best used as a first-pass tool before human review, with explicit exclusions:
+
+```bash
+slither src/ --exclude incorrect-exp,incorrect-shift --filter-paths "lib/"
+```
+
+After filtering, Slither's Medium and Low findings become more useful starting points.
+
+Bug Bounty Intelligence is designed to do this filtering for you, and adds protocol-context reasoning that static analysis cannot.
+
+---
+
+## Reproduce this benchmark
+
+The 3FLabs/grunt codebase is public at [github.com/3FLabs/grunt](https://github.com/3FLabs/grunt).
+
+To reproduce Slither's output:
+```bash
+git clone https://github.com/3FLabs/grunt
+cd grunt
+pip install slither-analyzer
+slither . --json slither-output.json
+```
+
+To use Bug Bounty Intelligence:
+```bash
+npx -y bug-bounty-intelligence-mcp@latest
+```
+
+Then in your MCP client:
+```
+scan_contract({ repo_url: "https://github.com/3FLabs/grunt", protocol_type: "LENDING" })
+```
+
+---
+
+## About Bug Bounty Intelligence
+
+Pattern-aware from a corpus of 27,681 submitted Sherlock/Code4rena findings across 105 contests; acceptance-rate numbers (used by `list_vulnerability_patterns`) are limited to the 1,032 findings across 10 contests that could be exact-reconciled against contest outcomes (461 accepted) — see METHODOLOGY.md. Uses the Al-Mizaan v3 framework — a 7-gate validation chain (Code, Reachability, Threat-Model, Invariant, Protocol-Intent, Impact, Proof) — to filter signals into confirmed findings.
+
+**Cost:** $5 USDC on Base (eip155:8453) via x402.  
+**Install:** `npx -y bug-bounty-intelligence-mcp@latest`  
+**npm:** [npmjs.com/package/bug-bounty-intelligence-mcp](https://www.npmjs.com/package/bug-bounty-intelligence-mcp)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdellah Ouadoudi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/METHODOLOGY.md

@@ -1,94 +1,94 @@
-# Methodology: acceptance-rate data behind `list_vulnerability_patterns`
-
-**Last updated: 2026-07-21.**
-
-## What this covers
-
-`list_vulnerability_patterns` returns, per vulnerability class, what fraction of *submitted*
-audit-competition findings were judged valid. This document explains exactly how those numbers
-are computed, what they don't claim, and how to reproduce them from public data.
-
-## Data source
-
-Sherlock runs public GitHub repos for judging each audit contest
-(`sherlock-audit/<contest>-judging`), where security researchers ("Watsons") open one GitHub
-issue per submitted finding. 105 of these judging repos were crawled (27,681 raw submitted
-findings total, 2024-02 through 2025-07).
-
-## The problem: "was this accepted?" is not reliably answerable from GitHub alone
-
-An early version of this pipeline inferred acceptance from GitHub issue state
-(`OPEN` = accepted, `CLOSED` = rejected). That heuristic turned out to be wrong, in both
-directions, depending on the contest — sometimes undercounting acceptance by an order of
-magnitude, sometimes overcounting it. GitHub issue labels (`Reward`, `Non-Reward`, `Invalid`,
-etc.) turned out to be applied inconsistently across contests too — some contests label every
-issue, some label almost none.
-
-## The fix: use Sherlock's own result structure, and only trust it when it reconciles
-
-Sherlock's judging repos also contain, at the repo root, a folder per accepted finding
-(`001-M/`, `002-H/`, etc. — number + severity), each containing one file per GitHub issue number
-that was judged to be that finding (the primary write-up plus any duplicates), and a separate
-`invalid/` folder for rejected issue numbers. This is Sherlock's own authoritative accounting,
-not an inference.
-
-We only trust this for a given contest if it **reconciles exactly**:
-`accepted_issue_numbers + invalid_issue_numbers === total_submitted_issues`.
-
-If a contest's folder structure doesn't exist, or doesn't reconcile exactly, that contest is
-**excluded entirely** — not estimated, not approximated. Of 105 crawled contests:
-
-- **10 reconcile exactly** and are used for `list_vulnerability_patterns`: 1,032 findings, 461
-  accepted.
-- **95 do not** — either no accepted/invalid folder structure exists in that judging repo (a
-  likely explanation: some contests use a different Sherlock judging workflow that doesn't
-  generate this structure), or the counts don't sum to the known total (a likely explanation for
-  many of these: the original crawl capped issue retrieval at 500 per contest, so large contests'
-  true totals exceed what was captured — a fixable crawler limitation, not a Sherlock data
-  problem, but not yet re-verified).
-
-## What the resulting numbers mean
-
-For each pattern (keyword-matched against finding titles/bodies — e.g. "reentrancy",
-"oracle manipulation"), the acceptance rate is: of all submissions whose issue number appears in
-*any* accepted-finding folder (including duplicates of the same underlying bug), what fraction
-of total tagged submissions that is. This measures **submission-level reliability** — "if
-someone writes up and submits a claim of this bug class, how often does it hold up" — not the
-number of distinct vulnerabilities found.
-
-## What this does not claim
-
-- Not a claim about real-world exploit frequency — this is pre-deployment audit-competition
-  data, not realized incidents.
-- Not a claim about detection coverage — it describes submitted reports, not silent misses.
-- The keyword-based pattern tagging is a simple substring matcher (see `detectPatterns()` in the
-  crawler scripts), not a semantic classifier — a manual audit found roughly 65% tagging
-  precision on a sample. Pattern labels are directional, not exact classifications.
-- The 10-contest sample is small. Some pattern rows have thin n (e.g. `liquidation`, n=14) —
-  treat low-n rows as lower-confidence than high-n rows (e.g. `trusted-actor`, n=311).
-
-## Reproducing this
-
-Everything below uses only public data — no private API, no authentication required beyond
-default `gh` CLI rate limits.
-
-```bash
-# 1. List Sherlock judging repos
-gh repo list sherlock-audit --limit 1000 --json name | jq -r '.[] | select(.name | endswith("-judging")) | .name'
-
-# 2. For a given contest, pull its full file tree and look for the NNN-severity / invalid folders
-gh api repos/sherlock-audit/<contest>-judging/git/trees/main?recursive=1 \
-  | jq '[.tree[].path | select(test("^[0-9]{3}-[HM]/|^invalid/"))]'
-
-# 3. Cross-check reconciliation against the contest's total issue count
-gh api "repos/sherlock-audit/<contest>-judging/issues?state=all&per_page=100" | jq 'length'
-```
-
-A finding's issue number appearing under any `NNN-[HM]/` path = accepted. Under `invalid/` =
-rejected. If `accepted + invalid !== total`, do not use that contest's data.
-
-## Why we publish this instead of just the bigger, older number
-
-An earlier draft of this tool advertised acceptance percentages computed from the full,
-unverified 27,681-finding corpus. Independent review caught that those specific percentages
-were unreliable. We would rather ship a smaller number we can prove than a bigger one we can't.
+# Methodology: acceptance-rate data behind `list_vulnerability_patterns`
+
+**Last updated: 2026-07-21.**
+
+## What this covers
+
+`list_vulnerability_patterns` returns, per vulnerability class, what fraction of *submitted*
+audit-competition findings were judged valid. This document explains exactly how those numbers
+are computed, what they don't claim, and how to reproduce them from public data.
+
+## Data source
+
+Sherlock runs public GitHub repos for judging each audit contest
+(`sherlock-audit/<contest>-judging`), where security researchers ("Watsons") open one GitHub
+issue per submitted finding. 105 of these judging repos were crawled (27,681 raw submitted
+findings total, 2024-02 through 2025-07).
+
+## The problem: "was this accepted?" is not reliably answerable from GitHub alone
+
+An early version of this pipeline inferred acceptance from GitHub issue state
+(`OPEN` = accepted, `CLOSED` = rejected). That heuristic turned out to be wrong, in both
+directions, depending on the contest — sometimes undercounting acceptance by an order of
+magnitude, sometimes overcounting it. GitHub issue labels (`Reward`, `Non-Reward`, `Invalid`,
+etc.) turned out to be applied inconsistently across contests too — some contests label every
+issue, some label almost none.
+
+## The fix: use Sherlock's own result structure, and only trust it when it reconciles
+
+Sherlock's judging repos also contain, at the repo root, a folder per accepted finding
+(`001-M/`, `002-H/`, etc. — number + severity), each containing one file per GitHub issue number
+that was judged to be that finding (the primary write-up plus any duplicates), and a separate
+`invalid/` folder for rejected issue numbers. This is Sherlock's own authoritative accounting,
+not an inference.
+
+We only trust this for a given contest if it **reconciles exactly**:
+`accepted_issue_numbers + invalid_issue_numbers === total_submitted_issues`.
+
+If a contest's folder structure doesn't exist, or doesn't reconcile exactly, that contest is
+**excluded entirely** — not estimated, not approximated. Of 105 crawled contests:
+
+- **10 reconcile exactly** and are used for `list_vulnerability_patterns`: 1,032 findings, 461
+  accepted.
+- **95 do not** — either no accepted/invalid folder structure exists in that judging repo (a
+  likely explanation: some contests use a different Sherlock judging workflow that doesn't
+  generate this structure), or the counts don't sum to the known total (a likely explanation for
+  many of these: the original crawl capped issue retrieval at 500 per contest, so large contests'
+  true totals exceed what was captured — a fixable crawler limitation, not a Sherlock data
+  problem, but not yet re-verified).
+
+## What the resulting numbers mean
+
+For each pattern (keyword-matched against finding titles/bodies — e.g. "reentrancy",
+"oracle manipulation"), the acceptance rate is: of all submissions whose issue number appears in
+*any* accepted-finding folder (including duplicates of the same underlying bug), what fraction
+of total tagged submissions that is. This measures **submission-level reliability** — "if
+someone writes up and submits a claim of this bug class, how often does it hold up" — not the
+number of distinct vulnerabilities found.
+
+## What this does not claim
+
+- Not a claim about real-world exploit frequency — this is pre-deployment audit-competition
+  data, not realized incidents.
+- Not a claim about detection coverage — it describes submitted reports, not silent misses.
+- The keyword-based pattern tagging is a simple substring matcher (see `detectPatterns()` in the
+  crawler scripts), not a semantic classifier — a manual audit found roughly 65% tagging
+  precision on a sample. Pattern labels are directional, not exact classifications.
+- The 10-contest sample is small. Some pattern rows have thin n (e.g. `liquidation`, n=14) —
+  treat low-n rows as lower-confidence than high-n rows (e.g. `trusted-actor`, n=311).
+
+## Reproducing this
+
+Everything below uses only public data — no private API, no authentication required beyond
+default `gh` CLI rate limits.
+
+```bash
+# 1. List Sherlock judging repos
+gh repo list sherlock-audit --limit 1000 --json name | jq -r '.[] | select(.name | endswith("-judging")) | .name'
+
+# 2. For a given contest, pull its full file tree and look for the NNN-severity / invalid folders
+gh api repos/sherlock-audit/<contest>-judging/git/trees/main?recursive=1 \
+  | jq '[.tree[].path | select(test("^[0-9]{3}-[HM]/|^invalid/"))]'
+
+# 3. Cross-check reconciliation against the contest's total issue count
+gh api "repos/sherlock-audit/<contest>-judging/issues?state=all&per_page=100" | jq 'length'
+```
+
+A finding's issue number appearing under any `NNN-[HM]/` path = accepted. Under `invalid/` =
+rejected. If `accepted + invalid !== total`, do not use that contest's data.
+
+## Why we publish this instead of just the bigger, older number
+
+An earlier draft of this tool advertised acceptance percentages computed from the full,
+unverified 27,681-finding corpus. Independent review caught that those specific percentages
+were unreliable. We would rather ship a smaller number we can prove than a bigger one we can't.

package/README.md

@@ -1,27 +1,72 @@
-# Bug Bounty Intelligence — MCP Server
+# Bug Bounty Intelligence: MCP Server
 
 AI-powered smart contract security analysis for AI agents and developers.
 
+## Update, 24 October 2026, later the same day: version 2 of the scan
+
+The defects described below were fixed and the new version is live. What changed: git submodules are fetched when they point to github.com, tests, mocks, scripts, interfaces and vendored libraries are left out, files are ranked by how likely they move funds and sent in at most six parts, every report states how much of the in-scope code was read, a scan without hypotheses is delivered as such and not as a normal report, hypotheses that name files or functions that are not in the code are dropped, and file links inside a repository are never followed. A free precheck at https://x402.tokenizen.nl/api/bug-intel/precheck?repo=owner/name says before you pay whether the scan counts any Solidity in your repository and roughly how much of it will be read.
+
+The measurement of this version was pre-registered before it ran: [PREREGISTRATION-v2-2026-10-24.md](PREREGISTRATION-v2-2026-10-24.md). The frozen files are in [pipeline/v2](pipeline/v2).
+
+Result, in [RESULTS-v2-2026-10-24.md](RESULTS-v2-2026-10-24.md): none of the 40 known High and Medium findings was found, 0 of 31 on the four contests of the first run and 0 of 9 on three new contests, while 29 percent of the in-scope code was read (8 to 100 percent per contest). 15 of the 40 known findings sit in a file that was read, and none of those was found. The scan produces hypotheses to review by hand. It has not been shown to find the issues that audit contests reward.
+
+## Correction and limits (24 October 2026, before version 2)
+
+Reading the production scan code on 24 October 2026 showed that earlier text on this page overstated what the paid scan does. What it does today:
+
+- It sends the model at most about 22,000 characters of Solidity source per job, taken from up to 60 files in directory order, and it does not skip test or mock folders. On three recent audit-contest repositories (code-423n4/2025-11-merkl, 2025-11-sukukfi and 2026-04-monetrix) that is 3 to 7 percent of the Solidity source.
+- The 7-gate filter is not part of the paid scan. It was taken out because the small model also eliminated real bugs. The report lists raw hypotheses with a self-reported confidence of 0.4 or higher, at most eight, and its disclaimer says so.
+- The sample below ran on a repository that belongs to the corpus the framework was built from. It does not show how the scan does on projects it has not seen, and its label "CONFIRMED by Al-Mizaan validation" does not apply to the scan as it runs today.
+- We have not measured how many real bugs the scan finds on contests it has not seen. A test on closed audit contests is pre-registered in [PREREGISTRATION-2026-10-24.md](PREREGISTRATION-2026-10-24.md). The baseline ran on 24 October 2026: 0 of 31 findings found, 2 hypotheses reported and neither matches, one job failed and two reports were empty. See [RESULTS-2026-10-24.md](RESULTS-2026-10-24.md). Until a changed version is pre-registered and measured, do not read this scan as something that finds bugs on projects it has not seen.
+
+Official source: this repository and the payment address in the payment section below are the only official ones for Bug Bounty Intelligence. If a listing, a reply or a website gives a different payment address, it is not ours. Check the address against the one below before you pay.
+
 **Drawn from a corpus of 27,681 submitted findings across 105 Sherlock and Code4rena contests.**
 **Cost: $5 USDC on Base (eip155:8453) via x402.**
-**Free tool: `list_vulnerability_patterns` — no payment needed.**
+**Free tool: `list_vulnerability_patterns`, no payment needed.**
 
 `list_vulnerability_patterns`' acceptance-rate numbers are computed only from the subset where
-results could be exactly reconciled against Sherlock's own published outcomes — 1,032 findings
+results could be exactly reconciled against Sherlock's own published outcomes: 1,032 findings
 across 10 contests. We'd rather show fewer, verified numbers than a bigger set we can't stand
 behind. See [METHODOLOGY.md](METHODOLOGY.md) for exactly why, and how to reproduce it.
 
+## Free dataset: no server, no MCP, no payment
+
+[`vulnerability-acceptance-rates.json`](vulnerability-acceptance-rates.json) is the same data
+`list_vulnerability_patterns` serves, as a static file. No API call, no account, no network
+dependency at all. Download it, or copy it into your own tool's rule set. CC0 licensed, use it
+however you want, credit optional.
+
+```bash
+curl -sO https://raw.githubusercontent.com/holistis/bug-bounty-intelligence-mcp/main/vulnerability-acceptance-rates.json
+```
+
+If you're building a local-first / offline security scanner and the paid `scan_contract` tool
+below isn't a fit for your project's architecture, this file might still be useful on its own.
+
+## Just want pattern search, nothing paid? Use 3ilm-mcp instead
+
+[3ilm-mcp](https://github.com/holistis/3ilm-mcp) is a smaller, free-only MCP server built from
+the same verified dataset. It has no paid tier at all, just pattern search
+(`search_vulnerabilities`, `get_pattern_details`, `list_patterns`). Use this repo
+(bug-bounty-intelligence-mcp) if you also want the paid `scan_contract` scan; use
+3ilm-mcp if you only ever wanted the free lookup tools and prefer the lighter package.
+
+Two more tools in the same Al-Mizaan toolkit, for the rest of the workflow: [al-mizaan-judge](https://github.com/holistis/al-mizaan-judge) is a local CLI that pressure-tests a candidate finding through the same 7-gate framework before you submit it, and [DeFi Signal API](https://github.com/holistis/defi-signal-api) exposes the same vuln-search/bug-intel routes as a pay-per-call HTTP API for anyone who wants this outside MCP.
+
 ## Benchmark: vs Slither
 
 **[See the full benchmark →](BENCHMARK.md)**
 
 On 3FLabs/grunt (ERC-4626 + Morpho vaults, 218 contracts): Slither reports 27 "High" findings. After analysis: 24 are in `lib/solady` (out-of-scope dependency with known Slither false positive patterns), and 3 are EIP-712 design patterns. False positive rate: **100%**.
 
-Bug Bounty Intelligence scopes to `src/` only and filters through the Al-Mizaan 7-gate framework before reporting anything.
+In that comparison Bug Bounty Intelligence was pointed at `src/` only. The paid scan now leaves out tests, mocks, scripts, interfaces and vendored libraries by rule. It does not run the 7-gate filter.
+
+We also reported a related `divide-before-multiply` pattern on the same `lib/solady` code directly to the Slither project: [crytic/slither#3039](https://github.com/crytic/slither/issues/3039). A maintainer merged a fix for part of it ([crytic/slither#3040](https://github.com/crytic/slither/pull/3040)); see [BENCHMARK.md](BENCHMARK.md) for the honest scope of what that fix does and doesn't cover, we overclaimed in the original report.
 
 ## What it does
 
-Submit a public GitHub repo containing Solidity smart contracts. Receive a full vulnerability report within 24 hours, powered by the Al-Mizaan v3 analysis framework.
+Submit a public GitHub repo containing Solidity smart contracts. Receive a report of AI-generated hypotheses, usually within the hour, that states how much of the code was read (see the update and the limits at the top of this page).
 
 ## Tools
 
@@ -33,6 +78,8 @@ Submit a public GitHub repo containing Solidity smart contracts. Receive a full
 
 ## Quick start (Claude Desktop / Claude Code)
 
+Also listed in [PuPu](https://github.com/haoxiang-xu/PuPu)'s MCP store as of release v0.1.11 ([registration issue](https://github.com/haoxiang-xu/PuPu/issues/186)).
+
 Add to your `claude_desktop_config.json`:
 
 ```json
@@ -54,13 +101,15 @@ npx -y bug-bounty-intelligence-mcp@latest
 
 ## Payment
 
-If `scan_contract` returns `PAYMENT REQUIRED`, send exactly $5 USDC on Base to the address shown, then retry. Payment = acceptance of [service terms](https://wazir-x402.duckdns.org/terms).
+If `scan_contract` returns `PAYMENT REQUIRED`, send exactly $5 USDC on Base to the address shown, then retry. Payment = acceptance of [service terms](https://x402.tokenizen.nl/terms).
 
 **x402 info:**
 - Network: Base mainnet (eip155:8453)
 - Amount: 5,000,000 (= 5 USDC, 6 decimals)
 - Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC)
-- Wallet: 0xdffcC75a674257be6FE1b5549FE52e8f8a6A3A5A
+- Wallet: 0x015Eb036560216B3051339061FF68A207E0fe88f
+
+The wallet address can change. Always pay the address `scan_contract` actually returns in its `PAYMENT REQUIRED` response, not a copy of this README. This document is updated when the address changes, but the live tool response is the source of truth.
 
 ## Example session
 
@@ -82,7 +131,7 @@ PAYMENT REQUIRED to start the scan.
 
 Amount:  5.00 USDC
 Network: Base mainnet (eip155:8453)
-Pay to:  0xdffcC75a674257be6FE1b5549FE52e8f8a6A3A5A
+Pay to:  0x015Eb036560216B3051339061FF68A207E0fe88f
 Asset:   USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
 
 After paying, retry scan_contract with the same repo_url.
@@ -124,7 +173,7 @@ Confidence: 0.90 (CONFIRMED by Al-Mizaan validation)
 
 ## About the analysis
 
-The Al-Mizaan v3 framework checks 7 gates:
+The Al-Mizaan v3 framework defines 7 gates:
 
 1. Code reading (literal, not docs)
 2. Reachability chain (entry to exploit)
@@ -134,11 +183,19 @@ The Al-Mizaan v3 framework checks 7 gates:
 6. Impact (real financial damage)
 7. Formal proof (reproducible PoC)
 
-Only findings that survive all 7 gates are reported.
+This is the framework used for manual review (the `al-mizaan-judge` CLI). The paid scan does not run it end to end, see the correction at the top of this page.
 
 ## Service info
 
-- **API endpoint**: https://wazir-x402.duckdns.org/api/bug-intel
-- **Terms**: https://wazir-x402.duckdns.org/terms
-- **Delivery**: within 24h
+- **API endpoint**: https://x402.tokenizen.nl/api/bug-intel
+- **Free precheck**: https://x402.tokenizen.nl/api/bug-intel/precheck?repo=owner/name
+- **Terms**: https://x402.tokenizen.nl/terms
+- **Delivery**: usually within the hour, at most 48 hours according to the terms
+- **If it fails or does not help**: write to info@holistischadviseur.nl with the job id for a new attempt or a refund, see the terms
 - **Source code**: deleted after analysis
+
+## Support this project
+
+This is a free, open-source MCP server maintained in my spare time. If it caught something useful before you shipped, tips are welcome and appreciated (never expected):
+
+`0xdffcC75a674257be6FE1b5549FE52e8f8a6A3A5A` (USDC, Base)

package/index.mjs

@@ -10,7 +10,7 @@
  * Payment: $5 USDC on Base (eip155:8453) via x402.
  * If you receive a payment_required response, pay to the address shown and retry.
  *
- * Run: node scripts/bug-intel-mcp.mjs
+ * Run: node index.mjs  (or: npx -y bug-bounty-intelligence-mcp@latest)
  */
 
 import { Server }        from '@modelcontextprotocol/sdk/server/index.js'
@@ -19,7 +19,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
-const API_URL = 'https://wazir-x402.duckdns.org'
+const API_URL = 'https://x402.tokenizen.nl'
 
 // Embedded pattern library — Sherlock audit-competition findings, updated 2026-07-21.
 // Methodology: only contests where Sherlock's own judging-repo result structure could be
@@ -93,11 +93,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: 'scan_contract',
       description: [
-        'Submit a public GitHub repository for an automated smart contract security analysis.',
-        'Trained on 27,681 real findings from Sherlock and Code4rena audits.',
-        'Cost: $5 USDC on Base (eip155:8453) via x402.',
-        'Returns a job_id. Use get_scan_report to poll for results (ready within 24h).',
-        'If payment_required is true, pay $5 USDC to the payTo address on Base, then retry.',
+        'Submit a public GitHub repository for an automated Solidity analysis. The result is a list of AI-generated hypotheses to review by hand. It is not an audit and not a list of confirmed bugs.',
+        'The scan reads the files most likely to move funds first, in at most six parts. Tests, mocks, scripts, interfaces and vendored dependencies are left out. The report states what share of the in-scope code was actually read, and a report can say that no hypotheses came out of the part that was read.',
+        'Check the repository first, for free: GET https://x402.tokenizen.nl/api/bug-intel/precheck?repo=owner/name says whether the scan counts any Solidity in it and roughly how much of it will be read.',
+        'How often the scan finds known issues on closed audit contests, including the misses, is published in the README of the repository (github.com/holistis/bug-bounty-intelligence-mcp). The prompt uses acceptance-rate hints from the 1,032 findings that could be exact-reconciled against contest outcomes, see METHODOLOGY.md.',
+        'Cost: $5 USDC on Base (eip155:8453) via x402. Reports usually arrive within the hour. If the scan fails or the report does not help, write to info@holistischadviseur.nl for a new attempt or a refund, see the terms.',
+        'Returns a job_id. Use get_scan_report to poll for results.',
+        'If payment_required is true, pay $5 USDC to the payTo address on Base, then retry scan_contract with the same repo_url.',
       ].join(' '),
       inputSchema: {
         type: 'object',
@@ -117,7 +119,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'get_scan_report',
-      description: 'Poll the status of a previously submitted scan. Returns status (queued/processing/complete) and report URL when complete.',
+      description: [
+        'Poll the status of a job_id returned by scan_contract.',
+        'Call this every few minutes after submitting. Reports usually arrive within the hour; polling faster just re-checks a job that is still processing.',
+        'Returns status (queued/processing/complete/failed), the repo under scan, and once complete the reportUrl (the report of hypotheses, with the share of code that was read), the outcome and the coverage. A failed job says why and where to write for a new attempt or a refund.',
+        'A 404 means the job_id does not exist — double-check what scan_contract actually returned rather than retrying blindly.',
+      ].join(' '),
       inputSchema: {
         type: 'object',
         properties: {
@@ -163,6 +170,17 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     if (status === 402) {
       const accept  = json.accepts?.[0] ?? {}
       const amtUsdc = accept.amount ? (parseInt(accept.amount) / 1_000_000).toFixed(2) : '5.00'
+      if (!accept.payTo || !accept.asset) {
+        // Never fall back to a hardcoded address here: a stale one silently
+        // sends real USDC to a wallet nobody is watching. Fail loud instead.
+        return {
+          content: [{
+            type: 'text',
+            text: 'PAYMENT REQUIRED, but the server did not return a payment address. Do not guess one. Retry scan_contract; if this repeats, the payment endpoint is broken, not the address.',
+          }],
+          isError: true,
+        }
+      }
       return {
         content: [{
           type: 'text',
@@ -171,11 +189,11 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             '',
             `Amount:  ${amtUsdc} USDC`,
             `Network: Base mainnet (eip155:8453)`,
-            `Pay to:  ${accept.payTo ?? '0xdffcC75a674257be6FE1b5549FE52e8f8a6A3A5A'}`,
-            `Asset:   USDC — ${accept.asset ?? '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'}`,
+            `Pay to:  ${accept.payTo}`,
+            `Asset:   USDC — ${accept.asset}`,
             '',
             'After paying, retry scan_contract with the same repo_url.',
-            'Terms: https://wazir-x402.duckdns.org/terms',
+            'Terms: https://x402.tokenizen.nl/terms',
           ].join('\n'),
         }],
         isError: false,
@@ -191,7 +209,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             `Status: ${json.status ?? 'queued'}`,
             '',
             `Poll for results: get_scan_report({ job_id: "${json.jobId}" })`,
-            `Results are typically ready within 24 hours.`,
+            `Reports usually arrive within the hour. The report states how much of the code was read.`,
           ].join('\n'),
         }],
       }

package/package.json

@@ -1,18 +1,40 @@
 {
   "name": "bug-bounty-intelligence-mcp",
-  "version": "1.0.2",
-  "description": "MCP server for AI-powered smart contract security analysis. $5 USDC/scan via x402. Drawn from 27,681 Sherlock/Code4rena submissions, verified acceptance rates from 1,032 exact-reconciled findings.",
+  "version": "1.0.5",
+  "description": "MCP server for AI-powered smart contract security analysis. $5 USDC/scan via x402. Drawn from 27,681 Sherlock/Code4rena submissions, verified acceptance rates from 1,032 exact-reconciled findings. Includes a free, standalone dataset (vulnerability-acceptance-rates.json) — no server required.",
   "type": "module",
   "main": "index.mjs",
-  "bin": { "bug-bounty-intelligence-mcp": "index.mjs" },
-  "files": ["index.mjs", "README.md", "BENCHMARK.md", "METHODOLOGY.md"],
-  "repository": { "type": "git", "url": "git+https://github.com/holistis/bug-bounty-intelligence-mcp.git" },
+  "bin": {
+    "bug-bounty-intelligence-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "BENCHMARK.md",
+    "METHODOLOGY.md",
+    "vulnerability-acceptance-rates.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holistis/bug-bounty-intelligence-mcp.git"
+  },
   "homepage": "https://github.com/holistis/bug-bounty-intelligence-mcp#readme",
-  "keywords": ["mcp", "smart-contract", "security", "audit", "solidity", "defi", "x402", "bug-bounty"],
+  "keywords": [
+    "mcp",
+    "smart-contract",
+    "security",
+    "audit",
+    "solidity",
+    "defi",
+    "x402",
+    "bug-bounty"
+  ],
   "author": "holistis",
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
-  "engines": { "node": ">=20.0.0" }
-}
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/vulnerability-acceptance-rates.json

@@ -0,0 +1,97 @@
+{
+  "$schema_note": "Free, standalone dataset — no server, no API key, no payment. Embed directly in your own tool.",
+  "source": "Sherlock audit-competition judging repos (public GitHub)",
+  "license": "CC0 — public domain, use freely with or without attribution",
+  "methodology_url": "https://github.com/holistis/bug-bounty-intelligence-mcp/blob/main/METHODOLOGY.md",
+  "last_updated": "2026-07-21T19:51:20.564Z",
+  "contests_included": 10,
+  "total_findings": 1032,
+  "total_accepted": 461,
+  "note": "Only contests where accepted+invalid counts reconcile exactly against Sherlock own published results are included. See methodology_url for full scope, limitations, and reproduction steps.",
+  "patterns": {
+    "fee-miscalculation": {
+      "acceptance_rate": 0.5,
+      "accepted": 55,
+      "rejected": 51,
+      "duplicated": 3,
+      "total": 109
+    },
+    "dos-griefing": {
+      "acceptance_rate": 0.41,
+      "accepted": 64,
+      "rejected": 90,
+      "duplicated": 2,
+      "total": 156
+    },
+    "reentrancy": {
+      "acceptance_rate": 0.78,
+      "accepted": 40,
+      "rejected": 11,
+      "duplicated": 0,
+      "total": 51
+    },
+    "trusted-actor": {
+      "acceptance_rate": 0.51,
+      "accepted": 159,
+      "rejected": 148,
+      "duplicated": 4,
+      "total": 311
+    },
+    "overflow": {
+      "acceptance_rate": 0.58,
+      "accepted": 26,
+      "rejected": 19,
+      "duplicated": 0,
+      "total": 45
+    },
+    "staleness": {
+      "acceptance_rate": 0.49,
+      "accepted": 86,
+      "rejected": 84,
+      "duplicated": 4,
+      "total": 174
+    },
+    "rounding": {
+      "acceptance_rate": 0.4,
+      "accepted": 25,
+      "rejected": 38,
+      "duplicated": 0,
+      "total": 63
+    },
+    "access-control": {
+      "acceptance_rate": 0.47,
+      "accepted": 35,
+      "rejected": 39,
+      "duplicated": 0,
+      "total": 74
+    },
+    "oracle-manipulation": {
+      "acceptance_rate": 0.36,
+      "accepted": 47,
+      "rejected": 78,
+      "duplicated": 6,
+      "total": 131
+    },
+    "mev-slippage": {
+      "acceptance_rate": 0.49,
+      "accepted": 44,
+      "rejected": 44,
+      "duplicated": 1,
+      "total": 89
+    },
+    "liquidation": {
+      "acceptance_rate": 0.29,
+      "accepted": 4,
+      "rejected": 9,
+      "duplicated": 1,
+      "total": 14
+    },
+    "flash-loan": {
+      "acceptance_rate": 0.46,
+      "accepted": 6,
+      "rejected": 6,
+      "duplicated": 1,
+      "total": 13
+    }
+  }
+}