/contract-bots-gang

Primary LanguageTypeScript

✨ Contract Bots Gang ✨

A collection of Forta detection bots 🤖 to automatically analyze, inspect, and detect bugs on newly deployed contracts. The repo contains subdirectories, one for each bot. The entire design is meant to be in three layers:

Live bots

bots that scan newly deployed contracts, run inspections on the bytecode and spit out organized info to be processed later (function signatures, events, etc..). A first attempt is the ContractDeconstruct bot that you can find LIVE here. Take a look at alerts metadata to get an idea of what it spits out. Otherwise you can read the README. The bot uses 4byte.directory database as a lookup table. There are some scripts to run manually to sync up with latest database updates. If you want to know how to sync latest signatures, read here.

  • 🕵️‍♂️ Detector bots:

bots that use ContractDeconstruct to run automatic detection of the type of contract, interfaces supported or patterns used. A first attempt I've done is an InterfaceDetector which is able to detect ERC20 and ERC721 tokens, TransparentUpgradeable or UUPS proxies, Ownable or AccessControl contracts and even ProxyAdmin contracts. You can find the bot LIVE here and you can read the README on the repo. You want to add your own interface or contract type detection ? read here how to do it.

  • 💥 [WIP] Hunter bots:

bots that will be using output from detectors and deconstructors to run simulations in a mainnet fork of potential attacks and vulnerabilities exploit. If positive bots will raise alerts.

⚒️ Deconstructors

ContractDeconstruct bot

This is the main bot that detects new contract deployments and spits out the following output into the fired alert's data.

{
    name: `CI-XXX`, // XXX Is the Unix timestamp.
    description: `Contract inspection ${contractAddressFromReceipt}`, // Here we put the contract address
    alertId: `CI-XXX`, // XXX Is the Unix timestamp.
    severity: FindingSeverity.Info,
    type: FindingType.Info,
    metadata: {
        transaction: // transaction.hash,
        contractAddress: // Contract address provided by the transaction receipt.
        functions: // list of functions signatures that matched with 4byte directory. Their text string is provided.
        unknownFunctions: //list of functions signatures that didn't match with 4byte directory.
        events: // list of event signatures that matched with 4byte directory. Their text string is provided.
        unknownEvents: // list of event signatures that didn't match with 4byte directory.
        bytecode: // The deployed bytecode (without init code).
        disassembled: // List of opcodes and their eventual values.
        //analysis: // [CURRENTLY COMMMENTED OUT] Output of Yasold tool.
    }
}

🕵️‍♂️ Detectors

InterfaceDetector bot

This bot takes contract-deconstruct bot output (it reads fired alerts) and uses them to automatically detect if the newly deployed contract adheres to some known interfaces.

About the new contract deployed it detects:

  • If it is an Ownable contract
  • If it adheres to ERC20 interface
  • If it adheres to ERC721 interface
  • If it is an AccessControl contract
  • If it has upgradebility contract by exposing upgradeTo and upgradeToAndCall functions. This can be either a proxy (either ERC1967 or not) or an UUPS implementation contract.
  • If it is an UUPS implementation logic contract
  • If it adheres to ERC1967 interface
  • If it is a TransparentUpgradeableProxy contract
  • If it is a ProxyAdmin contract

Read here on how to add more supported interfaces.

The current output is an alert of the form

{
  "name": "XXX interface detected", // XXX is the interface name detected
  "description": "Contract XXX adheres YYY interface", // XXX is contract address, YYY the detected interface
  "alertId": "XXX interface detected", // XXX is the interface name detected
  "protocol": "ethereum",
  "severity": "Info",
  "type": "Info",
  "metadata": {
    "contractAddress": , // the contract address
    "overallConfidence": , // confidence level, many function signatures can correspond to different actual functions
    "extras": "{}" // extra fields
  }
}

💥 Hunters