{"id":22041910,"url":"https://github.com/blocksecteam/hookscan","last_synced_at":"2025-05-08T01:08:35.229Z","repository":{"id":214733543,"uuid":"736149044","full_name":"blocksecteam/hookscan","owner":"blocksecteam","description":"Analyzer for Uniswap v4 Hooks","archived":false,"fork":false,"pushed_at":"2024-03-04T03:59:28.000Z","size":124,"stargazers_count":10,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-08T01:05:43.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blocksecteam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-27T05:49:14.000Z","updated_at":"2025-03-06T16:53:44.000Z","dependencies_parsed_at":"2024-01-07T11:38:06.703Z","dependency_job_id":"20bd6963-c641-4427-a51b-aa964031053d","html_url":"https://github.com/blocksecteam/hookscan","commit_stats":null,"previous_names":["blocksecteam/uniscan","blocksecteam/hookscan"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Fhookscan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Fhookscan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Fhookscan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Fhookscan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blocksecteam","download_url":"https://codeload.github.com/blocksecteam/hookscan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978758,"owners_count":21834915,"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":"2024-11-30T12:10:21.066Z","updated_at":"2025-05-08T01:08:35.176Z","avatar_url":"https://github.com/blocksecteam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HookScan\n\n\u003cimg src=\"./logo.svg\" alt=\"HookScan\" width=\"500\"/\u003e\n\n[![License: AGPL v3](https://img.shields.io/github/license/blocksecteam/hookscan)](LICENSE)\n[![CI Status](https://github.com/blocksecteam/hookscan/actions/workflows/ci.yml/badge.svg)](https://github.com/blocksecteam/hookscan/actions/workflows/ci.yml)\n[![Build-Image Status](https://github.com/blocksecteam/hookscan/actions/workflows/build-image.yml/badge.svg)](https://github.com/blocksecteam/hookscan/actions/workflows/build-image.yml)\n\nHookScan is an automated static analyzer designed specifically for [Uniswap v4](https://blog.uniswap.org/uniswap-v4) hooks.\nIts purpose is to identify the most prevalent and severe vulnerabilities within Uniswap v4 hooks that are susceptible to malicious manipulation. The security model and design of HookScan draw from insights detailed in a series of our published articles:\n\n- [Thorns in the Rose: Exploring Security Risks in Uniswap v4's Novel Hook Mechanism](https://phalcon.xyz/blog/thorns-in-the-rose-exploring-security-risks-in-uniswap-v4-s-novel-hook-mechanism)\n- [Lethal Integration: Vulnerabilities in Hooks Due to Risky Interactions](https://phalcon.xyz/blog/lethal-integration-vulnerabilities-in-hooks-due-to-risky-interactions)\n- Malicious Hooks (TBA)\n\nHookScan is based on a simplified tailored version of **Phalcon Inspector**, a powerful static analysis framework developed by [BlockSec](https://blocksec.com/).\nPhalcon Inspector is still under development and will be open-sourced and announced in the future.\n\n## Get started\n\n### Prerequisite\n\n```bash\nsolc\u003e=0.8.14\npython\u003e=3.8\n\npip install -r requirements.txt\n```\n\n### Usage\n\n```bash\n# [optional] for foundry projects, fetch dependencies before running HookScan\nforge install --root path/to/foundry/project\n\n# simple usage\nPYTHONPATH=path/to/this/repo python -m hookscan path/to/source_file.sol:ContractName\n\n# help\nPYTHONPATH=path/to/this/repo python -m hookscan --help\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003ch3\u003eDocker Support\u003c/h3\u003e\n\u003c/summary\u003e\n\nHookScan provides docker support with python and solc dependency integrated.\n\n```bash\n# build image\ndocker build --tag hookscan .\n\n# pull pre-built image\ndocker pull futuretech6/hookscan\ndocker image tag futuretech6/hookscan hookscan\n\n# run image\ndocker run --rm -it \\\n    -v /path/to/project:/project \\\n    -e SOLC_VERSION=0.8.x \\\n    -e CONTRACT=path/to/source_file.sol:ContractName \\\n    hookscan [--other-flags]\n\n# demo: run image on v4-stoploss (https://github.com/saucepoint/v4-stoploss)\ngit clone https://github.com/saucepoint/v4-stoploss ~/v4-stoploss\nforge install --root ~/v4-stoploss\ndocker run --rm -it \\\n    -v $HOME/v4-stoploss:/project \\\n    -e SOLC_VERSION=0.8.19 \\\n    -e CONTRACT=src/StopLoss.sol:StopLoss \\\n    hookscan\n```\n\n\u003c/details\u003e\n\n## Detector Spec\n\n| **Detector**                               | **Description**                                                                          | **Severity** | **Confidence** |\n| ------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------ | -------------- |\n| [`UniswapPublicHook`][public_hook]         | callers of hook functions are not exclusively\u003cbr /\u003erestricted to the pool manager alone  | High         | High           |\n| [`UniswapPublicCallback`][public_callback] | callers of callback functions are not exclusively\u003cbr /\u003erestricted to the contract itself | High         | High           |\n| [`UniswapUpgradableHook`][upgradable_hook] | the contract `DELEGATECALL`s to mutable addresses                                        | High         | High           |\n| [`UniswapSuicidalHook`][suicidal_hook]     | the contract contains `SELFDESTRUCT`                                                     | Medium       | High           |\n\n## Evaluation\n\nWe've conducted tests on 13 hook contracts associated with Uniswap v4, as listed in the compilation [awesome-uniswap-hook](https://github.com/hyperoracle/awesome-uniswap-hooks), all of which compiled without errors.\nThe test results are as follows:\n\n| **Detector**                               | **TP/ground_truth** |\n| ------------------------------------------ | ------------------- |\n| [`UniswapPublicHook`][public_hook]         | 7/7 contracts       |\n| [`UniswapPublicCallback`][public_callback] | 3/3 contracts       |\n| [`UniswapUpgradableHook`][upgradable_hook] | 0                   |\n| [`UniswapSuicidalHook`][suicidal_hook]     | 0                   |\n\n## Note\n\nHookScan can be integrated into the development process to scan Uniswap v4 hooks. Specifically, it can be used to determine whether these hooks are vulnerable or malicious, using the security models described in our previously mentioned published articles.\n\nUsing HookScan can significantly reduce manual effort and help to locate many potential issues. Nonetheless, HookScan has its limitations, particularly with complex logical vulnerabilities or those related to semantics.\n\nTo uncover and address these sophisticated semantic concerns, the expertise of BlockSec's seasoned professionals is indispensable. They can conduct thorough and detailed reviews to ensure the highest level of security. For our comprehensive audit services and proactive security solutions, such as [Phalcon Block](https://phalcon.xyz/block), to protect your smart contracts and assets, please do not hesitate to contact us.\n\n## License\n\nThis project is under the AGPLv3 License. See the LICENSE file for the full license text.\n\n[public_callback]: docs/detectors/UniswapPublicCallback.md\n[public_hook]: docs/detectors/UniswapPublicHook.md\n[upgradable_hook]: docs/detectors/UniswapUpgradableHook.md\n[suicidal_hook]: docs/detectors/UniswapSuicidalHook.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocksecteam%2Fhookscan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblocksecteam%2Fhookscan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocksecteam%2Fhookscan/lists"}