completed allowance abuse scanner example

[buggythanos]

Description

Adds an Allowance Abuse Scanner for BNB Smart Chain (BSC) to detect risky ERC-20 token allowances. Scans wallet addresses to identify excessive or dangerous token permissions that could expose assets.

The scanner evaluates allowances using a multi-tier risk assessment system:

• CRITICAL: Infinite or near-infinite allowances (MAX_UINT256)
• HIGH: Allowances significantly exceeding balance (>100x) or very large absolute values (>1M tokens)
• MEDIUM: Allowances exceeding balance or significant allowances to contract addresses
• LOW: Allowances within reasonable limits

Features:

• Web UI with dark mode
• CLI mode for programmatic usage
• Support for common BSC tokens (USDT, BUSD, USDC, ETH, BTCB, CAKE, DAI)
• Custom spender address checking
• Risk assessment with detailed explanations
• Summary statistics and detailed allowance cards
• Express server for serving the web interface

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 test suite with 24 unit tests covering:

1. Provider initialization: Tests for BSC provider creation with default and custom RPC URLs
2. Contract detection: Tests for identifying contract addresses vs EOA addresses
3. Token information retrieval: Tests for fetching token symbol, name, and decimals with error handling
4. Risk level calculation: Tests for all risk levels (CRITICAL, HIGH, MEDIUM, LOW) including:
   • Infinite allowance detection
   • Near-infinite allowance detection
   • Allowance-to-balance ratio analysis
   • Large absolute value detection
   • Contract spender identification
5. Allowance scanning logic: Tests for:
   • Scanning allowances with custom spenders
   • Filtering zero allowances
   • Handling token errors gracefully
   • Calculating risk counts correctly
   • Address normalization

Test execution:

npm test

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

Manual testing:

• Web UI tested by opening index.html in browser and scanning various wallet addresses
• CLI mode tested with different owner addresses and custom spender addresses
• Server mode tested by running npm start and accessing the web interface

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, and configuration details
• Includes setup.sh script for one-command installation and setup
• Includes env.template for environment variable configuration
• TypeScript implementation with full type safety
• Uses ethers.js v6 for blockchain interactions
• Modern, responsive web UI with dark mode styling