N3

Problem Statement

N3: Nuclei for Web3 - Comprehensive Template based Security Scanner for Smart Contracts & DApps Detailed DescriptionN3 (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:Core Security Engine:Parses and processes security templates written in YAML formatExecutes pattern matching against smart contract codeCalculates risk scores based on detected vulnerabilitiesProvides severity classification (Critical, High, Medium, Low, Info)Supports multiple categories of vulnerabilities (smart-contract, defi, token, nft)Command-Line Interface (CLI):Nuclei-style interface for scanning contracts and infrastructureSupport for multiple output formats (JSON, Markdown, HTML, terminal)Colored and structured output with emoji indicators for severityFiltering by severity and template categoryDebug mode with verbose loggingHardhat Plugin IntegrationDirect integration with the popular Hardhat development frameworkCustom Hardhat tasks for security scanning, testing, and auditingAuto-generation of test cases from detected vulnerabilitiesSecurity coverage analysis to measure template coverageComprehensive audit report generationCVE ScannerHTTP-based vulnerability detection for blockchain infrastructureTemplates for detecting common vulnerabilities and exposuresMultiple matcher types: word matching, regex matching, status code matching, DSL expressionsCustomizable DSL for advanced detection logicSupport for scanning deployed infrastructureTemplate SystemYAML-based definition of security vulnerabilitiesPattern matching for code analysisRisk calculation with modifiers for specific conditionsRemediation suggestionsCategorization by severity and vulnerability typeUse CasesSmart Contract DevelopmentScan contracts during development to catch vulnerabilities earlyGenerate comprehensive security reportsAutomatically create test cases for detected issuesTrack security coverage throughout the development processSecurity AuditingPerform initial automated audits before manual reviewGenerate audit reports in multiple formatsTrack security metrics and risk scoresIdentify common security patterns that need attentionContinuous Integration/Continuous DeploymentIntegrate security scanning into CI/CD pipelinesSet severity thresholds for buildsGenerate artifacts like security reportsTrack security metrics over timeInfrastructure SecurityScan deployed blockchain infrastructure for CVEsDetect common exposures like leaked private keysMonitor for security issues in public-facing componentsCreate custom templates for organization-specific security checksTechnical Implementation N3 is built as a monorepo with several packages:Core Package:Implements the security scanning engineHandles template parsing and pattern matchingCalculates risk scores and generates detailed reportsWritten in TypeScript for type safety and modern language featuresCLI Package:Provides command-line interfaceHandles user input, flags, and command processingFormats output for terminal displayManages file handling and output generationHardhat Plugin Package:Integrates with Hardhat's task systemProvides custom tasks for security scanningHandles test generation and executionManages report formatting for Hardhat usersTemplatesCollection of YAML files defining security patternsOrganized by category (smart-contract, defi, etc.)Includes severity, pattern definitions, remediation stepsCan be extended by users with custom templatesKey DifferentiatorsTemplate-Based Architecture:Unlike most blockchain security tools that use hardcoded rules, N3 uses flexible templatesCommunity can contribute and extend the template libraryOrganizations can create private templates for proprietary checksComprehensive CoverageCovers smart contract vulnerabilitiesIncludes DeFi-specific security issuesSupports infrastructure scanningAdaptable to new blockchain platforms and languagesDeveloper ExperienceIntegration with existing developer workflows (Hardhat)Multiple output formats for different use casesClear, actionable remediation suggestionsVisual reports with risk scoringAdvanced FeaturesCVE scanning for infrastructureTest generation from detected vulnerabilitiesCoverage analysis for security templatesRisk scoring with multiple factorsTarget AudienceSmart Contract Developers:Need to check security during developmentWant integration with existing toolsLooking for actionable remediation adviceSecurity Researchers:Want to create and share custom detection templatesNeed flexible pattern matching capabilitiesInterested in contributing to security standardsAudit Firms:Need preliminary automated scanning toolsWant to generate professional reportsLooking to track security metrics across projectsDeFi Projects:Need specialized security checks for DeFi patternsWant continuous monitoring of deployed contractsNeed infrastructure scanning capabilitiesCurrent 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 patternsEnhanced reporting with interactive dashboardsBlockchain-specific security rules for various platformsMachine learning integration for pattern detectionIntegration with additional development frameworksSummary: 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.

Solution

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 StackTypeScript & Node.jsThe entire codebase is written in TypeScript for type safety and better developer experienceNode.js provides the runtime environment, allowing for cross-platform compatibilityTypeScript interfaces ensure consistent data structures across the scannerYAML for TemplatesAll security templates are defined in YAML formatYAML was chosen for its readability and ease of creation by security researchersThe js-yaml library handles parsing with strict validationCommand Line Interface (CLI)Built using Commander.js for argument parsing and command structureChalk and Ora libraries provide beautiful terminal output with colors and spinnersCustom formatting logic creates structured reports in the terminalPattern Matching EngineCustom pattern matching engine for Solidity code analysisRegular expressions for basic pattern detectionAdvanced parser for more complex vulnerability patternsRisk Calculation SystemSophisticated algorithm for calculating risk scoresBase scores modified by context-specific factorsSeverity classification based on industry standardsHardhat IntegrationCustom Hardhat plugin architectureTask system integration for seamless developer experienceTest generation using Hardhat's testing frameworkCVE ScannerHTTP-based scanning using AxiosMultiple matcher types (word, regex, status, DSL)Custom DSL (Domain Specific Language) for complex matching logicReport GenerationMultiple output formats (JSON, Markdown, HTML)Custom templating for HTML reportsIntegration with CI/CD systemsSystem 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.mdLegend: ✅ Complete | ⏳ In Progress | 🔜 PlannedDevelopment Approach Modular Design. We built N3 with modularity in mind, ensuring each component has a single responsibility:Core Engine: Handles the fundamental scanning logic 2.Template System: Manages security pattern definitionsCLI: Provides user interface and command processingHardhat Plugin: Integrates with development workflowsReport Generation: Creates formatted output for different needsThis modular approach allows for:Independent evolution of componentsEasier testing and maintenanceFlexibility in deployment scenariosBetter separation of concernsNotable Technical Challenges and how N3 solves itSmart 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 patternsContext-aware pattern matching for complex casesMulti-line pattern detection with state trackingFallback mechanisms for edge casesRisk Calculation AlgorithmCreating an accurate risk scoring system required balancing multiple factors:Base severity of vulnerability typesContext-specific modifiersPresence of mitigating factorsCompound risk from multiple vulnerabilities We developed a weighted algorithm that considers all these factors to produce a meaningful risk score between 0-10.Template Validation To ensure templates are valid and work correctly, we implemented:Schema validation for all templatesRuntime pattern testingPerformance optimization for pattern matchingValidation of remediation adviceCVE Scanning DSL For the CVE scanner, we implemented a custom Domain Specific Language (DSL) inspired by Nuclei:Expression evaluation engineFunction support (contains(), status_code, len())Variable substitution ({{BaseURL}})Matcher combination logic (AND/OR conditions)Integration with Partner TechnologiesHardhat Integration: The integration with Hardhat significantly enhances the developer experience:Task System: We leverage Hardhat's task system to provide custom commandsConfiguration: N3 respects Hardhat configuration patternsTesting Framework: Auto-generated tests use Hardhat's testing capabilitiesNetwork Integration: Security tests can interact with deployed contractsBlockscout Integration: Our integration with Blockscout's explorer platform adds powerful capabilities:Verified Contract Analysis: Direct access to verified contract source code across multiple chainsReact Widget: We built a custom React widget for embedding N3 security analytics directly in Blockscout's UIMulti-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 analyticsSecurity Visualization: Custom visualization components for security findings within the explorer interfaceEnvio Integration: Leveraging Envio's HyperIndex and HyperSync capabilities significantly enhances our security monitoring:Historical Security Analysis: Query comprehensive security scan history from Envio's HyperIndexReal-time Monitoring: Register contracts for security monitoring via HyperSync with webhook notificationsEnhanced Vulnerability Detection: Access to indexed vulnerability event data for deeper insightsMulti-chain Data Aggregation: Combine security data across multiple chains via Envio's indexing infrastructureFallback Mechanisms: Smart fallback to local analysis when Envio data is unavailableDevelopment Process Test-Driven Development We followed a test-driven approach:Create test cases for vulnerability patternsDevelop template definitionsImplement detection logicVerify against test casesIterate and refineProgressive EnhancementThe project was built in phases:Core scanning engine for basic pattern detectionCLI interface for user interactionTemplate system for vulnerability definitionsHardhat integration for developer workflowsCVE scanning for infrastructure securityAdvanced reporting and visualizationFuture Technical DirectionsAs we continue to develop N3, we're exploring:WebAssembly compilation for improved performanceMachine learning for pattern detection enhancementsDistributed scanning for large repositoriesReal-time monitoring integrationBlockchain-specific optimizations for different platformsConclusion: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.