{"id":22041918,"url":"https://github.com/blocksecteam/rustle","last_synced_at":"2025-05-08T00:52:00.072Z","repository":{"id":62423675,"uuid":"560252110","full_name":"blocksecteam/rustle","owner":"blocksecteam","description":"A static analyzer for NEAR smart contract in Rust","archived":false,"fork":false,"pushed_at":"2023-10-31T05:11:17.000Z","size":512,"stargazers_count":105,"open_issues_count":5,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-08T00:51:27.645Z","etag":null,"topics":["nearprotocol","smart-contract-security","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Rust","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":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-01T03:58:15.000Z","updated_at":"2024-12-03T19:09:23.000Z","dependencies_parsed_at":"2023-02-19T05:16:06.075Z","dependency_job_id":null,"html_url":"https://github.com/blocksecteam/rustle","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Frustle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Frustle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Frustle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blocksecteam%2Frustle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blocksecteam","download_url":"https://codeload.github.com/blocksecteam/rustle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978703,"owners_count":21834914,"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":["nearprotocol","smart-contract-security","static-analysis"],"created_at":"2024-11-30T12:10:24.322Z","updated_at":"2025-05-08T00:52:00.049Z","avatar_url":"https://github.com/blocksecteam.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rustle\n\n\u003cimg src=\"./logo.png\" alt=\"Rustle\" width=\"500\"/\u003e\n\n[![CI Status](https://img.shields.io/github/actions/workflow/status/blocksecteam/rustle/ci.yml?branch=main\u0026label=ci)](https://github.com/blocksecteam/rustle/actions/workflows/ci.yml)\n[![Build-Image Status](https://img.shields.io/github/actions/workflow/status/blocksecteam/rustle/build-image.yml?branch=main\u0026label=build-image)](https://github.com/blocksecteam/rustle/actions/workflows/build-image.yml)\n[![License: AGPL v3](https://img.shields.io/github/license/blocksecteam/rustle)](LICENSE)\n[![AwesomeNEAR](https://img.shields.io/badge/Project-AwesomeNEAR-054db4)](https://awesomenear.com/rustle)\n[![Devpost](https://img.shields.io/badge/Honorable%20Mention-Devpost-003e54)](https://devpost.com/software/rustle)\n\nRustle is an automatic static analyzer for NEAR smart contracts in Rust. It can help to locate tens of different vulnerabilities in NEAR smart contracts.\nAccording to [DefiLlama](https://defillama.com/chain/Near), among the top 10 DApps in NEAR, 8 are audited by BlockSec. With rich audit experience and a deep understanding of NEAR protocol, we build this tool and share it with the community.\n\n## Get started\n\n### Prerequisite\n\n#### Linux setup\n\nInstall the required toolkits with the following commands for **Rustle** in Linux. Commands are tested in Ubuntu 20.04 LTS.\n\n```bash\n# install Rust Toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# install LLVM 15\nsudo bash -c \"$(wget -O - https://apt.llvm.org/llvm.sh)\" 15\n\n# install Python toolchain\nsudo apt install python3 python3-pip    # requires python \u003e= 3.8\npip3 install -r utils/requirements.txt  # you need to clone this repo first\n\n# add WASM target\nrustup target add wasm32-unknown-unknown\n\n# install other components\nsudo apt install figlet\ncargo install rustfilt\n\n# [optional] useful tools for developing\nLLVM_VERSION=\nsudo apt install clangd-$LLVM_VERSION clang-format-$LLVM_VERSION clang-tidy-$LLVM_VERSION\n```\n\n#### macOS setup\n\nThe following commands are for users using macOS, they are tested only on Apple Silicon Mac, so use them with caution.\n\n```bash\n# install Rust Toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# install LLVM 15\nbrew install llvm@15\n\n# install Python packages\npip3 install -r utils/requirements.txt  # you need to clone this repo first\n                                        # using macOS default python3\n\n# add WASM target\nrustup target add wasm32-unknown-unknown\n\n# install other components\nbrew install figlet coreutils gsed\ncargo install rustfilt\n```\n\n#### Docker\n\nWe provide a docker solution.\n\n```bash\n# build the image\ndocker build --build-arg UID=`id -u` --build-arg GID=`id -g` -t rustle .\n\n# run a container from the image\ndocker run --name rustle -it -v `pwd`:/rustle -w /rustle rustle bash\n\n# exec the container\ndocker start rustle\ndocker exec -it -w /rustle rustle bash\n```\n\n### Usage\n\n```bash\n./rustle [-t|--tg_dir \u003ctg_dir\u003e] [-d|--detector \u003cdetector_list\u003e] [-o|--output \u003coutput_dir\u003e] [-h|--help] \u003csrc_dir\u003e\n```\n\n* `src_dir`: Path to the contract source.\n* `tg_dir`: Path to the contract build target. Defaults to be same as `src_dir`.\n* `detector`: The detector list. It can be used to pass multiple *detectors* or *groups* separated by `,`. Defaults to `all`.\n    * pass `all` *group* to enable all detectors.\n    * pass `high`, `medium`, `low` and `info` *groups* to enable detector groups with different severity (refer to [Detectors](#detectors))\n    * pass `nep-ft`, `nep-storage` and `nep-nft` *groups* to enable detectors implemented for specified NEP (refer to [NEP detector groups](#nep-detector-groups))\n    * pass *detector ids* in the [table](#detectors) to enable those detectors\n* `output`: Path where audit reports will be generated in. Defaults to `./audit-result`.\n\nNote: if the target bit code (`.bc` binary) built by cargo is not in the `$src_dir`, use `-t|--tg_dir` to set the target's directory, or it will be set to `$src_dir` by default.\n\nThe command below shows an example of analyzing the LiNEAR.\n\n```bash\n# clone LiNEAR\ngit clone https://github.com/linear-protocol/LiNEAR.git ~/near-repo/LiNEAR\n\n# run Rustle\n./rustle -t ~/near-repo/LiNEAR ~/near-repo/LiNEAR/contracts/linear\n\n# [optional] run Rustle on specified detectors or severity groups and save audit reports in `~/linear-report`\n./rustle -t ~/near-repo/LiNEAR ~/near-repo/LiNEAR/contracts/linear -d high,medium,complex-loop -o ~/linear-report\n```\n\nA CSV-format report will be generated in the directory \"./audit-result\".\n\n## Detectors\n\nAll vulnerabilities **Rustle** can find.\n\n| Detector ID             | Description                                                                                 | Severity |\n| ----------------------- | ------------------------------------------------------------------------------------------- | -------- |\n| `unhandled-promise`     | [find `Promises` that are not handled](docs/detectors/unhandled-promise.md)                 | High     |\n| `non-private-callback`  | [missing macro `#[private]` for callback functions](docs/detectors/non-private-callback.md) | High     |\n| `reentrancy`            | [find functions that are vulnerable to reentrancy attack](docs/detectors/reentrancy.md)     | High     |\n| `unsafe-math`           | [lack of overflow check for arithmetic operation](docs/detectors/unsafe-math.md)            | High     |\n| `self-transfer`         | [missing check of `sender != receiver`](docs/detectors/self-transfer.md)                    | High     |\n| `incorrect-json-type`   | [incorrect type used in parameters or return values](docs/detectors/incorrect-json-type.md) | High     |\n| `unsaved-changes`       | [changes to collections are not saved](docs/detectors/unsaved-changes.md)                   | High     |\n| `nft-approval-check`    | [find `nft_transfer` without check of `approval id`](docs/detectors/nft-approval-check.md)  | High     |\n| `nft-owner-check`       | [find approve or revoke functions without owner check](docs/detectors/nft-owner-check.md)   | High     |\n| `div-before-mul`        | [precision loss due to incorrect operation order](docs/detectors/div-before-mul.md)         | Medium   |\n| `round`                 | [rounding without specifying ceil or floor](docs/detectors/round.md)                        | Medium   |\n| `lock-callback`         | [panic in callback function may lock contract](docs/detectors/lock-callback.md)             | Medium   |\n| `yocto-attach`          | [no `assert_one_yocto` in privileged function](docs/detectors/yocto-attach.md)              | Medium   |\n| `dup-collection-id`     | [duplicate id uses in collections](docs/detectors/dup-collection-id.md)                     | Medium   |\n| `unregistered-receiver` | [no panic on unregistered transfer receivers](docs/detectors/unregistered-receiver.md)      | Medium   |\n| `nep${id}-interface`    | [find all unimplemented NEP interface](docs/detectors/nep-interface.md)                     | Medium   |\n| `prepaid-gas`           | [missing check of prepaid gas in `ft_transfer_call`](docs/detectors/prepaid-gas.md)         | Low      |\n| `non-callback-private`  | [macro `#[private]` used in non-callback function](docs/detectors/non-callback-private.md)  | Low      |\n| `unused-ret`            | [function result not used or checked](docs/detectors/unused-ret.md)                         | Low      |\n| `upgrade-func`          | [no upgrade function in contract](docs/detectors/upgrade-func.md)                           | Low      |\n| `tautology`             | [tautology used in conditional branch](docs/detectors/tautology.md)                         | Low      |\n| `storage-gas`           | [missing balance check for storage expansion](docs/detectors/storage-gas.md)                | Low      |\n| `unclaimed-storage-fee` | [missing balance check before storage unregister](docs/detectors/unclaimed-storage-fee.md)  | Low      |\n| `inconsistency`         | [use of similar but slightly different symbol](docs/detectors/inconsistency.md)             | Info     |\n| `timestamp`             | [find all uses of `timestamp`](docs/detectors/timestamp.md)                                 | Info     |\n| `complex-loop`          | [find all loops with complex logic which may lead to DoS](docs/detectors/complex-loop.md)   | Info     |\n| `ext-call`              | [find all cross-contract invocations](docs/detectors/ext-call.md)                           | Info     |\n| `promise-result`        | [find all uses of promise result](docs/detectors/promise-result.md)                         | Info     |\n| `transfer`              | [find all transfer actions](docs/detectors/transfer.md)                                     | Info     |\n| `public-interface`      | [find all public interfaces](docs/detectors/public-interface.md)                            | Info     |\n\n### NEP detector groups\n\nApart from the groups by severity level, **Rustle** provides some detector groups by corresponding NEP. Currently, **Rustle** supports the following groups.\n\n[nep141]: https://github.com/near/NEPs/blob/master/neps/nep-0141.md\n[nep145]: https://github.com/near/NEPs/blob/master/neps/nep-0145.md\n[nep171]: https://github.com/near/NEPs/blob/master/neps/nep-0171.md\n[nep178]: https://github.com/near/NEPs/blob/master/neps/nep-0178.md\n\n| NEP                                  | Detector Group ID | Detector IDs                                                 |\n| ------------------------------------ | ----------------- | ------------------------------------------------------------ |\n| [NEP-141][nep141]                    | `nep-ft`          | `nep141-interface`, `self-transfer`, `unregistered-receiver` |\n| [NEP-145][nep145]                    | `nep-storage`     | `nep145-interface`, `unclaimed-storage-fee`                  |\n| [NEP-171][nep171], [NEP-178][nep178] | `nep-nft`         | `nep171-interface`, `nft-approval-check`, `nft-owner-check`  |\n\n## Add new detectors\n\n1. Fork this repo to your account.\n2. Put the new detector under [/detectors](/detectors/).\n3. Add a detection target in [/Makefile](/Makefile) with commands to run your detector.\n4. Add the target to the dependency of `audit` target and its name to [detector list](/rustle#L146) and [severity groups](/rustle#L169) in `./rustle` script.\n5. Add processing code in [utils/audit.py](/utils/audit.py) (refer to other detectors' code in `audit.py`).\n6. Submit a pull request from your branch to the main.\n\n## Note\n\n**Rustle** can be used in the development process to scan the NEAR smart contracts iteratively. This can save a lot of manual effort and mitigate part of potential issues. However, vulnerabilities in complex logic or related to semantics are still the limitation of **Rustle**. Locating complicated semantic issues requires the experts in [BlockSec](https://blocksec.com/) to conduct exhaustive and thorough reviews. [Contact us](audit@blocksec.com) for audit service.\n\n## License\n\nThis project is under the AGPLv3 License. See the [LICENSE](LICENSE) file for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocksecteam%2Frustle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblocksecteam%2Frustle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblocksecteam%2Frustle/lists"}