bug-bounty-intelligence-mcp 1.0.0 → 1.0.1

package/BENCHMARK.md

@@ -0,0 +1,160 @@
+# 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)

package/README.md

@@ -6,6 +6,14 @@ AI-powered smart contract security analysis for AI agents and developers.
 **Cost: $5 USDC on Base (eip155:8453) via x402.**
 **Free tool: `list_vulnerability_patterns` — no payment needed.**
 
+## 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.
+
 ## 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.
@@ -27,7 +35,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "bug-bounty-intelligence": {
       "command": "npx",
-      "args": ["-y", "github:holistis/bug-bounty-intelligence-mcp"]
+      "args": ["-y", "bug-bounty-intelligence-mcp@latest"]
     }
   }
 }
@@ -36,7 +44,7 @@ Add to your `claude_desktop_config.json`:
 Or run directly:
 
 ```bash
-node index.mjs
+npx -y bug-bounty-intelligence-mcp@latest
 ```
 
 ## Payment

package/index.mjs

@@ -19,14 +19,24 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
-import { readFileSync, existsSync } from 'node:fs'
-import { join, dirname }             from 'node:path'
-import { fileURLToPath }             from 'node:url'
-
-const HERE    = dirname(fileURLToPath(import.meta.url))
-const BASE    = join(HERE, '..')
 const API_URL = 'https://wazir-x402.duckdns.org'
 
+// Embedded pattern library — 27,681 accepted findings from Sherlock + Code4rena (updated 2026-07-10)
+const PATTERN_LIBRARY = {
+  'rounding':           { acceptance_rate: '0.51', total: 2615,  accepted: 1327, examples_accepted: ['Long Jetblack Porpoise - wrong calculation of borrowed amount causes migrateFrom', 'Gentle Mango Locust - Duplicate Reward Tokens Can Be Added, Leading to Denial of', 'Tiny Smoke Swift - No Liquidation Incentive for Small Positions'] },
+  'oracle-manipulation':{ acceptance_rate: '0.53', total: 3253,  accepted: 1736, examples_accepted: ['Boxy Pickle Corgi - Users lose the latest accrued rewards during migration if pr', 'Tiny Smoke Swift - No Liquidation Incentive for Small Positions', 'Flat Cedar Robin - AbstractYieldStrategy.price() implementation is wrong'] },
+  'trusted-actor':      { acceptance_rate: '0.46', total: 8820,  accepted: 4081, examples_accepted: ['Agreeable Pine Porpoise - Double Fee Accrual in Withdrawal Flow Causes Last User', 'Rare Parchment Monkey - Migration of the reward pool will render the strategy co', 'Boxy Pickle Corgi - Users lose the latest accrued rewards during migration'] },
+  'fee-miscalculation': { acceptance_rate: '0.56', total: 2676,  accepted: 1505, examples_accepted: ['Clean Gauze Halibut - Incorrect update of s_escrowedShares causes later users', 'Flat Cedar Robin - AbstractYieldStrategy.price() implementation is wrong', 'Generous Sandstone Raven - Escrowed shares and their underlying yield tokens'] },
+  'mev-slippage':       { acceptance_rate: '0.54', total: 1874,  accepted: 1006, examples_accepted: ['Wide Lavender Octopus - User can go with less tokens', 'Innocent Mahogany Baboon - Intended slippage parameter for liquidators will not', 'Stale Ebony Reindeer - AbstractSingleSidedLP execution'] },
+  'dos-griefing':       { acceptance_rate: '0.49', total: 3702,  accepted: 1796, examples_accepted: ['Long Jetblack Porpoise - wrong calculation of borrowed amount causes migrateFrom', 'Gentle Mango Locust - Duplicate Reward Tokens Can Be Added, Leading to Denial of', 'Fast Quartz Elephant - Shares minted for ERC20 WRM yield strategy deposits'] },
+  'access-control':     { acceptance_rate: '0.51', total: 2480,  accepted: 1259, examples_accepted: ['Decent Saffron Woodpecker - Lack of Access Control in updateAccountRewards', 'Tricky Eggplant Orangutan - Cooldown Griefing via Delegated enterPosition', 'Hot Viridian Sidewinder - Transient Storage Authorization Persists After Failed'] },
+  'staleness':          { acceptance_rate: '0.45', total: 5838,  accepted: 2649, examples_accepted: ['Jumpy Tartan Guppy - claimRewardToken does not update emission rate claiming', 'Boxy Pickle Corgi - Users lose the latest accrued rewards during migration', 'Joyful Caramel Cuckoo - Attacker Can Reenter Redemption Process'] },
+  'reentrancy':         { acceptance_rate: '0.47', total: 979,   accepted: 458,  examples_accepted: ['Joyful Caramel Cuckoo - Attacker Can Reenter Redemption Process', 'Fast Quartz Elephant - Shares minted for ERC20 WRM yield strategy deposits', 'Soaring Carrot Cow - Attacker Will Steal Yield Funds via Reentrancy'] },
+  'overflow':           { acceptance_rate: '0.47', total: 1256,  accepted: 586,  examples_accepted: ['Gentle Mango Locust - Duplicate Reward Tokens Can Be Added', 'Stale Ebony Reindeer - AbstractSingleSidedLP execution', 'Tiny Smoke Swift - Liquidation Front-Running via Minimal Repay'] },
+  'flash-loan':         { acceptance_rate: '0.53', total: 512,   accepted: 269,  examples_accepted: ['Long Jetblack Porpoise - wrong calculation of borrowed amount causes migrateFrom', 'Fancy Ultraviolet Raccoon - Missing Checks for Flash Loan Callback in _enterPosition', 'Cool Clay Cottonmouth - use of approve(type(uint256).max) in the exit flow'] },
+  'liquidation':        { acceptance_rate: '0.53', total: 2502,  accepted: 1319, examples_accepted: ['Generous Sandstone Raven - Liquidators can steal rewards accrued to liquidated', 'Rare Parchment Monkey - Migration of the reward pool will render the strategy', 'Joyful Caramel Cuckoo - Attacker Can Reenter Redemption Process'] },
+}
+
 // ── helpers ──────────────────────────────────────────────────────────────────
 
 async function callApi(path, method = 'GET', body = null, extraHeaders = {}) {
@@ -36,34 +46,34 @@ async function callApi(path, method = 'GET', body = null, extraHeaders = {}) {
     signal: AbortSignal.timeout(30_000),
   }
   if (body) opts.body = JSON.stringify(body)
-  const res  = await fetch(`${API_URL}${path}`, opts)
-  const text = await res.text()
-  let json
-  try { json = JSON.parse(text) } catch { json = { raw: text } }
-  return { status: res.status, ok: res.ok, json }
+  try {
+    const res  = await fetch(`${API_URL}${path}`, opts)
+    const text = await res.text()
+    let json
+    try { json = JSON.parse(text) } catch { json = { raw: text } }
+    return { status: res.status, ok: res.ok, json }
+  } catch (err) {
+    const reason = err.name === 'TimeoutError' || err.name === 'AbortError' ? 'timed out after 30s' : err.message
+    return { status: 0, ok: false, json: { error: `Could not reach ${API_URL} (${reason})` } }
+  }
 }
 
 function ilmPatterns(protocolType) {
-  const idx = join(BASE, 'knowledge/3ilm/sherlock/_index.json')
-  if (!existsSync(idx)) return null
-  try {
-    const lib   = JSON.parse(readFileSync(idx, 'utf8')).pattern_library ?? {}
-    const TYPE  = {
-      DEX:         ['oracle-manipulation','mev-slippage','rounding','flash-loan','fee-miscalculation','reentrancy'],
-      LENDING:     ['oracle-manipulation','liquidation','staleness','rounding','flash-loan','access-control'],
-      BRIDGE:      ['access-control','reentrancy','overflow','dos-griefing'],
-      GOVERNANCE:  ['access-control','dos-griefing','trusted-actor'],
-      STAKING:     ['rounding','fee-miscalculation','access-control','overflow','staleness'],
-      GENERAL:     ['oracle-manipulation','rounding','access-control','fee-miscalculation','reentrancy','flash-loan'],
-    }
-    const keys = TYPE[protocolType?.toUpperCase()] ?? TYPE.GENERAL
-    return keys.filter(k => lib[k]).map(k => ({
-      pattern:         k,
-      acceptance_rate: lib[k].acceptance_rate,
-      total_cases:     lib[k].total,
-      example:         (lib[k].examples_accepted ?? [])[0]?.slice(0, 120),
-    }))
-  } catch { return null }
+  const TYPE = {
+    DEX:        ['oracle-manipulation','mev-slippage','rounding','flash-loan','fee-miscalculation','reentrancy'],
+    LENDING:    ['oracle-manipulation','liquidation','staleness','rounding','flash-loan','access-control'],
+    BRIDGE:     ['access-control','reentrancy','overflow','dos-griefing'],
+    GOVERNANCE: ['access-control','dos-griefing','trusted-actor'],
+    STAKING:    ['rounding','fee-miscalculation','access-control','overflow','staleness'],
+    GENERAL:    ['oracle-manipulation','rounding','access-control','fee-miscalculation','reentrancy','flash-loan'],
+  }
+  const keys = TYPE[protocolType?.toUpperCase()] ?? TYPE.GENERAL
+  return keys.filter(k => PATTERN_LIBRARY[k]).map(k => ({
+    pattern:         k,
+    acceptance_rate: PATTERN_LIBRARY[k].acceptance_rate,
+    total_cases:     PATTERN_LIBRARY[k].total,
+    example:         (PATTERN_LIBRARY[k].examples_accepted ?? [])[0]?.slice(0, 120),
+  }))
 }
 
 // ── MCP server ────────────────────────────────────────────────────────────────
@@ -194,13 +204,20 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       return { content: [{ type: 'text', text: 'Error: job_id is required' }], isError: true }
     }
 
-    const { status, json } = await callApi(`/api/bug-intel/${encodeURIComponent(job_id)}`)
+    const { status, ok, json } = await callApi(`/api/bug-intel/${encodeURIComponent(job_id)}`)
 
     if (status === 404) {
       return { content: [{ type: 'text', text: `Job ${job_id} not found. Check the job_id.` }], isError: true }
     }
 
-    const lines = [`Job ID: ${job_id}`, `Status: ${json.status ?? 'unknown'}`]
+    if (!ok || !json.status) {
+      return {
+        content: [{ type: 'text', text: `Could not get status for job ${job_id}: ${json.error ?? `API error ${status}`}. Try again shortly.` }],
+        isError: true,
+      }
+    }
+
+    const lines = [`Job ID: ${job_id}`, `Status: ${json.status}`]
     if (json.repo)      lines.push(`Repo: ${json.repo}`)
     if (json.reportUrl) lines.push(`Report: ${json.reportUrl}`)
     if (json.findingsCount !== undefined) lines.push(`Findings: ${json.findingsCount}`)
@@ -216,9 +233,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { protocol_type = 'GENERAL' } = args ?? {}
     const patterns = ilmPatterns(protocol_type)
 
-    if (!patterns) {
+    if (!patterns || patterns.length === 0) {
       return {
-        content: [{ type: 'text', text: 'Pattern library not available locally. Run scan_contract for live analysis.' }],
+        content: [{ type: 'text', text: 'No patterns found for this protocol type. Try GENERAL.' }],
       }
     }
 

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "bug-bounty-intelligence-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for AI-powered smart contract security analysis. $5 USDC/scan via x402. Trained on 27,681 real Sherlock/Code4rena findings.",
   "type": "module",
   "main": "index.mjs",
   "bin": { "bug-bounty-intelligence-mcp": "index.mjs" },
+  "files": ["index.mjs", "README.md", "BENCHMARK.md"],
+  "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"],
   "author": "holistis",
   "license": "MIT",

package/Dockerfile

@@ -1,6 +0,0 @@
-FROM node:20-slim
-WORKDIR /app
-COPY package.json .
-RUN npm install
-COPY . .
-CMD ["node", "index.mjs"]

package/smithery.yaml

@@ -1,9 +0,0 @@
-# Smithery configuration: https://smithery.ai/docs/config#smitheryyaml
-
-startCommand:
-  type: stdio
-  configSchema:
-    type: object
-    properties: {}
-  commandFunction: |-
-    (config) => ({command: 'node', args: ['index.mjs'], env: {}})