Skip to content

darks0l/threat-lab

BranchesTags

Repository files navigation

DARKSOL Built by DARKSOL 🌑

🔬 Threat Lab

Threat Assessment npm version tests Solidity Foundry License: MIT Built with teeth

Threat Lab Banner

Unified Solidity security scanner and threat research CLI — static analysis, dependency audit, live threat intel, exploit simulation, and watch-mode monitoring.

The threat landscape is a moving target. MEV bots, flash loan attacks, oracle manipulation — by the time a new exploit pattern is understood well enough to defend against, dozens of protocols have already been hit. The window between "detected" and "exploited" is milliseconds. The window between "exploited" and "patched" is weeks.

Threat Lab is the research infrastructure for that gap. Instead of waiting for the next attack to happen on mainnet, security researchers deploy realistic exploit scenarios in a sandboxed environment, get AI-powered analysis of the attack mechanics, and submit findings to a growing pattern library. The platform gets smarter with every submission.

How it works

┌─────────────┐     ┌──────────────┐     ┌────────────┐     ┌──────────────┐
│  Scenario   │────▶│   Execute    │────▶│  Analyze   │────▶│   Library    │
│  Library    │     │ (Anvil/Sepolia)│     │(multi-model)│     │  (grows)     │
└─────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
                           │                    │
                           ▼                    ▼
                    Real tx traces       Threat Report
                    + gas analysis      + recommendations
  1. Choose a scenario — pre-built exploit templates or your own
  2. Execute it — deploy contracts to Anvil or Base Sepolia, run exploit steps, capture real tx traces
  3. Get AI analysis — multi-model analysis via Bankr LLM gateway produces structured threat reports
  4. Submit to library — findings are stored permanently, searchable, citable
  5. Pattern library compounds — every submission makes future analysis smarter

Quick start

Install

npm install threat-lab

Quick Start

# Check status
npx threat-lab status

# List scenarios + library
npx threat-lab list

# Unified scan — all 4 layers in one pass (recommended)
npx threat-lab scan .                   # full: static + deps + intel + exploit sim
npx threat-lab scan . --quick           # fast: static + deps (no Anvil)
npx threat-lab scan . --no-intel        # skip live threat intel
npx threat-lab scan . --deep            # full + modelab deep research + patch generation
npx threat-lab scan . --output report.md # save a reusable markdown report
npx threat-lab scan . --output .reports/security/threat-lab.sarif # nested dirs auto-create
npx threat-lab scan . --compare baseline.json # see what changed vs a prior scan
npx threat-lab scan . --fail-on high    # fail CI/builds on high+ findings

# Continuous monitoring / watch mode
npx threat-lab watch . --interval 60              # rescan every minute
npx threat-lab watch . --interval 30 --iterations 5 # run 5 monitor cycles then exit
npx threat-lab watch . --out-dir .threat-lab/watch # save per-cycle snapshots

# Fleet monitor / multi-repo monitoring
npx threat-lab monitor add ../repo-a ../repo-b
npx threat-lab monitor list
npx threat-lab monitor scan --output .reports/security/fleet.json

# Analyze a Solidity file directly (static analysis only)
npx threat-lab analyze ./contracts/MyVault.sol

# Dependency audit only (npm + OSV + Socket.dev)
npx threat-lab audit .
npx threat-lab audit ./ --no-socket   # skip Socket.dev (no API key)

# Execute a scenario (requires Anvil running)
npx threat-lab run reentrancy-101 --network anvil

# Search the pattern library
npx threat-lab library search reentrancy

# View library stats
npx threat-lab library

# Export library (IPFS-ready)
npx threat-lab export

Scenarios

ID Pattern Severity Difficulty
reentrancy-101 Reentrancy vault drain Critical Beginner
oracle-manipulation-101 Uniswap V2 oracle manipulation High Intermediate
flash-loan-101 Flash loan arbitrage Medium Beginner
sandwich-attack-101 AMM sandwich attack High Intermediate
governance-attack-101 DAO governance flash loan takeover Critical Advanced
liquidation-attack-101 Aave V2 oracle liquidation attack High Advanced

Architecture

threat-lab/
├── src/
│   ├── schemas.ts           # Zod schemas for all entities
│   ├── scenarios.ts         # Built-in attack scenario library
│   ├── executor.ts          # Deploy contracts + run exploit steps
│   ├── runner.ts            # Full orchestrator: execute → analyze → library
│   ├── modelabIntegration.ts # Multi-model AI analysis via Bankr gateway
│   ├── analyzer.ts          # AI analysis engine (signature + LLM)
│   ├── patternDetector.ts    # Pattern matching against known signatures
│   ├── library.ts           # Persistent pattern library (IPFS-ready)
│   ├── scanner.ts           # Unified scan orchestrator (static + deps + sim)
│   ├── audit.ts             # Dependency audit (OSV + npm + Socket.dev)
│   ├── auditSchemas.ts      # Zod schemas for audit result types
│   ├── api.ts               # Submission endpoint handler
│   └── cli.ts               # Full CLI (scan/audit/run/analyze/library/export)
├── contracts/              # Exploitable Solidity contract templates
│   ├── ReentrancyVault.sol
│   ├── OracleManipulation.sol
│   ├── FlashLoanAttacker.sol
│   └── *.sol                # Additional scenario contracts
├── library/                # Pattern library storage (created at runtime)
│   ├── index.json           # Library index
│   └── reports/             # Individual threat reports
├── scripts/
│   └── deploy.ts            # Deploy scenarios to Anvil / Base Sepolia
├── test/                   # Foundry/Forge tests
└── foundry.toml            # Forge configuration

The execution loop

threat-lab run reentrancy-101

⚡ Executing: Reentrancy Vault Drain
   Network: anvil | RPC: http://127.0.0.1:8545

  [0] Deployed ReentrancyVault at 0x5FbDB2315678afecb367f032d93F642f54180a3E
  [1] Funded vault with 10 ETH
  [2] Deployed Attacker contract
  [3] Executed attack(10 ETH) -> recursive withdrawal confirmed

📋 Captured 4 transactions

🧠 Running modelab analysis for: Reentrancy Vault Drain
   Models: claude-sonnet-4-6
  ✅ claude-sonnet-4-6: reentrancy (80% confidence) — 1420ms

🏆 Best analysis: claude-sonnet-4-6 — reentrancy (80% conf)

📚 Added to pattern library:
   ID: a1b2c3d4-...
   Pattern: reentrancy | Severity: critical
   Library size: 7 entries

────────────────────────────────────────────────────────────
📋 THREAT REPORT — Reentrancy Vault Drain
   Pattern:   reentrancy
   Severity:   critical
   Confidence: 80%
   AI Model:  claude-sonnet-4-6

   Recommendations:
   - Implement CEI pattern (Checks-Effects-Interactions)
   - Add ReentrancyGuard from OpenZeppelin
   - Use pull-based withdrawal pattern instead of push
────────────────────────────────────────────────────────────

Pattern library

The library currently recognizes:

  • reentrancy — external calls before state updates
  • oracle-manipulation — spot price oracle attacks
  • flash-loan-attack — uncollateralized borrow + arbitrage
  • access-control — missing permission checks
  • front-running — MEV transaction order exploitation
  • sandwich-attack — front-run + back-run combo
  • integer-overflow — unchecked arithmetic
  • delegatecall-injection — storage corruption via delegatecall
  • permit-front-run — EIP712 signature replay
  • liquidation-attack — oracle-manipulated liquidation exploit

Every submission expands the library. New patterns can be added by submitting a new scenario.

Community submissions are reviewed manually. See library/SUBMISSION_GUIDE.md for the full workflow, JSON format, and review criteria.

Environment variables

# Bankr LLM gateway (required for AI analysis + modelab deep research)
BANKR_API_KEY=your_bankr_api_key

# Brave Search API (optional — enables Layer 2b live threat intel)
# Get free key at: https://brave.com/search/api/
BRAVE_SEARCH_API_KEY=your_brave_api_key

# Anvil (defaults to http://127.0.0.1:8545)
ANVIL_RPC=http://127.0.0.1:8545

# Base Sepolia deployment
BASE_SEPOLIA_RPC=https://sepolia.base.org
DEPLOYER_PRIVATE_KEY=0x...

The unified scan — all 4 layers in one command

npx threat-lab scan .

🔬 Threat Lab — Scanning .
   Static analysis:   always on (signature patterns + AI deep-read)
   Dependency audit: ON (npm + OSV.dev + Socket.dev)
   Exploit sim:      ON (Anvil)

  🟠 contracts/MyVault.sol [score: 72] [exploit sim: liquidation-attack]
  🔴 contracts/GovToken.sol [score: 89] [exploit sim: governance-attack]
  🟢 contracts/SafeMath.sol [score: 3]

   Overall Threat: HIGH | Score: 80/100 | 3 files

The unified scan command runs four independent passes, then can stay live in watch mode for rescans and diffs:

SARIF output for CI / code scanning

Threat Lab can export scan findings as SARIF 2.1.0 for GitHub code scanning and other security tooling.

npx threat-lab scan . --output .reports/security/threat-lab.sarif

Custom output directories are created automatically, so nested paths are safe.

Fleet state files

Threat Lab stores fleet-monitor state locally under .threat-lab/:

  • fleet.json - registered repos in the monitoring fleet
  • fleet-last.json - most recent fleet scan output
  • threat-state.json - persistent deduped threat memory across scans

threat-state.json is where active package-level threat intel starts becoming durable instead of one-shot search noise.

GitHub Action wrapper

Threat Lab now ships a reusable composite action, so repos can use it directly:

name: threat-lab

on:
  push:
    branches: [main]
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Threat Lab scan
        uses: darks0l/threat-lab@v0
        with:
          path: .
          scan-args: --quick --no-intel --fail-on high
          output: .reports/security/threat-lab.sarif

Action inputs

  • path — path to scan (default: .)
  • node-version — Node version for the run (default: 20)
  • install-command — dependency install command (default: npm ci)
  • build-command — build command (default: npm run build)
  • scan-args — extra args passed to threat-lab scan (default: --quick --no-intel)
  • output — SARIF output path (default: .reports/security/threat-lab.sarif)
  • upload-sarif — whether to upload SARIF automatically (default: true)

Manual GitHub Actions example

If you want the lower-level version instead of the wrapper:

name: threat-lab

on:
  push:
    branches: [main]
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install deps
        run: npm ci

      - name: Build Threat Lab
        run: npm run build

      - name: Run Threat Lab SARIF scan
        run: node dist/cli.js scan . --quick --no-intel --output .reports/security/threat-lab.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: .reports/security/threat-lab.sarif

If you want CI to fail on serious findings too, add --fail-on high to the scan command or to scan-args in the wrapper.

Layer 1 — Static Analysis (always on) Signature pattern matching against all known attack patterns + Bankr AI deep-read of contract code. Scans every .sol file in the target path recursively.

Layer 2 — Dependency Audit (if node_modules present) Queries OSV.dev, npm Security Advisories, and Socket.dev for known vulnerabilities and malicious packages. Active exploits (CVEs described as "actively exploited") are flagged at highest priority.

Layer 2b — Live Threat Intelligence (always on, requires internet) After static vuln DB checks, searches the live web for package mentions in the last 14 days and correlates them against declared project dependencies before escalating:

  • GitHub Security Advisories API (free, no key needed)
  • Brave Search API for X/Twitter and security blog discussions
  • Catches 0-days and active discussions NOT yet in CVE/OSV databases
  • Keywords: "actively exploited", "weaponized", "poc available", "zero-day"
  • Requires: BRAVE_SEARCH_API_KEY (get at brave.com/search/api)

Layer 3 — Exploit Simulation (if Anvil running + contract matched to scenario) Matches your contract to a built-in scenario by code signature, deploys it to Anvil, executes the attack, and runs the transaction trace through AI for a verdict.

Watch Mode (optional, watch <path>) Build a baseline scan, re-run on an interval, diff each cycle, emit only new/escalated high-signal findings, and optionally save JSON snapshots for later review.

Fleet Monitor (new, monitor ...) Threat Lab can now track multiple repos as a fleet:

  • threat-lab monitor add ../repo-a ../repo-b registers repos in .threat-lab/fleet.json
  • threat-lab monitor list shows the current fleet + last scan timestamps
  • threat-lab monitor scan runs repo-by-repo scans, builds shared dependency exposure maps, and persists threat memory to .threat-lab/threat-state.json
  • threat memory dedupes findings by package + source URL/title, tracks first seen / last seen / sightings, and records which repos are exposed

This is the first step toward org-scale autonomous monitoring: shared package blast radius, new threat detection, and persistent cross-repo intel state.

Deep Research (optional, --deep flag) Runs flagged findings through modelab's multi-model research pipeline:

  • Parallel research across multiple AI models (Sonnet, Opus, GLM)
  • Root cause analysis + impact assessment
  • Concrete exploit scenarios with parameters

Report Export

  • --output report.json saves the full machine-readable scan payload where you want it
  • --output report.md saves a readable markdown summary for sharing, review, or diffing between runs

Baseline Diffing

  • --compare baseline.json compares the current scan to a previous JSON export
  • highlights new findings, resolved files, and files whose severity/score changed
  • best used with saved --output report.json artifacts between commits or releases

Security Gates

  • --fail-on high exits non-zero when the worst scan severity is high or critical
  • supports: critical, high, medium, low, informational
  • useful for CI, release checks, and protected deployment workflows
  • Patch/remediation code generation in Solidity
  • Validated fix output with confidence scores
  • Requires: BANKR_API_KEY

Reports are saved to threat-reports/<file>.<pattern>.md and threat-reports/simulation/<scenario>.json.

Building

npm install
npm run build        # TypeScript compilation
forge build          # Solidity contracts (requires Foundry)
npm test             # Run SDK tests

Deploying scenarios

# Local Anvil (recommended for testing)
forge build && npx threat-lab run reentrancy-101 --network anvil

# Base Sepolia (requires DEPLOYER_PRIVATE_KEY)
npx threat-lab run reentrancy-101 --network base-sepolia

Built with teeth. 🌑

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

5 tags

Packages

 
 
 

Contributors

Languages