completed contract surface area analyzer

[buggythanos]

Description

This PR adds a Contract Surface Area Analyzer for BNB Smart Chain (BSC) that evaluates smart contract attack surface and complexity. Understanding a contract's surface area is crucial for security auditing, as it helps identify potential attack vectors and complexity hotspots.

The analyzer examines all ways a contract can be interacted with from the outside, including public/external functions, payable functions, events, and special functions like fallback/receive. It calculates a complexity score and identifies risk factors to help security auditors and developers assess contract security.

Key Features:

• ABI Analysis: Extracts functions, events, and special functions from contract ABIs
• Complexity Scoring: Weighted scoring system based on contract structure (functions, events, payable functions, fallback/receive)
• Risk Factor Identification: Automatically detects potential security concerns
• Proxy Detection: Identifies EIP-1967 proxy patterns and implementation addresses
• Common Contract Support: Built-in ABI templates for ERC20, ERC721, ERC1155, Uniswap V2/V3
• Modern Web UI: Dark mode interface for easy visualization of analysis results
• RESTful API: /api/analyze endpoint for programmatic access
• CLI Support: Command-line interface for batch analysis

Surface Area Components Analyzed:

• Public Functions: Can be called internally and externally
• External Functions: Can only be called from outside the contract
• Payable Functions: Can receive ETH/BNB, increasing financial risk
• Events: Emitted data that can be monitored
• Fallback/Receive Functions: Special functions for handling unexpected calls

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

The implementation includes a comprehensive test suite with 24 unit tests covering:

1. ABI Analysis:

   • Function extraction from ABI
   • Event extraction with indexed parameter detection
   • Fallback function detection
   • Receive function detection
   • Payable function identification
   • Empty ABI handling
   • Invalid ABI graceful error handling

2. Complexity Score Calculation:

   • Base complexity from total functions
   • Weighted scoring for public/external functions
   • Additional points for payable functions
   • Significant points for fallback and receive functions
   • Event inclusion in scoring

3. Risk Factor Identification:

   • High number of public functions detection (>20)
   • High number of external functions detection (>15)
   • Multiple payable functions detection (>5)
   • Fallback function risk identification
   • Receive function risk identification
   • Proxy pattern risk identification
   • Safe contract detection (no significant risks)

4. Common Contract ABI Support:

   • ERC20 ABI template validation
   • ERC721 ABI template validation
   • Uniswap V2 ABI template validation
   • Unknown type handling (returns empty array)

5. Utility Functions:

   • Proxy detection function structure
   • Contract address validation function structure

Test execution:

npm test

All 24 tests pass successfully. The test suite uses Jest with mocked ethers.js providers where needed to ensure reliable, fast test execution without requiring actual blockchain connections.

Manual testing:

• Web UI tested by accessing http://localhost:3000 and analyzing various contract addresses
• API endpoint tested via POST requests to /api/analyze with different contract addresses and types
• CLI mode tested with different contract addresses and contract types (ERC20, ERC721, UNISWAP_V2)
• Server mode tested by running npm start without arguments and accessing the web interface
• Proxy detection tested with known proxy contracts on BSC

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional notes:

• Includes comprehensive README.md with setup instructions, usage examples, API documentation, and key metrics explanation
• Includes setup.sh script for one-command installation and setup
• Includes env.template for environment variable configuration
• TypeScript implementation with full type safety and comprehensive interfaces
• Uses ethers.js v6 for blockchain interactions
• Express server with RESTful API endpoints
• Modern, responsive web UI with dark mode styling
• Graceful error handling for invalid addresses, missing ABIs, and network issues
• Support for common contract types with built-in ABI templates
• EIP-1967 proxy pattern detection for upgradeable contracts

[vivixu-cmd]

Congratulations! You have received a Cookbook reward. Please reply with your BSC wallet address.Thanks

[buggythanos]

Congratulations! You have received a Cookbook reward. Please reply with your BSC wallet address.Thanks

Hi there, thank you!
0x4e5d4a29F7b02c8cf1310D112A42231Bde049180