Skip to content

README.md

Latest commit

 

History

History
218 lines (166 loc) · 7.62 KB

README.md

File metadata and controls

218 lines (166 loc) · 7.62 KB

ChainScout — Automated Smart Contract Security Scanner

MVP Status License Security Coverage Chains AI Engine

ChainScout is an open-source platform for automated security analysis of Web3 projects.
Supports Ethereum smart contracts, Solana programs, and dApp/Web3 applications with AI-powered reporting.

image image image

What It Does

  1. Smart Contract Analysis — Paste a contract address, get a full security report
  2. Solana Program Scanning — Analyze on-chain programs for upgradeability risks
  3. DApp / Web3 Surface Analysis — Detect wallet SDKs, signature prompts, chain gating
  4. AI-Powered Reports — Detailed audit reports via OpenRouter (Claude GPT-4o-mini)
  5. Slither Integration — AST-based deep analysis for Solidity contracts
  6. Risk Scoring — 0–100 weighted vulnerability scoring

Vulnerability Detection (7 Categories)

# Category Severity Description
1 Reentrancy Attacks HIGH External calls modifying state (CEI violations)
2 Integer Overflow/Underflow MEDIUM Arithmetic without SafeMath/Solidity 0.8+
3 tx.origin Misuse HIGH Phishing-vulnerable authorization
4 Unchecked Calls HIGH Low-level calls without return validation
5 Delegatecall Misuse CRITICAL Code injection via delegatecall
6 Access Control Issues CRITICAL Missing permission checks
7 Timestamp Dependence LOW Miner-manipulatable timestamps

Why ChainScout?

Feature ChainScout Slither Mythril Certora
Browser-based ✅ No CLI needed ❌ CLI only ❌ CLI only ❌ CLI only
AI-Powered Reports ✅ OpenRouter (Claude/GPT) ❌ ❌ ❌
Solana Support ✅ On-chain analysis ❌ ❌ ❌
DApp Surface Analysis ✅ Wallet SDK detection ❌ ❌ ❌
Risk Scoring ✅ 0–100 weighted ❌ ❌ ❌
Open Source ✅ MIT ✅ AGPL ✅ MIT ❌ Proprietary
Setup Time 2 min (Docker) 10 min 15 min Days

Quick Start (Docker Compose)

Prerequisites

1. Clone & Configure

git clone https://github.com/BarmaleiDB-infosec/ChainScout.git
cd ChainScout
cp .env.example .env
# Edit .env with your keys

2. Launch

docker compose up -d

3. Verify

curl http://localhost/health
# → {"status":"ok","service":"chainscout-api"}

Open http://localhost in browser.

Architecture

┌─────────────────┐
│   React App     │  Port 5173 (dev) / 80 (prod via Nginx)
│   (Vite + TS)   │
└────────┬────────┘
         │
    ┌────▼────┐
    │  Nginx   │  Reverse Proxy, Rate Limiting, Security Headers
    │  :80/443 │
    └────┬────┘
         │
    ┌────▼─────────┐
    │  Node.js API │  Express, JWT Auth, Scan Orchestration
    │    :4000     │
    └────┬─────────┘
         │
    ┌────┴──────────────────────┐
    │                           │
┌───▼──────┐          ┌────────▼────────┐
│ Supabase │          │ Security Engine  │
│ Auth + DB│          │ • 7 Detectors    │
│   RLS    │          │ • Slither (AST)  │
└──────────┘          │ • Infura (RPC)   │
                      │ • Solana Client  │
                      │ • OpenRouter AI  │
                      └─────────────────┘

API Endpoints

Authentication

Method Endpoint Description
POST /api/auth/register Create account
POST /api/auth/login Login, returns JWT

Scanning

Method Endpoint Description
POST /api/scans Start new scan
GET /api/scans/:id Get scan status/results
GET /api/scans/recent List recent scans
POST /api/solana/scan Scan Solana program

Health

Method Endpoint Description
GET /health Service status

Security

Feature Implementation
Row-Level Security Supabase RLS policies
JWT Authentication Bearer tokens on all endpoints
Rate Limiting Nginx-level (10 req/min auth, 1 req/min scan)
CORS Whitelisted origins only
SSRF Protection Private IP ranges blocked
Input Validation Address format, file type checks
Security Headers CSP, HSTS, X-Frame-Options, X-Content-Type-Options

Tech Stack

Layer Technology
Frontend React 18, TypeScript, Vite, TailwindCSS, shadcn/ui
Backend Node.js, Express
Database PostgreSQL (Supabase)
Auth Supabase Auth + JWT
AI OpenRouter (Claude / GPT-4o-mini)
Analysis Slither, Custom Heuristics, Etherscan V2 API, Infura RPC, Solana RPC
Infra Docker, Nginx, GitHub Actions

Environment Variables

Variable Required Description
SUPABASE_URL Yes Supabase project URL
SUPABASE_SERVICE_KEY Yes Supabase service role key
VITE_SUPABASE_PUBLISHABLE_KEY Yes Supabase anon key
ETHERSCAN_API_KEY Yes Etherscan API key
OPENROUTER_API_KEY No OpenRouter API key (for AI reports)
INFURA_API_KEY No Infura RPC key

Deployment

Production checklist:

  • Replace self-signed SSL with Let's Encrypt (certbot --nginx)
  • Set NODE_ENV=production
  • Enable firewall: ufw allow 22 && ufw allow 80 && ufw allow 443 && ufw enable
  • Configure monitoring (CPU > 80%, RAM > 90%, Disk > 85%)
  • Set up database backups

⚠️ Disclaimer

ChainScout is an automated analysis tool and should NOT replace professional security audits. Automated scanning can miss complex vulnerabilities. Always:

  • Have critical contracts audited by professional firms
  • Test thoroughly on testnet before mainnet deployment
  • Review generated reports with security expertise

License

MIT License

Built by the ChainScout Team | MVP Ready — May 2026