N3

N3: Nuclei for Web3 - Comprehensive Template based Security Scanner for Smart Contracts & DApps Detailed Description

N3 (Nuclei for Web3) is an advanced security scanning platform specifically designed for blockchain applications, smart contracts, and decentralized applications (DApps). Taking inspiration from ProjectDiscovery's Nuclei vulnerability scanner, N3 brings the power of template-based vulnerability detection to the Web3 ecosystem.

Core Concept: The fundamental concept of N3 is to provide a template-based approach to security scanning rather than hardcoded rules. This allows for much greater flexibility, extensibility, and community contributions. Security researchers and developers can create custom YAML templates that define patterns to detect specific vulnerabilities, making it easy to continually expand the scanner's capabilities as new threats emerge.

Primary Components:

1. Core Security Engine:

• Parses and processes security templates written in YAML format
• Executes pattern matching against smart contract code
• Calculates risk scores based on detected vulnerabilities
• Provides severity classification (Critical, High, Medium, Low, Info)
• Supports multiple categories of vulnerabilities (smart-contract, defi, token, nft)

1. Command-Line Interface (CLI):

• Nuclei-style interface for scanning contracts and infrastructure
• Support for multiple output formats (JSON, Markdown, HTML, terminal)
• Colored and structured output with emoji indicators for severity
• Filtering by severity and template category
• Debug mode with verbose logging

1. Hardhat Plugin Integration

• Direct integration with the popular Hardhat development framework
• Custom Hardhat tasks for security scanning, testing, and auditing
• Auto-generation of test cases from detected vulnerabilities
• Security coverage analysis to measure template coverage
• Comprehensive audit report generation

1. CVE Scanner

• HTTP-based vulnerability detection for blockchain infrastructure
• Templates for detecting common vulnerabilities and exposures
• Multiple matcher types: word matching, regex matching, status code matching, DSL expressions
• Customizable DSL for advanced detection logic
• Support for scanning deployed infrastructure

1. Template System

• YAML-based definition of security vulnerabilities
• Pattern matching for code analysis
• Risk calculation with modifiers for specific conditions
• Remediation suggestions
• Categorization by severity and vulnerability type

Use Cases

1. Smart Contract Development

• Scan contracts during development to catch vulnerabilities early
• Generate comprehensive security reports
• Automatically create test cases for detected issues
• Track security coverage throughout the development process

1. Security Auditing

• Perform initial automated audits before manual review
• Generate audit reports in multiple formats
• Track security metrics and risk scores
• Identify common security patterns that need attention

1. Continuous Integration/Continuous Deployment

• Integrate security scanning into CI/CD pipelines
• Set severity thresholds for builds
• Generate artifacts like security reports
• Track security metrics over time

1. Infrastructure Security

• Scan deployed blockchain infrastructure for CVEs
• Detect common exposures like leaked private keys
• Monitor for security issues in public-facing components
• Create custom templates for organization-specific security checks

Technical Implementation N3 is built as a monorepo with several packages:

1. Core Package:

• Implements the security scanning engine
• Handles template parsing and pattern matching
• Calculates risk scores and generates detailed reports
• Written in TypeScript for type safety and modern language features

1. CLI Package:

• Provides command-line interface
• Handles user input, flags, and command processing
• Formats output for terminal display
• Manages file handling and output generation

1. Hardhat Plugin Package:

• Integrates with Hardhat's task system
• Provides custom tasks for security scanning
• Handles test generation and execution
• Manages report formatting for Hardhat users

1. Templates

• Collection of YAML files defining security patterns
• Organized by category (smart-contract, defi, etc.)
• Includes severity, pattern definitions, remediation steps
• Can be extended by users with custom templates

Key Differentiators

1. Template-Based Architecture:

• Unlike most blockchain security tools that use hardcoded rules, N3 uses flexible templates
• Community can contribute and extend the template library
• Organizations can create private templates for proprietary checks

1. Comprehensive Coverage

• Covers smart contract vulnerabilities
• Includes DeFi-specific security issues
• Supports infrastructure scanning
• Adaptable to new blockchain platforms and languages

1. Developer Experience

• Integration with existing developer workflows (Hardhat)
• Multiple output formats for different use cases
• Clear, actionable remediation suggestions
• Visual reports with risk scoring

1. Advanced Features

• CVE scanning for infrastructure
• Test generation from detected vulnerabilities
• Coverage analysis for security templates
• Risk scoring with multiple factors

Target Audience

1. Smart Contract Developers:

• Need to check security during development
• Want integration with existing tools
• Looking for actionable remediation advice

1. Security Researchers:

• Want to create and share custom detection templates
• Need flexible pattern matching capabilities
• Interested in contributing to security standards

1. Audit Firms:

• Need preliminary automated scanning tools
• Want to generate professional reports
• Looking to track security metrics across projects

1. DeFi Projects:

• Need specialized security checks for DeFi patterns
• Want continuous monitoring of deployed contracts
• Need infrastructure scanning capabilities

Current Status and Roadmap: The project is fully operational with the core security scanner, CLI, Hardhat plugin integration, and CVE detection system. Future enhancements planned include:

• Expanded template library with more vulnerability patterns
• Enhanced reporting with interactive dashboards
• Blockchain-specific security rules for various platforms
• Machine learning integration for pattern detection
• Integration with additional development frameworks

Summary: N3 represents a significant advancement in blockchain security tooling by bringing template-based vulnerability scanning to the Web3 ecosystem. It provides a comprehensive security solution for smart contract developers, security researchers, and audit firms, with specialized features for DeFi and NFT projects. With its extensible architecture and integration capabilities, N3 aims to raise the security standard across the blockchain ecosystem and make security scanning an accessible part of every developer's workflow.

N3 was built using a robust stack of modern technologies, carefully integrated to create a comprehensive security scanning platform for Web3. Here's a deep dive into how we built it:

Technology Stack

1. TypeScript & Node.js

• The entire codebase is written in TypeScript for type safety and better developer experience
• Node.js provides the runtime environment, allowing for cross-platform compatibility
• TypeScript interfaces ensure consistent data structures across the scanner

1. YAML for Templates

• All security templates are defined in YAML format
• YAML was chosen for its readability and ease of creation by security researchers
• The js-yaml library handles parsing with strict validation

1. Command Line Interface (CLI)

• Built using Commander.js for argument parsing and command structure
• Chalk and Ora libraries provide beautiful terminal output with colors and spinners
• Custom formatting logic creates structured reports in the terminal

1. Pattern Matching Engine

• Custom pattern matching engine for Solidity code analysis
• Regular expressions for basic pattern detection
• Advanced parser for more complex vulnerability patterns

1. Risk Calculation System

• Sophisticated algorithm for calculating risk scores
• Base scores modified by context-specific factors
• Severity classification based on industry standards

1. Hardhat Integration

• Custom Hardhat plugin architecture
• Task system integration for seamless developer experience
• Test generation using Hardhat's testing framework

1. CVE Scanner

• HTTP-based scanning using Axios
• Multiple matcher types (word, regex, status, DSL)
• Custom DSL (Domain Specific Language) for complex matching logic

1. Report Generation

• Multiple output formats (JSON, Markdown, HTML)
• Custom templating for HTML reports
• Integration with CI/CD systems

System Architecture: N3 is built as a monorepo with several interconnected packages: n3/ ├── bin/ # CLI executable wrappers ✅ │ └── n3 # Main CLI executable
│ ├── packages/ │ ├── core/ # Core security engine ✅ │ │ ├── src/ │ │ │ ├── engine.ts # Main scanning engine │ │ │ ├── parser.ts # Template parser │ │ │ ├── risk-calculator.ts # Risk score calculator │ │ │ ├── types.ts # Core type definitions │ │ │ ├── cve-types.ts # CVE type definitions │ │ │ ├── cve-parser.ts # CVE template parser │ │ │ └── cve-scanner.ts # CVE scanning engine │ │ ├── templates/ # Smart contract templates │ │ │ ├── defi/ │ │ │ │ ├── flash-loan-001.yaml │ │ │ │ └── oracle-001.yaml │ │ │ └── smart-contract/ │ │ │ ├── access-001.yaml │ │ │ ├── math-001.yaml │ │ │ └── reentrancy-001.yaml │ │ └── cve-templates/ # CVE detection templates │ │ ├── CVE-2022-40769.yaml # Profanity vulnerability │ │ ├── CVE-2023-PRIVATE-KEY.yaml │ │ └── CVE-2023-ETHERSCAN.yaml │ │ │ ├── cli/ # Command-line interface ✅ │ │ ├── src/ │ │ │ ├── cli.ts # Main CLI with CVE command │ │ │ └── utils/ │ │ │ ├── logger.ts │ │ │ ├── formatter.ts │ │ │ ├── file-scanner.ts │ │ │ └── template-manager.ts │ │ │ ├── hardhat-plugin/ # Hardhat integration ✅ │ │ ├── src/tasks/ │ │ │ ├── scan.ts # Basic security scanning │ │ │ ├── test.ts # Test generation & execution │ │ │ ├── audit.ts # Comprehensive audit │ │ │ ├── fix.ts # Auto-fix suggestions │ │ │ ├── coverage.ts # Coverage analysis │ │ │ └── monitor.ts # Real-time monitoring │ │ └── TASKS.md # Task documentation │ │ │ ├── mcp-server/ # MCP server with Blockscout integration ✅ │ │ ├── src/ │ │ │ ├── index.ts # MCP server initialization │ │ │ ├── blockscout-widget.tsx # Blockscout widget component │ │ │ ├── prompts/ │ │ │ │ └── index.js # Security prompts │ │ │ └── tools/ │ │ │ ├── index.ts # Core security tools │ │ │ ├── blockscout-adapter.ts # Blockscout API adapter │ │ └── envio-adapter.ts # Envio API adapter │ │ ├── package.json │ │ └── tsconfig.json │ │ │ ├── blockscout-widget/ # Blockscout explorer widget ✅ │ │ └── src/ │ │ └── widget.tsx # Embeddable security widget │ │ │ └── envio-indexer/ # Envio indexer ✅ │ ├── config.yaml # Indexer configuration │ ├── schema.graphql # GraphQL schema │ └── src/ │ ├── generated.ts # Generated code │ └── handlers/ │ └── security-events.ts # Security event handlers │ ├── examples/ │ └── vulnerable-contracts/ │ ├── SecureBank.sol │ └── VulnerableBank.sol │ ├── scripts/ # Utility scripts │ └── bootstrap.sh # Setup script │ ├── CVE_FEATURE_SUMMARY.md # CVE feature documentation ├── CVE_TESTING.md # CVE scanner testing guide └── README.md

Legend: ✅ Complete | ⏳ In Progress | 🔜 Planned

Development Approach Modular Design. We built N3 with modularity in mind, ensuring each component has a single responsibility:

1. Core Engine: Handles the fundamental scanning logic 2.Template System: Manages security pattern definitions
2. CLI: Provides user interface and command processing
3. Hardhat Plugin: Integrates with development workflows
4. Report Generation: Creates formatted output for different needs

This modular approach allows for:

1. Independent evolution of components
2. Easier testing and maintenance
3. Flexibility in deployment scenarios
4. Better separation of concerns

Notable Technical Challenges and how N3 solves it

1. Smart Contract Pattern Matching: One of the most challenging aspects was developing a reliable pattern matching system for Solidity code. Rather than building a full AST parser, we created a hybrid approach:

• Regular expressions for simpler patterns
• Context-aware pattern matching for complex cases
• Multi-line pattern detection with state tracking
• Fallback mechanisms for edge cases
• Risk Calculation Algorithm

1. Creating an accurate risk scoring system required balancing multiple factors:

• Base severity of vulnerability types
• Context-specific modifiers
• Presence of mitigating factors
• Compound risk from multiple vulnerabilities We developed a weighted algorithm that considers all these factors to produce a meaningful risk score between 0-10.

1. Template Validation To ensure templates are valid and work correctly, we implemented:

• Schema validation for all templates
• Runtime pattern testing
• Performance optimization for pattern matching
• Validation of remediation advice

1. CVE Scanning DSL For the CVE scanner, we implemented a custom Domain Specific Language (DSL) inspired by Nuclei:

• Expression evaluation engine
• Function support (contains(), status_code, len())
• Variable substitution ({{BaseURL}})
• Matcher combination logic (AND/OR conditions)

Integration with Partner Technologies

Hardhat Integration: The integration with Hardhat significantly enhances the developer experience:

• Task System: We leverage Hardhat's task system to provide custom commands
• Configuration: N3 respects Hardhat configuration patterns
• Testing Framework: Auto-generated tests use Hardhat's testing capabilities
• Network Integration: Security tests can interact with deployed contracts

Blockscout Integration: Our integration with Blockscout's explorer platform adds powerful capabilities:

• Verified Contract Analysis: Direct access to verified contract source code across multiple chains
• React Widget: We built a custom React widget for embedding N3 security analytics directly in Blockscout's UI
• Multi-Chain Support: The integration works across all blockchains supported by Blockscout (Ethereum, Polygon, Arbitrum, Optimism, Base, etc.)
• API Communication: Two-way data exchange between N3 and Blockscout for enhanced security analytics
• Security Visualization: Custom visualization components for security findings within the explorer interface

Envio Integration: Leveraging Envio's HyperIndex and HyperSync capabilities significantly enhances our security monitoring:

• Historical Security Analysis: Query comprehensive security scan history from Envio's HyperIndex
• Real-time Monitoring: Register contracts for security monitoring via HyperSync with webhook notifications
• Enhanced Vulnerability Detection: Access to indexed vulnerability event data for deeper insights
• Multi-chain Data Aggregation: Combine security data across multiple chains via Envio's indexing infrastructure
• Fallback Mechanisms: Smart fallback to local analysis when Envio data is unavailable

Development Process Test-Driven Development We followed a test-driven approach:

• Create test cases for vulnerability patterns
• Develop template definitions
• Implement detection logic
• Verify against test cases
• Iterate and refine
• Progressive Enhancement

The project was built in phases:

• Core scanning engine for basic pattern detection
• CLI interface for user interaction
• Template system for vulnerability definitions
• Hardhat integration for developer workflows
• CVE scanning for infrastructure security
• Advanced reporting and visualization

Future Technical Directions

As we continue to develop N3, we're exploring:

• WebAssembly compilation for improved performance
• Machine learning for pattern detection enhancements
• Distributed scanning for large repositories
• Real-time monitoring integration
• Blockchain-specific optimizations for different platforms

Conclusion:

Building N3 required combining expertise in security, blockchain technologies, and software development. By focusing on a modular architecture, template-based approach, and seamless integration with existing tools, we created a flexible and powerful security scanning platform for the Web3 ecosystem.

The combination of TypeScript, YAML templates, custom pattern matching, and integrations with developer tools like Hardhat makes N3 both powerful and approachable for developers, security researchers, and audit firms working in the blockchain space.