white-hat-scanner 1.0.1

package/src/contest.ts

@@ -0,0 +1,172 @@
+/**
+ * Code4rena and Sherlock contest calendar scraper.
+ *
+ * Fetches recently-created audit contest repos from `code-423n4` and `sherlock-audit`
+ * GitHub orgs. Active audit contests are live protocols with known codebases — ideal
+ * scan targets because the code is publicly accessible and the protocol is actively
+ * seeking security review.
+ *
+ * The contest repo itself (or the protocol code it mirrors) is used as the github field
+ * so our analyzer can clone and run Slither alongside Claude review.
+ */
+
+import { log } from './redis'
+import type { Protocol } from './discovery'
+
+const CONTEST_ORGS = ['code-423n4', 'sherlock-audit']
+const GITHUB_API = 'https://api.github.com'
+
+// Default TVL for contest protocols — they lack on-chain TVL data but are
+// vetted protocols worth auditing (otherwise they wouldn't pay for audits).
+const CONTEST_DEFAULT_TVL = 50_000_000
+
+// Only fetch repos created within this window (active/recent contests)
+const CONTEST_MAX_AGE_DAYS = 30
+
+interface GitHubRepo {
+  id: number
+  name: string
+  full_name: string
+  html_url: string
+  description: string | null
+  created_at: string
+  pushed_at: string
+  stargazers_count: number
+  language: string | null
+  fork: boolean
+  archived: boolean
+}
+
+/**
+ * Parse a human-readable protocol name from a contest repo name.
+ * Code4rena repos: "2024-01-protocolname" → "protocolname"
+ * Sherlock repos:  "2024-protocolname-audit" → "protocolname"
+ */
+export function parseProtocolName(org: string, repoName: string): string {
+  let name = repoName
+
+  // Strip leading date prefix: YYYY-MM- or YYYY-
+  name = name.replace(/^\d{4}-\d{2}-/, '').replace(/^\d{4}-/, '')
+
+  // Strip trailing "-audit" suffix (Sherlock convention)
+  name = name.replace(/-audit$/, '')
+
+  // Convert hyphens/underscores to spaces and title-case
+  name = name
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ')
+    .trim()
+
+  if (!name) return repoName
+
+  const source = org === 'code-423n4' ? 'C4' : 'Sherlock'
+  return `${name} (${source})`
+}
+
+/**
+ * Filter: skip repos that are clearly meta/admin repos, not protocol contest repos.
+ */
+function isContestRepo(org: string, repo: GitHubRepo): boolean {
+  if (repo.fork) return false
+  if (repo.archived) return false
+
+  const name = repo.name.toLowerCase()
+
+  // Skip org-level meta repos
+  const metaPatterns = [
+    /^\.github$/,
+    /^org-/,
+    /^template/,
+    /^docs$/,
+    /^website$/,
+    /^judging/,
+    /^judge/,
+    /^findings/,
+    /^leaderboard/,
+    /^governance/,
+  ]
+  if (metaPatterns.some((p) => p.test(name))) return false
+
+  // Code4rena contest repos start with a year
+  if (org === 'code-423n4') {
+    if (!/^\d{4}-/.test(name)) return false
+  }
+
+  // Sherlock contest repos end with -audit or start with a year
+  if (org === 'sherlock-audit') {
+    if (!name.includes('audit') && !/^\d{4}-/.test(name)) return false
+  }
+
+  return true
+}
+
+async function fetchOrgContests(org: string): Promise<Protocol[]> {
+  const cutoff = new Date(Date.now() - CONTEST_MAX_AGE_DAYS * 24 * 60 * 60 * 1000)
+  const protocols: Protocol[] = []
+  let page = 1
+
+  while (page <= 3) {
+    const url = `${GITHUB_API}/orgs/${org}/repos?type=public&sort=created&direction=desc&per_page=50&page=${page}`
+    const res = await fetch(url, {
+      headers: {
+        'User-Agent': 'white-hat-scanner/1.0',
+        Accept: 'application/vnd.github+json',
+      },
+      signal: AbortSignal.timeout(20_000),
+    })
+
+    if (!res.ok) {
+      if (res.status === 404) break // org might not exist
+      throw new Error(`GitHub API ${org} returned ${res.status}`)
+    }
+
+    const repos = (await res.json()) as GitHubRepo[]
+    if (repos.length === 0) break
+
+    for (const repo of repos) {
+      const createdAt = new Date(repo.created_at)
+      // Since repos are sorted by created desc, stop when we go past the cutoff
+      if (createdAt < cutoff) {
+        page = 999 // signal outer loop to stop
+        break
+      }
+
+      if (!isContestRepo(org, repo)) continue
+
+      const name = parseProtocolName(org, repo.name)
+      protocols.push({
+        id: `contest-${org}-${repo.name}`,
+        name,
+        github: repo.html_url,
+        chain: 'ethereum', // most DeFi audit contests are EVM-based
+        tvl: CONTEST_DEFAULT_TVL,
+        listedAt: createdAt.getTime(),
+      })
+    }
+
+    page++
+  }
+
+  return protocols
+}
+
+/**
+ * Fetch active/recent audit contest protocols from Code4rena and Sherlock.
+ * Returns Protocol objects ready to be queued via queueNewProtocols().
+ */
+export async function fetchContestProtocols(): Promise<Protocol[]> {
+  const all: Protocol[] = []
+
+  for (const org of CONTEST_ORGS) {
+    try {
+      const protocols = await fetchOrgContests(org)
+      await log(`Contest scraper (${org}): found ${protocols.length} recent contest repos`)
+      all.push(...protocols)
+    } catch (err) {
+      await log(`Contest scraper (${org}) error: ${(err as Error).message}`)
+    }
+  }
+
+  return all
+}

package/src/disclosure.ts

@@ -0,0 +1,111 @@
+import { getRedis, log } from './redis'
+import type { AnalysisResult } from './analyzer'
+import type { ScoredFinding } from './scorer'
+
+export interface DisclosureRecord {
+  id: string
+  protocolName: string
+  riskLevel: string
+  bounty: number
+  summary: string
+  contactedAt?: number
+  deadlineAt?: number
+  followUpAt?: number
+  publicAt?: number
+  status: 'pending' | 'contacted' | 'acknowledged' | 'fixed' | 'public' | 'expired'
+  createdAt: number
+}
+
+const DISCLOSURE_DEADLINE_MS = 72 * 60 * 60 * 1000
+const FOLLOWUP_MS = 24 * 60 * 60 * 1000
+
+export async function createDisclosureRecord(
+  result: AnalysisResult,
+  scored: ScoredFinding
+): Promise<DisclosureRecord> {
+  const redis = getRedis()
+  const id = `${result.protocolId}-${Date.now()}`
+
+  const record: DisclosureRecord = {
+    id,
+    protocolName: result.protocolName,
+    riskLevel: result.riskLevel,
+    bounty: result.estimatedBounty,
+    summary: result.disclosureSummary,
+    status: 'pending',
+    createdAt: Date.now(),
+  }
+
+  await redis.set(`whiteh:findings:${result.protocolId}`, JSON.stringify(result))
+  await redis.lpush('whiteh:disclosures', JSON.stringify(record))
+  await redis.ltrim('whiteh:disclosures', 0, 499)
+  await log(`Disclosure record created for ${result.protocolName} (${result.riskLevel})`)
+
+  return record
+}
+
+export async function checkDisclosureTimelines(): Promise<void> {
+  const redis = getRedis()
+  const rawRecords = await redis.lrange('whiteh:disclosures', 0, -1)
+
+  const now = Date.now()
+  let warnings = 0
+  let expired = 0
+
+  for (const raw of rawRecords) {
+    let record: DisclosureRecord
+    try {
+      record = JSON.parse(raw) as DisclosureRecord
+    } catch {
+      continue
+    }
+
+    if (record.status === 'public' || record.status === 'fixed') continue
+
+    if (record.contactedAt) {
+      const deadline = record.contactedAt + DISCLOSURE_DEADLINE_MS
+
+      if (now > deadline && record.status !== 'expired') {
+        await log(
+          `⏰ DEADLINE EXPIRED: ${record.protocolName} — 72h disclosure window passed, consider public disclosure`
+        )
+        expired++
+      } else if (deadline - now < FOLLOWUP_MS && record.status === 'contacted') {
+        await log(
+          `⚠️ FOLLOW-UP DUE: ${record.protocolName} — ${Math.floor((deadline - now) / 3_600_000)}h until deadline`
+        )
+        warnings++
+      }
+    }
+  }
+
+  if (warnings > 0 || expired > 0) {
+    await log(`Timeline check: ${warnings} follow-ups due, ${expired} deadlines expired`)
+  } else {
+    await log('Timeline check: all disclosures on track')
+  }
+}
+
+export function draftDisclosureEmail(record: DisclosureRecord): string {
+  return `Subject: Responsible Disclosure — Security Vulnerability in ${record.protocolName}
+
+Dear ${record.protocolName} Security Team,
+
+I am writing to responsibly disclose a security vulnerability I discovered in your protocol.
+
+Risk Level: ${record.riskLevel}
+${record.bounty > 0 ? `Estimated Bug Bounty: $${record.bounty.toLocaleString()}` : ''}
+
+Summary:
+${record.summary}
+
+I am disclosing this under a 72-hour responsible disclosure policy. I will refrain from publishing details until:
+1. You acknowledge receipt of this report
+2. A fix is deployed, OR
+3. 72 hours have elapsed from the timestamp of this email
+
+Please respond to confirm receipt.
+
+Regards,
+White Hat Security Researcher`
+}

package/src/discovery.ts

@@ -0,0 +1,297 @@
+import { getRedis, log } from './redis'
+import { fetchContestProtocols } from './contest'
+
+export interface Protocol {
+  id: string
+  name: string
+  github?: string
+  chain: string
+  tvl: number
+  listedAt?: number
+}
+
+interface DefiLlamaProtocol {
+  id: string
+  name: string
+  url?: string
+  description?: string
+  chain?: string
+  chains?: string[]
+  tvl?: number
+  listedAt?: number
+  github?: string[]
+}
+
+const DEFILLAMA_API = 'https://api.llama.fi/protocols'
+const TVL_THRESHOLD = 10_000_000
+const MAX_AGE_DAYS = 7
+
+/**
+ * Protocols with known exploit history from Rekt.news / public incident records.
+ * These are high-priority scan targets: prior exploits indicate architectural
+ * weaknesses or recurring vuln classes that may still be present in redeployments
+ * or sister protocols. Matched case-insensitively against protocol names.
+ *
+ * Sources: rekt.news all-time losses, Immunefi incident reports, DeFiHackLabs
+ */
+export const EXPLOIT_HISTORY_TARGETS: string[] = [
+  // Cross-chain bridges (historically highest losses)
+  'ronin', 'wormhole', 'nomad', 'multichain', 'anyswap', 'thorchain', 'harmony',
+  'poly network', 'polynetwork', 'orbit bridge', 'orbitbridge',
+  // Lending / money markets
+  'compound', 'aave', 'cream finance', 'cream', 'beanstalk', 'euler',
+  'inverse finance', 'mango markets', 'venus', 'moola',
+  // DEX / AMM
+  'uniswap', 'curve', 'balancer', 'kyber', 'dodo', 'pancakeswap',
+  'saddle finance', 'saddle',
+  // Yield / vault
+  'yearn', 'harvest finance', 'harvest', 'badger', 'rari capital',
+  'value defi', 'valuedefi', 'belt finance', 'belt', 'bunny finance', 'bunny',
+  // Stablecoin / algo-stable
+  'terra', 'anchor', 'fei', 'iron finance', 'ironfinance',
+  'deus finance', 'deus', 'mirror protocol',
+  // Other notable hacks
+  'bzx', 'fulcrum', 'indexed finance', 'indexed', 'uranium', 'spartan',
+  'merlin lab', 'merlin', 'ola finance', 'ola', 'pickle finance', 'pickle',
+  'alpha finance', 'alpha homora', 'mushroom', '88mph', 'cover protocol',
+  'kucoin', 'bitmart', 'vulcan forged', 'ronin network',
+]
+
+/**
+ * Returns true if the protocol name matches any known exploit target.
+ * Case-insensitive substring match.
+ */
+export function isExploitTarget(name: string): boolean {
+  const lower = name.toLowerCase()
+  return EXPLOIT_HISTORY_TARGETS.some((target) => lower.includes(target))
+}
+// Protocols without a GitHub repo produce only speculative Claude-only reviews with no real
+// code evidence, so they're not actionable for disclosure. Only queue them if their TVL is
+// exceptionally large (≥ $500M) — large enough that an architectural threat model has value.
+const NO_GITHUB_MIN_TVL = 500_000_000
+
+export async function discoverProtocols(): Promise<Protocol[]> {
+  await log('Starting protocol discovery from DeFiLlama + contest calendars...')
+
+  let protocols: Protocol[] = []
+
+  try {
+    protocols = await fetchDefiLlama()
+    await log(`DeFiLlama: found ${protocols.length} new protocols with TVL > $${TVL_THRESHOLD.toLocaleString()}`)
+  } catch (err) {
+    await log(`DeFiLlama fetch error: ${(err as Error).message}`)
+  }
+
+  try {
+    const contestProtocols = await fetchContestProtocols()
+    if (contestProtocols.length > 0) {
+      await log(`Contest calendars: found ${contestProtocols.length} active audit contest protocols`)
+      protocols = [...protocols, ...contestProtocols]
+    }
+  } catch (err) {
+    await log(`Contest scraper error: ${(err as Error).message}`)
+  }
+
+  return protocols
+}
+
+async function fetchDefiLlama(): Promise<Protocol[]> {
+  const res = await fetch(DEFILLAMA_API, {
+    headers: { 'User-Agent': 'white-hat-scanner/1.0' },
+    signal: AbortSignal.timeout(30_000),
+  })
+
+  if (!res.ok) {
+    throw new Error(`DeFiLlama API returned ${res.status}`)
+  }
+
+  const data = (await res.json()) as DefiLlamaProtocol[]
+  const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+
+  const filtered: Protocol[] = []
+  for (const p of data) {
+    const tvl = p.tvl ?? 0
+    const listedAt = p.listedAt ? p.listedAt * 1000 : 0
+
+    if (tvl < TVL_THRESHOLD) continue
+    if (listedAt && listedAt < cutoff) continue
+
+    // DeFiLlama github field is org names; build a searchable URL
+    const githubOrg = p.github && p.github.length > 0 ? p.github[0] : undefined
+    const github = githubOrg ? `https://github.com/${githubOrg}` : undefined
+    filtered.push({
+      id: p.id,
+      name: p.name,
+      github,
+      chain: p.chain || (p.chains && p.chains[0]) || 'unknown',
+      tvl,
+      listedAt: listedAt || Date.now(),
+    })
+  }
+
+  return filtered
+}
+
+export async function queueNewProtocols(protocols: Protocol[]): Promise<number> {
+  const redis = getRedis()
+  let queued = 0
+  let skippedNoGithub = 0
+  let prioritized = 0
+
+  for (const p of protocols) {
+    // Skip protocols that lack source code unless they are very high TVL.
+    // No-GitHub protocols generate only speculative architectural assessments
+    // (no real code to audit), and PR #5 already skips their disclosures —
+    // so queueing them wastes scan slots.
+    if (!p.github && p.tvl < NO_GITHUB_MIN_TVL) {
+      skippedNoGithub++
+      continue
+    }
+
+    const alreadyScanned = await redis.sismember('whiteh:scanned', p.id)
+    if (alreadyScanned) continue
+
+    // Use a parallel set (whiteh:queued) to track what's in the queue.
+    // lpos() on a JSON-object list requires an exact string match against the full
+    // serialised entry — it would never match a bare ID — so it was silently broken.
+    const alreadyQueued = await redis.sismember('whiteh:queued', p.id)
+    if (alreadyQueued) continue
+
+    // Protocols with known exploit history jump to the front of the queue —
+    // prior hacks indicate architectural weaknesses likely to recur.
+    if (isExploitTarget(p.name)) {
+      await redis.lpush('whiteh:queue', JSON.stringify(p))
+      prioritized++
+    } else {
+      await redis.rpush('whiteh:queue', JSON.stringify(p))
+    }
+    await redis.sadd('whiteh:queued', p.id)
+    queued++
+  }
+
+  if (queued > 0 || skippedNoGithub > 0) {
+    const priorityNote = prioritized > 0 ? ` (${prioritized} exploit-history targets front-queued)` : ''
+    await log(`Queued ${queued} new protocols for scanning (skipped ${skippedNoGithub} with no source code)${priorityNote}`)
+  }
+
+  return queued
+}
+
+/**
+ * Reorder existing queue entries so that exploit-history targets move to the front.
+ * Safe to call at startup — rewrites the queue atomically.
+ */
+export async function prioritizeExploitTargets(): Promise<number> {
+  const redis = getRedis()
+  const all = await redis.lrange('whiteh:queue', 0, -1)
+  const priority: string[] = []
+  const normal: string[] = []
+
+  for (const raw of all) {
+    try {
+      const p = JSON.parse(raw) as Protocol
+      if (isExploitTarget(p.name)) {
+        priority.push(raw)
+      } else {
+        normal.push(raw)
+      }
+    } catch {
+      normal.push(raw)
+    }
+  }
+
+  if (priority.length === 0) return 0
+
+  await redis.del('whiteh:queue')
+  const ordered = [...priority, ...normal]
+  if (ordered.length > 0) {
+    await redis.rpush('whiteh:queue', ...ordered)
+  }
+  await log(`Queue reordered: ${priority.length} exploit-history targets moved to front, ${normal.length} normal`)
+  return priority.length
+}
+
+/**
+ * Prune existing queue entries that have no GitHub repo and TVL below threshold,
+ * and remove entries for protocols already in whiteh:scanned (duplicate cleanup).
+ * Rebuilds whiteh:queued set from the surviving entries.
+ * Called once at startup.
+ */
+export async function pruneNoGithubFromQueue(): Promise<number> {
+  const redis = getRedis()
+  const all = await redis.lrange('whiteh:queue', 0, -1)
+  const keep: string[] = []
+  const seenIds = new Set<string>()
+  let pruned = 0
+
+  for (const raw of all) {
+    let p: Protocol
+    try {
+      p = JSON.parse(raw) as Protocol
+    } catch {
+      pruned++
+      continue
+    }
+
+    if (!p.github && p.tvl < NO_GITHUB_MIN_TVL) {
+      pruned++
+      continue
+    }
+
+    // Drop entries already scanned or already kept once (deduplicate)
+    const alreadyScanned = await redis.sismember('whiteh:scanned', p.id)
+    if (alreadyScanned || seenIds.has(p.id)) {
+      pruned++
+      continue
+    }
+
+    seenIds.add(p.id)
+    keep.push(raw)
+  }
+
+  // Atomically replace queue and rebuild the queued-ID set
+  await redis.del('whiteh:queue')
+  await redis.del('whiteh:queued')
+  if (keep.length > 0) {
+    await redis.rpush('whiteh:queue', ...keep)
+    for (const raw of keep) {
+      try {
+        const p = JSON.parse(raw) as Protocol
+        await redis.sadd('whiteh:queued', p.id)
+      } catch { /* skip */ }
+    }
+  }
+
+  if (pruned > 0) {
+    await log(`Queue pruned: removed ${pruned} entries (no-source/already-scanned/duplicates), ${keep.length} remaining`)
+  }
+
+  return pruned
+}
+
+export async function dequeueProtocol(): Promise<Protocol | null> {
+  const redis = getRedis()
+
+  // Pop entries until we find one that hasn't been scanned yet.
+  // Duplicate entries accumulated before the whiteh:queued fix was deployed
+  // (or race conditions between discovery and scan) are silently discarded here.
+  for (let attempts = 0; attempts < 20; attempts++) {
+    const raw = await redis.lpop('whiteh:queue')
+    if (!raw) return null
+
+    let p: Protocol
+    try {
+      p = JSON.parse(raw) as Protocol
+    } catch {
+      continue // malformed — discard
+    }
+
+    await redis.srem('whiteh:queued', p.id)
+
+    const alreadyScanned = await redis.sismember('whiteh:scanned', p.id)
+    if (!alreadyScanned) return p
+    // Already done — discard duplicate and try next
+  }
+
+  return null
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+import { discoverProtocols, queueNewProtocols, dequeueProtocol, pruneNoGithubFromQueue, prioritizeExploitTargets } from './discovery'
+import { analyzeProtocol } from './analyzer'
+import { scoreFindings } from './scorer'
+import { createDisclosureRecord, checkDisclosureTimelines } from './disclosure'
+import { sendAlert } from './notifier'
+import { generateSubmissionDraft } from './submission'
+import { getRedis, log } from './redis'
+
+const DISCOVER_INTERVAL_MS = 6 * 60 * 60 * 1000
+const SCAN_INTERVAL_MS = 30 * 60 * 1000
+const DISCLOSURE_CHECK_INTERVAL_MS = 60 * 60 * 1000
+
+async function runDiscovery(): Promise<void> {
+  try {
+    const protocols = await discoverProtocols()
+    const queued = await queueNewProtocols(protocols)
+    await log(`Discovery complete: ${protocols.length} protocols found, ${queued} new queued`)
+  } catch (err) {
+    await log(`Discovery error: ${(err as Error).message}`)
+  }
+}
+
+async function processScanQueue(): Promise<void> {
+  const redis = getRedis()
+
+  try {
+    const queueLen = await redis.llen('whiteh:queue')
+    await log(`Scan queue: ${queueLen} protocols pending`)
+
+    if (queueLen === 0) return
+
+    const protocol = await dequeueProtocol()
+    if (!protocol) return
+
+    await log(`Processing: ${protocol.name}`)
+
+    const result = await analyzeProtocol(protocol)
+    const scored = scoreFindings(result)
+
+    await redis.sadd('whiteh:scanned', protocol.id)
+
+    // Only track disclosures when source code was actually reviewed — no-source findings are
+    // speculative architectural assessments and don't meet the bar for responsible disclosure.
+    if (scored.sourceAvailable) {
+      await createDisclosureRecord(result, scored)
+    }
+
+    if (scored.needsAlert) {
+      await sendAlert(scored)
+    }
+
+    // Generate Immunefi submission draft for qualifying HIGH/CRITICAL findings (human review required)
+    await generateSubmissionDraft(result, scored)
+
+    await log(
+      `Completed: ${protocol.name} — ${scored.riskLevel} (severity: ${scored.severity.toFixed(1)}, bounty: $${scored.estimatedBounty})`
+    )
+  } catch (err) {
+    await log(`Scan queue error: ${(err as Error).message}`)
+  }
+}
+
+async function runDisclosureCheck(): Promise<void> {
+  try {
+    await checkDisclosureTimelines()
+  } catch (err) {
+    await log(`Disclosure check error: ${(err as Error).message}`)
+  }
+}
+
+async function main(): Promise<void> {
+  await log('=== white-hat-scanner starting ===')
+  await log(`Node ${process.version} | PID ${process.pid}`)
+
+  process.on('unhandledRejection', async (reason) => {
+    await log(`Unhandled rejection: ${reason}`)
+  })
+
+  process.on('uncaughtException', async (err) => {
+    await log(`Uncaught exception: ${err.message}`)
+    process.exit(1)
+  })
+
+  // One-time startup: prune queue bloat from before the GitHub filter was added.
+  await pruneNoGithubFromQueue()
+  // One-time startup: reorder existing queue so exploit-history targets scan first.
+  await prioritizeExploitTargets()
+
+  // Run immediately on startup
+  await runDiscovery()
+  await processScanQueue()
+  await runDisclosureCheck()
+
+  // Set up recurring intervals
+  setInterval(() => { runDiscovery().catch(console.error) }, DISCOVER_INTERVAL_MS)
+  setInterval(() => { processScanQueue().catch(console.error) }, SCAN_INTERVAL_MS)
+  setInterval(() => { runDisclosureCheck().catch(console.error) }, DISCLOSURE_CHECK_INTERVAL_MS)
+
+  await log('Service running — discovery every 6h, scanning every 30m, disclosure check every 1h')
+}
+
+main().catch(async (err) => {
+  console.error('[fatal]', err)
+  process.exit(1)
+})