N3 - Nuclei for Web3 🛡️

Template-Based Security Scanner for Smart Contracts & DApps
From Development to Deployment - Continuous Security at Every Stage

🎯 What is N3?

N3 (Nuclei for Web3) is a template-based security scanner inspired by ProjectDiscovery's Nuclei. Instead of rigid static analysis rules, N3 uses human-readable YAML templates to detect vulnerabilities in Solidity smart contracts.

Core Philosophy: Templates > Hardcoded Rules

Traditional scanners have fixed, hardcoded rules. N3 lets you:

Create custom templates for new vulnerability patterns
Share templates across teams and communities
Update detection logic without changing code
Combine multiple templates for comprehensive scans
Calculate risk scores based on template matches

Example Template

id: reentrancy-001
name: Reentrancy Vulnerability
severity: CRITICAL
category: smart-contract
description: Detects potential reentrancy attack patterns

patterns:
  - pattern: "call.value"
    before: "balance[msg.sender] -= amount"
    message: "External call before state change"
  
  - pattern: "withdraw"
    missing: "nonReentrant"
    message: "Missing reentrancy guard"

remediation: |
  1. Use checks-effects-interactions pattern
  2. Add ReentrancyGuard from OpenZeppelin
  3. Update state before external calls

cvss: 9.8
references:
  - https://swcregistry.io/docs/SWC-107
  - https://consensys.github.io/smart-contract-best-practices/

🚀 Features

1. Template Library (40+ Pre-Built Templates)

Category	Templates	Examples
SWC (Smart Contract Weakness)	20+	Reentrancy, Access Control, Integer Overflow
DeFi Vulnerabilities	10+	Flash Loan Attacks, Oracle Manipulation, Price Manipulation
Smart Contract Patterns	10+	Initialization Issues, Upgrade Patterns, Gas Optimization
CVE Detection	3+	HTTP-based infrastructure scanning

2. Multi-Platform Integration

N3's template engine integrates seamlessly across the development workflow:

┌─────────────────────────────────────────────┐
│     N3 TEMPLATE-BASED SCANNER CORE          │
│  (YAML Templates + Risk Calculator)         │
└──────────────┬──────────────────────────────┘
               │
      ┌────────┴────────┐
      │  Scan Contract  │
      │  Match Templates│
      │  Calculate Risk │
      └────────┬────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌───▼───┐  ┌──▼────┐
│  CLI  │  │Hardhat│  │  MCP  │
│Scanner│  │Plugin │  │Server │
└───┬───┘  └───┬───┘  └───┬───┘
    │          │          │
    │      ┌───▼───┐      │
    │      │ Build │      │
    │      │ Time  │      │
    │      └───────┘      │
    │                     │
┌───▼─────────────────────▼───┐
│   Blockscout Widget Display │
│   + Envio Real-Time Index   │
└─────────────────────────────┘

📦 Architecture

N3/
├── packages/
│   ├── core/                 #  TEMPLATE ENGINE (Core)
│   │   ├── templates/        #    40+ YAML templates
│   │   │   ├── SWC/         #    Smart Contract Weakness
│   │   │   ├── defi/        #    DeFi attack patterns
│   │   │   └── smart-contract/  # General patterns
│   │   ├── src/
│   │   │   ├── engine.ts    #    Template matching engine
│   │   │   ├── parser.ts    #    YAML template parser
│   │   │   └── risk-calculator.ts # CVSS-based scoring
│   │   └── cve-templates/   #    CVE definitions
│   │
│   ├── cli/                  #  Command-line scanner
│   ├── hardhat-plugin/       #  Hardhat 3 integration
│   ├── mcp-server/           #  AI Model Context Protocol
│   ├── blockscout-widget/    #  Explorer visualization
│   └── envio-indexer/        #  Real-time event indexing
│
├── contracts/
│   └── N3SecurityOracle.sol  # On-chain scan result storage
│
└── scripts/
    └── deploy-oracle.js      # Contract deployment

🛠️ Technology Stack

Component	Technology	Version	Purpose
Smart Contracts	Hardhat	3.0.9	Development & deployment
Indexing	Envio HyperIndex	2.31.0	Event monitoring
AI Integration	Blockscout SDK	1.20.2	AI-powered analysis
Explorer	Blockscout	API + Widget	Block explorer integration
Database	PostgreSQL	17.5	Event storage
API	Hasura GraphQL	2.43.0	Query interface
Runtime	Node.js	22.21.0	JavaScript execution
Package Manager	pnpm	10.19.0	Monorepo management

🔧 Installation

Prerequisites

IMPORTANT: Hardhat 3.x requires Node.js 22.10.0 or later. Node.js 20.x is not compatible.

# Install Node.js 22 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify version
node --version  # Should be 22.10.0 or higher

Other requirements:

pnpm 10.x or npm 10.x
Docker & Docker Compose (for Envio)
PostgreSQL 17+ (or use Docker)

Quick Start

# Clone repository
git clone https://github.com/intelligent-ears/N3.git
cd N3

# Install dependencies
pnpm install

# Build all packages
pnpm run build

📚 Usage

1. CLI Scanner

# Scan a single contract
n3 scan contracts/MyContract.sol

# Scan with specific templates
n3 scan MyContract.sol --template reentrancy-001

# Generate detailed report
n3 scan MyContract.sol --format html --output report.html

# Scan with severity filter
n3 scan MyContract.sol --severity critical,high

2. Hardhat Plugin

// hardhat.config.js
require('@n3-security/hardhat-plugin');

module.exports = {
  solidity: "0.8.20",
  n3: {
    templates: './n3-templates',
    severity: ['critical', 'high', 'medium'],
    failOnCritical: true,
    reportFormat: 'json'
  }
};

# Run security scan
npx hardhat scan

# Run comprehensive audit
npx hardhat audit

# Generate security tests
npx hardhat test:generate

# Check template coverage
npx hardhat coverage:security

3. MCP Server (AI Integration)

# Start MCP server
node mcp-blockscout-server.mjs

# The server runs on http://localhost:3000
# AI assistants can query: /api/analyze

Example API call:

curl -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "chain": "ethereum"
  }'

4. Envio Indexer (Real-time Monitoring)

# Navigate to indexer
cd packages/envio-indexer

# Start Envio development server
envio dev

# Access Hasura console at http://localhost:8080
# GraphQL endpoint: http://localhost:8080/v1/graphql

Query vulnerability events:

query GetVulnerabilities {
  VulnerabilityEvent(
    where: { severity: { _eq: "CRITICAL" } }
    order_by: { detectedAt: desc }
  ) {
    id
    contractAddress
    vulnerabilityType
    severity
    detectedAt
  }
}

🧪 Example Output

CLI Scan Results

🔍 Scanning VulnerableBank.sol...

📊 Found 7 vulnerabilities

🔥 Risk Score: 87.35/100 (CRITICAL)

✅ Templates: reentrancy, access-control, math, oracle, flash-loan

🔴 Critical: 2 issues
  - Reentrancy vulnerability in withdraw()
  - Unprotected initialization function

🟠 High: 2 issues
  - Integer overflow in calculateReward()
  - Missing access control on admin functions

🟡 Medium: 3 issues
  - Unchecked external call return value
  - Block timestamp dependency
  - Gas optimization needed

✅ Scan completed in 234ms

Hardhat Integration Output

Compiling contracts...
✓ Compiled 3 contracts

Running N3 Security Scan...
✓ Scanned 3 contracts with 40 templates

SecurityToken.sol: ✅ PASSED (Risk: 15/100)
VulnerableBank.sol: ❌ FAILED (Risk: 87/100)
  - 2 CRITICAL issues found
  - Build stopped (failOnCritical: true)

Error: Security scan failed. Fix critical issues before deployment.

🎯 Template Coverage

N3 includes comprehensive template coverage across multiple categories:

Smart Contract Weaknesses (SWC)

SWC-101: Integer Overflow/Underflow
SWC-107: Reentrancy
SWC-115: Authorization through tx.origin
SWC-116: Timestamp Dependence
SWC-120: Weak Sources of Randomness
SWC-134: Message call with hardcoded gas
... and 15+ more

DeFi Attack Patterns

Flash Loan Attacks
Oracle Manipulation
Price Manipulation
Front-running vulnerabilities
Sandwich attacks
MEV exploitation
... and more

General Smart Contract Issues

Uninitialized storage pointers
Delegate call issues
Selfdestruct vulnerabilities
Gas optimization patterns
Upgrade pattern violations

📊 Risk Scoring

N3 uses a CVSS-inspired risk calculation methodology:

Risk Score = Σ (Template_Match_Score × Severity_Weight)

Severity Weights:
- CRITICAL: 10.0
- HIGH:     7.5
- MEDIUM:   5.0
- LOW:      2.5
- INFO:     1.0

Risk Levels:

🟢 0-30: LOW - Minor issues, safe to deploy
🟡 31-60: MEDIUM - Review recommended
🟠 61-80: HIGH - Fix before deployment
🔴 81-100: CRITICAL - Do not deploy

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Adding New Templates

Create a YAML file in packages/core/templates/
Follow the template schema (see examples)
Test with sample vulnerable contracts
Submit a PR with test cases

Template Schema

id: unique-identifier
name: Human-readable name
severity: CRITICAL|HIGH|MEDIUM|LOW|INFO
category: smart-contract|defi|infrastructure
description: What this template detects

patterns:
  - pattern: "regex or string to match"
    context: "where to look (optional)"
    message: "Issue description"

remediation: |
  Step-by-step fix instructions

cvss: 0.0-10.0
references:
  - https://relevant-documentation.com

📖 Documentation

Quick Reference - Essential commands and workflows
Integration Guide - Platform integrations (1006 lines)
Architecture - System design and components

📄 License

MIT License - see LICENSE for details

🔗 Links

Repository: https://github.com/intelligent-ears/N3
Documentation: See DOCUMENTATION_INDEX.md
Templates: packages/core/templates/
Examples: examples/

🙏 Acknowledgments

Inspired by Nuclei by ProjectDiscovery
Built with Hardhat, Envio, and Blockscout
Smart contract security patterns from SWC Registry

N3: Securing Web3, Templates for security 🛡️

Name		Name	Last commit message	Last commit date
bin		bin
contracts		contracts
examples		examples
packages		packages
scripts		scripts
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc.js		.prettierrc.js
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
ENVIO_FLOWCHART.md		ENVIO_FLOWCHART.md
ENVIO_MANUAL_SETUP.md		ENVIO_MANUAL_SETUP.md
ENVIO_QUERIES.md		ENVIO_QUERIES.md
INTEGRATION_GUIDE.md		INTEGRATION_GUIDE.md
LICENSE		LICENSE
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
hardhat.config.js		hardhat.config.js
mcp-blockscout-server.mjs		mcp-blockscout-server.mjs
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Latest commit

History

Folders and files

Repository files navigation