From 4cb1d150cd3bcfa9b140bbdae2ac322a5effed41 Mon Sep 17 00:00:00 2001 From: Alex Roan Date: Thu, 25 Apr 2024 12:51:57 +0100 Subject: [PATCH] Match readme wording to docs (#367) --- README.md | 2 +- aderyn/README.md | 133 ++++++++++++++++++++++++++--------------------- 2 files changed, 76 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index f408b745b..b1657deeb 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ ## What is Aderyn? -Aderyn is a **Rust-based solidity smart contract static analyzer** designed to help protocol engineers and security researchers find vulnerabilities in Solidity code bases. +**Aderyn is an open-source public good developer tool.** It is a Rust-based solidity smart contract static analyzer designed to help protocol engineers and security researchers find vulnerabilities in Solidity code bases. Thanks to its collection of static vulnerability detectors, running Cyfrin Aderyn on your Solidity codebase will **highlight potential vulnerabilities**, drastically reducing the potential for unknown issues in your Solidity code and giving you the time to focus on more complex problems. diff --git a/aderyn/README.md b/aderyn/README.md index ba7aa2d4d..95450faf1 100644 --- a/aderyn/README.md +++ b/aderyn/README.md @@ -17,9 +17,10 @@

-Twitter +Docs +Get support Website -Discord +Twitter

--- @@ -38,50 +39,83 @@ ## What is Aderyn? +**Aderyn is an open-source public good developer tool.** It is a Rust-based solidity smart contract static analyzer designed to help protocol engineers and security researchers find vulnerabilities in Solidity code bases. -Aderyn is a Rust-based static analyzer specifically designed for Web3 smart contract security and development. It takes a bird's eye view over your smart contracts, traversing the Abstract Syntax Trees (AST) to pinpoint suspected vulnerabilities. Aderyn prints out these potential issues in an easy-to-consume markdown format. +Thanks to its collection of static vulnerability detectors, running Cyfrin Aderyn on your Solidity codebase will **highlight potential vulnerabilities**, drastically reducing the potential for unknown issues in your Solidity code and giving you the time to focus on more complex problems. -## Features +Built using **Rust**, Aderyn integrates seamlessly into small and **enterprise-level development workflows**, offering lighting-fast command-line functionality and a framework to [build custom detectors](https://docs.cyfrin.io/aderyn-custom-detectors/what-is-a-detector) to adapt to your codebase. -* [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/) support +You can read the [Cyfrin official documentation](https://docs.cyfrin.io) for an in-depth look at Aderyn's functionalities. + +## Features +* [Foundry](https://book.getfoundry.sh/) support * Modular [detectors](../aderyn_core/src/detect/) * AST Traversal * Markdown reports -# Usage - -To get started using Aderyn make sure to have Rust installed on your device. For more information, refer to the [official Rust documentation](https://www.rust-lang.org/tools/install). +## Installation -## Mac, Linux, Unix +### Prerequisites +Before installing Aderyn, ensure you have the following: +* Rust: Aderyn is built in Rust. Before running, you must install Rust and Cargo (Rust's package manager). If you still need to install Rust, follow the instructions on the [official Rust website](https://www.rust-lang.org/learn/get-started). -You can install Rust and Cargo by running the following command on your terminal: - ```sh - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` +Aderyn currently only supports Foundry-based projects. If you're using Hardhat, please take a look at the [contribution guidelines]() and [issues]() for information on how to contribute. +**Suggested VSCode extensions:** +[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=dustypomerleau.rust-syntax) - Rust language support for Visual Studio Code +[Rust Syntax](https://marketplace.visualstudio.com/items?itemName=dustypomerleau.rust-syntax) - Improved Rust syntax highlighting -## Windows +### Installing Aderyn +**Step 1: Install Aderyn using cargo** -You can install Rust and Cargo by downloading and running [`rustup-init.exe`](https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe). +Aderyn is currently installed using Cargo, Rust's package manager. Open your command line interface and run the following command: +```sh +cargo install aderyn +``` +This command downloads and installs the Aderyn package. -## Installation +**Step 2: Verify installation** -In the command line, run: +After the installation, you can verify that Aderyn is correctly installed by checking its version. In your command line, execute: ```sh -cargo install aderyn +aderyn --version ``` +This command should return the installed version of Aderyn, confirming that the installation was successful. -## Quick Start +**Step 3: Update PATH (if necessary)** -The root path you're running Aderyn on should be either a **Foundry** or compiled **Hardhat** project. +If you cannot run the aderyn after installation, you may need to add Cargo's bin directory to your PATH. The exact instructions can vary based on your operating system. Typically, it involves adding ~/.cargo/bin to your PATH in your shell profile script (like .bashrc or .zshrc). +**Step 4: Future Updates** + +To update Aderyn to the latest version, you can run the install command again: ```sh -aderyn /path/to/your/foundry/project/root/directory/ +cargo install aderyn ``` +Cargo will replace the existing version with the latest one. -That's it! Aderyn identifies whether the project root is a Foundry or Hardhat repo, then uses the compiled AST files to hunt for vulnerabilities. +## Quick Start +Once Aderyn is installed on your system, you can run it against your Foundry-based codebase to find vulnerabilities in your code. -`report.md` will be output **in the directory in which you ran the command.** +We will use the [aderyn-contracts-playground](https://github.com/Cyfrin/aderyn-contracts-playground) repository in this example. You can follow along by cloning it to your system: +```sh +git clone https://github.com/Cyfrin/aderyn-contracts-playground.git +``` +Navigate inside the repository: +```sh +cd aderyn-contracts-playground +``` +We usually use several smart contracts and tests to try new detectors. Build the contracts by running: +```sh +forge build +``` +Building your project by running forge build --ast will save you time the first time you run Aderyn. +Once your smart contracts have been successfully compiled, run Aderyn using the following command: +```sh +aderyn [OPTIONS] path/to/your/project +``` +Replace [OPTIONS] with specific command-line arguments as needed. +For an in-depth walkthrough on how to get started using Aderyn, check the [Cyfrin official docs](https://docs.cyfrin.io/aderyn-static-analyzer/quickstart) ### Arguments @@ -90,7 +124,7 @@ Usage: `aderyn [OPTIONS] ` ``: The path to the root of the codebase to be analyzed. Defaults to the current directory. Options: - - `-o`, `--output `: Desired file path for the final report (will overwrite existing one) [default: report.md] + - `-o`, `--output `: Desired file path for the final report (will overwrite the existing one) [default: report.md] - `-s`, `--scope `: List of path strings to include, delimited by comma (no spaces). Any solidity file path not containing these strings will be ignored - `-e`, `--exclude `: List of path strings to exclude, delimited by comma (no spaces). Any solidity file path containing these strings will be ignored - `-n`, `--no-snippets`: Do not include code snippets in the report (reduces report size in large repos) @@ -98,56 +132,38 @@ Options: - `-V`, `--version`: Print version -You must provide the root directory of the repo you want to analyze. Alternatively, you can provide a single Solidity filepath (this mode requires [Foundry](https://book.getfoundry.sh/) to be installed). +You must provide the root directory of the repo you want to analyze. Alternatively, you can provide a single Solidity file path (this mode requires [Foundry](https://book.getfoundry.sh/) to be installed). Examples: ```sh aderyn /path/to/your/foundry/project/root/directory/ ``` +Find more examples on the official [Cyfrin Docs](https://docs.cyfrin.io) -Run Aderyn in the folder you're currently in: +## Building a custom Aderyn detector +Aderyn makes it easy to build Static Analysis detectors that can adapt to any Solidity codebase and protocol. This guide will teach you how to build, test, and run your custom Aderyn detectors. +To learn how to create your custom Aderyn detectors, [checkout the official docs](https://docs.cyfrin.io/aderyn-custom-detectors/detectors-quickstart) -```sh -aderyn -``` - -Output to a different markdown file: - -```sh -aderyn -o output.md ./path/to/repo/ -``` +## Docker -Refine the scope to a subdirectory called `/uniswap/`: +You can run Aderyn from a Docker container. +Build the image: ```sh -aderyn --scope uniswap ./path/to/repo/ + docker build -t aderyn . ``` +`/path/to/project/root` should be the path to your Foundry or Hardhat project root directory and it will be mounted to `/share` in the container. -Exclude a contract called `Counter.sol`: - +Run Aderyn: ```sh -aderyn --exclude Counter.sol ./path/to/repo/ + docker run -v /path/to/project/root/:/share aderyn ``` - -Run on a single Solidity file (requires [Foundry](https://book.getfoundry.sh/) to be installed on your machine): - +Run with flags: ```sh -aderyn src/MyContract.sol + docker run -v /path/to/project/root/:/share aderyn -h ``` -## Supported Development Frameworks - -If the `` is a directory, Aderyn automatically detects the development framework so long as it's Foundry or Hardhat. - -### Foundry - -If Foundry is detected in the project root, Aderyn will first run `forge build` to ensure that the contract compiles correctly and the latest artifacts are available. - -### Hardhat - -If Hardhat is detected, Aderyn does not auto-compile. Make sure to run `hardhat compile` BEFORE running Aderyn. - ## Single Solidity File Mode If it is a Solidity file path, then Aderyn will create a temporary Foundry project, copy the contract into it, compile the contract and then analyze the AST generated by that temporary project. @@ -155,13 +171,13 @@ If it is a Solidity file path, then Aderyn will create a temporary Foundry proje ## Contributing & License Help us build Aderyn 🦜 Please see our [contribution guidelines](../CONTRIBUTING.md). -Aderyn is an open source software licensed under the [MIT License](../LICENSE). +Aderyn is an open-source software licensed under the [MIT License](../LICENSE). To build Aderyn locally, [install Rust](https://www.rust-lang.org/tools/install), clone this repo, and use [`cargo`](https://doc.rust-lang.org/cargo/getting-started/first-steps.html) commands to build, test and run locally ## Credits -This project exists thanks to all the people who [contribute](/CONTRIBUTING.md).
+This project exists thanks to all the people who [contribute](../CONTRIBUTING.md).
@@ -170,6 +186,7 @@ This project exists thanks to all the people who [contribute](/CONTRIBUTING.md). ## Attribution * AST Visitor code from [solc-ast-rs](https://github.com/hrkrshnn/solc-ast-rs). * Original detectors based on [4naly3er](https://github.com/Picodes/4naly3er) detectors. +* Shoutout to the original king of static analysis [slither](https://github.com/crytic/slither). [contributors-shield]: https://img.shields.io/github/contributors/cyfrin/aderyn