UUPS Checker

A command-line tool to check UUPS and Transparent Proxy initialization status for whitehat security research.

Features

• ✅ Detects UUPS vs Transparent Proxies
• ✅ Checks initialization status of proxy and implementation
• ✅ Shows owner/admin addresses
• ✅ Displays contract balance
• ✅ Supports multiple chains (ETH, BSC, Polygon, Arbitrum, Optimism, opBNB)
• ✅ Color-coded output for easy reading
• ✅ Works on Linux, macOS, and Android (Termux)

Prerequisites

• Foundry (for cast command)
• bc (basic calculator - usually pre-installed)

Installation

Option 1: npm (Recommended)

npm install -g uups-checker

After installation, you can use either command:

ups <contract_address> [chain]
# or
uups-checker <contract_address> [chain]

Option 2: From source

git clone https://github.com/yourusername/uups-checker
cd uups-checker
chmod +x bin/ups
npm link

Termux Installation (Android)

1. Install Termux from F-Droid (NOT Google Play)

2. Update packages and install dependencies:

pkg update && pkg upgrade
pkg install git nodejs bc

3. Install Rust (required for Foundry):

pkg install rust

4. Install Foundry:

curl -L https://foundry.paradigm.xyz | bash
source ~/.bashrc
foundryup

5. Install uups-checker:

npm install -g uups-checker

6. Test it:

ups 0x8599068597fd27D87514CB90c42300c03a474084 bsc

Usage

ups <contract_address> [chain]

Examples

# Check on Ethereum mainnet (default)
ups 0x1234...

# Check on BSC
ups 0x1234... bsc

# Check on Polygon
ups 0x1234... polygon

# Check on opBNB
ups 0x1234... opbnb

# Check on Arbitrum
ups 0x1234... arbitrum

# Check on Optimism
ups 0x1234... optimism

Supported Chains

• eth - Ethereum Mainnet (default)
• bsc - Binance Smart Chain
• opbnb - opBNB
• polygon - Polygon
• arbitrum - Arbitrum
• optimism - Optimism

Output

The tool provides:

• Proxy type (UUPS or Transparent)
• Implementation address
• Owner/Admin address
• Initialization status for BOTH proxy and implementation
• Contract balance
• Vulnerability assessment

Example Output

╔══════════════════════════════════════════╗
║       UUPS INITIALIZATION CHECKER        ║
║          Whitehat Bounty Tool            ║
╚══════════════════════════════════════════╝

[INFO] Checking: 0x8599...
[INFO] Chain: bsc
[INFO] Explorer: https://bscscan.com/address/0x8599...

[1/5] Reading EIP-1967 implementation slot...
[✓] Implementation: 0xd28A...
[2/5] Checking if UUPS proxy...
[✓] UUPS proxy detected!
[3/5] Checking owner/admin...
[✓] Owner/Admin: 0x1234...
[4/5] Checking initialization status...
[✓] Proxy: INITIALIZED
[✓] Implementation: INITIALIZED
[5/5] Checking balance...
[✓] Balance: 0 ETH

═══════════════════════════════════════════
              FINAL VERDICT                
═══════════════════════════════════════════
Proxy Type:      UUPS
Implementation:  0xd28A...
Owner:           0x1234...
Balance:         0 ETH
Status:          ✓ INITIALIZED

[SAFE] Proxy is properly configured

Vulnerable Contract Example

[4/5] Checking initialization status...
[!] Proxy: NOT INITIALIZED
[!] Implementation: NOT INITIALIZED

Status:          ✗ UNINITIALIZED

[VULNERABLE] UUPS implementation is uninitialized!
[EXPLOIT] Potential takeover vulnerability!

Next steps:
1. Try calling initialize() on the implementation
2. Check if you can set yourself as owner
3. Verify with: cast call 0x... "owner()(address)" --rpc-url ...

Troubleshooting

Termux Issues

If you get "command not found" errors:

# Reload your shell
source ~/.bashrc

# Or restart Termux

If Foundry installation fails:

# Make sure Rust is installed
pkg install rust

# Try installing Foundry again
curl -L https://foundry.paradigm.xyz | bash

RPC Issues

If you get RPC errors, the default Infura endpoint might be rate-limited. You can modify the script to use your own RPC endpoints.

Publishing to npm (For Developers)

1. Create a GitHub repository and push your code
2. Update package.json with your GitHub URL
3. Login to npm: npm login
4. Publish: npm publish

Security Notice

This tool is for security research and whitehat bounty hunting only. Always:

• Get proper authorization before testing contracts
• Report vulnerabilities responsibly through official channels (Immunefi, HackerOne, etc.)
• Never exploit vulnerabilities for personal gain
• Follow responsible disclosure practices

How It Works

The tool checks:

1. EIP-1967 implementation slot to detect proxies
2. proxiableUUID() function to identify UUPS proxies
3. Admin slot (0xb53127...) for Transparent Proxies
4. Initialization status by checking storage slot 0 and owner functions
5. Contract balance and ownership

License

MIT

Contributing

Pull requests are welcome! For major changes, please open an issue first.

Author

Created for whitehat security researchers and bug bounty hunters.

Disclaimer

This tool is provided as-is for educational and security research purposes. Use responsibly and ethically.