{"id":29089708,"url":"https://github.com/openzeppelin/contract-bots-gang","last_synced_at":"2025-06-28T04:04:35.581Z","repository":{"id":45318768,"uuid":"513497082","full_name":"OpenZeppelin/contract-bots-gang","owner":"OpenZeppelin","description":null,"archived":false,"fork":false,"pushed_at":"2023-03-09T14:55:37.000Z","size":22861,"stargazers_count":66,"open_issues_count":7,"forks_count":29,"subscribers_count":8,"default_branch":"master","last_synced_at":"2023-04-09T18:37:51.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenZeppelin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-13T11:37:38.000Z","updated_at":"2023-03-30T07:59:19.000Z","dependencies_parsed_at":"2023-02-08T07:31:43.493Z","dependency_job_id":null,"html_url":"https://github.com/OpenZeppelin/contract-bots-gang","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/OpenZeppelin/contract-bots-gang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fcontract-bots-gang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fcontract-bots-gang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fcontract-bots-gang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fcontract-bots-gang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenZeppelin","download_url":"https://codeload.github.com/OpenZeppelin/contract-bots-gang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenZeppelin%2Fcontract-bots-gang/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262371683,"owners_count":23300595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-28T04:04:26.681Z","updated_at":"2025-06-28T04:04:35.561Z","avatar_url":"https://github.com/OpenZeppelin.png","language":"TypeScript","readme":"# :sparkles: Contract Bots Gang :sparkles: \n\nA collection of [Forta detection bots](https://docs.forta.network/en/latest/quickstart/) :robot: 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:\n\nLive bots\n- [`ContractDeconstruct`](https://explorer.forta.network/agent/0x9703bb3bf08bc89e6d0fd273fa995c32f75e8998c314bafdafcfe2491678f083)\n- [`InterfaceDetector`](https://explorer.forta.network/agent/0xf75be156b17977784d5f4bfd7a2d3b06f412b7cb6bb71fdf79a75725bf7b01e9)\n\n- :hammer_and_pick: **Deconstruct bots**: \n\nbots 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](https://explorer.forta.network/agent/0x9703bb3bf08bc89e6d0fd273fa995c32f75e8998c314bafdafcfe2491678f083). Take a look at alerts `metadata` to get an idea of what it spits out. Otherwise you can read the [README](https://github.com/OpenZeppelin/contract-bots-gang/tree/master/contract-deconstruct#contractdeconstruct). The bot uses [4byte.directory](https://www.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](https://github.com/OpenZeppelin/contract-bots-gang/tree/master/contract-deconstruct#sync-with-4byte-directory).\n\n- :male_detective: **Detector bots**: \n\nbots 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](https://explorer.forta.network/agent/0xf75be156b17977784d5f4bfd7a2d3b06f412b7cb6bb71fdf79a75725bf7b01e9) and you can read the [README]() on the repo. You want to add your own interface or contract type detection ? read [here](https://github.com/OpenZeppelin/contract-bots-gang/tree/master/interface-detector#interface-detector) how to do it.\n\n- :boom: **[WIP] Hunter bots**: \n\nbots 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.\n\n## :hammer_and_pick: Deconstructors\n\n### `ContractDeconstruct` bot\n\nThis is the main bot that detects new contract deployments and spits out the following output into the fired alert's data.\n\n```\n{\n    name: `CI-XXX`, // XXX Is the Unix timestamp.\n    description: `Contract inspection ${contractAddressFromReceipt}`, // Here we put the contract address\n    alertId: `CI-XXX`, // XXX Is the Unix timestamp.\n    severity: FindingSeverity.Info,\n    type: FindingType.Info,\n    metadata: {\n        transaction: // transaction.hash,\n        contractAddress: // Contract address provided by the transaction receipt.\n        functions: // list of functions signatures that matched with 4byte directory. Their text string is provided.\n        unknownFunctions: //list of functions signatures that didn't match with 4byte directory.\n        events: // list of event signatures that matched with 4byte directory. Their text string is provided.\n        unknownEvents: // list of event signatures that didn't match with 4byte directory.\n        bytecode: // The deployed bytecode (without init code).\n        disassembled: // List of opcodes and their eventual values.\n        //analysis: // [CURRENTLY COMMMENTED OUT] Output of Yasold tool.\n    }\n}\n```\n\n## :male_detective: Detectors\n\n### `InterfaceDetector` bot\n\nThis 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.\n\nAbout the new contract deployed it detects:\n\n- If it is an [Ownable](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/Ownable.sol) contract\n- If it adheres to [ERC20](https://eips.ethereum.org/EIPS/eip-20) interface\n- If it adheres to [ERC721](https://eips.ethereum.org/EIPS/eip-721) interface\n- If it is an [AccessControl](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/AccessControl.sol) contract\n- 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. \n- If it is an [UUPS](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/utils/UUPSUpgradeable.sol) implementation logic contract\n- If it adheres to [ERC1967](https://eips.ethereum.org/EIPS/eip-1967) interface\n- If it is a [TransparentUpgradeableProxy](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) contract \n- If it is a [ProxyAdmin](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/transparent/ProxyAdmin.sol) contract\n\nRead [here](./interface-detector/README.md#how-to-support-more-interfaces) on how to add more supported interfaces.\n\nThe current output is an alert of the form\n\n```\n{\n  \"name\": \"XXX interface detected\", // XXX is the interface name detected\n  \"description\": \"Contract XXX adheres YYY interface\", // XXX is contract address, YYY the detected interface\n  \"alertId\": \"XXX interface detected\", // XXX is the interface name detected\n  \"protocol\": \"ethereum\",\n  \"severity\": \"Info\",\n  \"type\": \"Info\",\n  \"metadata\": {\n    \"contractAddress\": , // the contract address\n    \"overallConfidence\": , // confidence level, many function signatures can correspond to different actual functions\n    \"extras\": \"{}\" // extra fields\n  }\n}\n```\n\n## :boom: Hunters\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fcontract-bots-gang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzeppelin%2Fcontract-bots-gang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzeppelin%2Fcontract-bots-gang/lists"}