diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md new file mode 100644 index 00000000..eb3be07c --- /dev/null +++ b/docs/CLI/Fuzz Testing.md @@ -0,0 +1,154 @@ +# Fuzz Test Generation + +## Overview + +Olympix Fuzz Testing is a specialized security tool designed for smart contracts. The fuzzer integrates an in-house symbolic execution engine to reason about code behavior, explore every possible path and uses SMT solving to generate concrete inputs that trigger specific execution paths. Once paths are explored, the tool applies a set of attack strategies to automatically generate proof-of-concepts for potential exploits. + +### Why Fuzz Testing Matters + +Traditional fuzzing can miss vulnerabilities because it depends on random mutations to reach different paths. By leveraging an in-house symbolic execution and proof-of-concepts generation, our tool achieves path-aware fuzzing, allowing it to: + +1. Detecting vulnerabilities that depend on complex input conditions +2. Exploring all reachable execution paths, including deep analysis of inner function calls +3. Performing inter-function analysis to reach paths that depend on state changes from prior function calls +4. Building proof-of-concepts demonstrating real exploitability + +### Security Implications + +In blockchain security, logic errors or validation misses can lead to severe financial losses. Olympix Fuzz Testing tool helps developers identify these issues early by simulating real-world attack scenarios. + +The integrated attack strategy engine applies heuristics and exploit templates inspired by real vulnerabilities such as reentrancy, price manipulation, or access control bypasses to validate whether discovered conditions are exploitable in practice. + +Each generated proof-of-concept provides a concrete demonstration of a potential exploit path, giving teams clear, actionable insight into their contract’s weakest points before deployment. + +### How it works + +
+ +```mermaid +flowchart TD + %% Styles + classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px,rx:10,ry:10,color:#000; + classDef internal fill:#ffffff,stroke:#ae6ae0,stroke-width:1px,rx:10,ry:10,color:#000; + linkStyle default stroke:#ae6ae0,stroke-width:1px; + + %% Nodes + A[**User**
Submits smart contracts]:::node --> + B[**Fuzzer**
Fuzzes smart contracts to identify potential vulnerabilities]:::node -.-> Internal + + subgraph Internal["**Internal Workflow**"] + direction LR + C[**Symbolic Execution**
Performs path exploration over the IR and generates inputs to trigger each path]:::internal -.-> + D[**Exploit Detection**
Generates test cases using attack strategies to reproduce exploits]:::internal + end + + Internal --> E[**Email Report**
Sends analysis results to user]:::node + + %% Assign classes + class A,B,E node + class C,D internal +``` +
+ +### Coverage Modes + +Take this function as example: + +``` +function example(uint256 a, uint256 b) external { + if(a > 100) { + //Do something + } + + if(b > 100) { + //Do something + } +} +``` + +**Path Coverage**: 4 paths explored, covering all branch combinations + +
+ +```mermaid +flowchart TD + %% Styles + classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; + classDef path stroke:#ae6ae0,stroke-width:2px; + + %% Nodes + A([Start]):::node --> B{a > 100}:::node + B -->|True| C{b > 100}:::node + B -->|False| D{b > 100}:::node + + C -->|True| E([End]):::node + C -->|False| F([End]):::node + D -->|True| G([End]):::node + D -->|False| H([End]):::node + + %% Paths + class A,B,C,D,E,F,G,H path; +``` + +
+ +**Branch Coverage**: 1 path explored, covering all branches with minimum number of paths needed. Covers all branches but not all possible true/false combinations + +
+ +```mermaid +flowchart TD + %% Styles + classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; + classDef path stroke:#ae6ae0,stroke-width:2px; + + %% Nodes + A([Start]):::node --> B{a > 100}:::node + B -->|True| C{b > 100}:::node + C -->|True| D[End]:::node + + %% Paths + class A,B,C,D path; +``` + +
+ +--- + +## Installation & Requirements + +The fuzz testing generator is designed to be dependency-free and works with any Forge project. + +:white_check_mark: No external dependencies +:white_check_mark: Works with standard Forge + +--- + +## CLI Usage + +```none +generate-fuzz-tests [-w ] [-p ] + +Options + -w, --workspace-path: Root project directory path (default: current directory) + + -p, --path: Solidity file path to fuzz (can be specified multiple times) + + -cm, --coverage-mode: Exploration strategies: + `path`: Explores all distinct paths, including every branch combination + `branch`: Covers all branches using the fewest paths possible + + -cl, --chain-length: Number of sequential function calls per exploration. High values can drastically increase analysis time. Default: 2 + + --no-: Defines the attack strategies that may be ignored. It can be used multiple times to ignore each attack strategy + + Tip: Start with `--coverage-mode branch` and `--chain-length 2`(default) for a fast, high-value initial run +``` + +## Need Help? + +If you encounter any issues or have questions, feel free to reach out: + +**Email:** [contact@olympix.ai](mailto:contact@olympix.ai) + +Happy fuzzing! 🎉 \ No newline at end of file diff --git a/docs/CLI/index.md b/docs/CLI/index.md index 8efc6e63..b95775b9 100644 --- a/docs/CLI/index.md +++ b/docs/CLI/index.md @@ -11,6 +11,7 @@ When you run the Olympix CLI, you have access to several commands: - **`analyze`**: Perform code analysis - **`generate-unit-tests`**: Generate unit tests - **`generate-mutation-tests`**: Generate mutation tests +- **`generate-fuzz-tests`**: Generate fuzz tests - **`login`**: Request access and log in to your account - **`show-vulnerabilities`**: Show the vulnerability types that the analyzer aims to find - **`version`**: Show CLI version @@ -39,7 +40,6 @@ When using the `analyze` command, you can customize the analysis with the follow - **`--no-`** Defines the vulnerabilities to be ignored. Can be used multiple times. - *Default:* Ignores nothing --- @@ -82,7 +82,34 @@ When generating mutation tests, you have the following options: - **`--env-file`**: Defines the path of the file containing the environment variables. Make sure to follow foundry's .env format guidelines. Doesn't do anything if '--include-dot-env' is not set. *Default*: `.env` + - **`-ext, --extension`**: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: `--extra-extension .json --extra-extension .txt`. By default, only `.sol/.t.sol` and/or `foundry.toml` files are uploaded. + +--- + +## Fuzz Tests Generation Options + +When generating fuzz tests, you have the following options: + +- **`-w | --workspace-path`** + Defines the root project directory path. + *Default:* current directory + +- **`-p | --path`** + Defines the Solidity file path to run the fuzz tests. Can be used multiple times. + +- **`-cm | --coverage-mode`** + Exploration strategies: + `path`: Explores all distinct paths, including every branch combination + `branch`: Covers all branches using the fewest paths possible + +- **`-cl | --chain-length`** + Number of sequential function calls per exploration. High values can drastically increase analysis time + *Default:* 2 + +- **`--no-`** + Defines the attack strategies to be ignored. Can be used multiple times. + --- ## Usage Examples diff --git a/mkdocs.yml b/mkdocs.yml index 9d4cede9..f485f076 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,7 +42,11 @@ markdown_extensions: pygments_lang_class: true - pymdownx.inlinehilite - pymdownx.snippets - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.details - pymdownx.tabbed: - alternate_style: true + alternate_style: true \ No newline at end of file