From c9daf13df7c4e257d684e8816e134b65d7b67dfc Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Tue, 28 Oct 2025 20:19:03 -0300 Subject: [PATCH 01/10] #1082 Adding first version of fuzzing doc --- docs/CLI/Fuzz Testing.md | 60 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/CLI/Fuzz Testing.md diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md new file mode 100644 index 00000000..99531e20 --- /dev/null +++ b/docs/CLI/Fuzz Testing.md @@ -0,0 +1,60 @@ +# Fuzz Testing 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 generate precise 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. + +--- + +## 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 + + 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 From 1cda2dfe5893c478d78b225e9fe25e483a0eef29 Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Wed, 29 Oct 2025 19:39:42 -0300 Subject: [PATCH 02/10] #1082 Updating fuzzing doc --- docs/CLI/Fuzz Testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index 99531e20..be2e2015 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -43,8 +43,8 @@ Options -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 + `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 From caec4bafc3c4e43344c5489d378304e9e2f7e542 Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Thu, 30 Oct 2025 10:31:44 -0300 Subject: [PATCH 03/10] #1082 Improving fuzzing doc --- docs/CLI/Fuzz Testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index be2e2015..02ee2a84 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -2,7 +2,7 @@ ## 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 generate precise 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. +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 @@ -48,6 +48,8 @@ Options -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 ``` From 8c8262d0e665e680eea29dd567474be4d4c34ad1 Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Thu, 30 Oct 2025 19:57:57 -0300 Subject: [PATCH 04/10] #1082 Adding fuzzing to index page --- docs/CLI/index.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/CLI/index.md b/docs/CLI/index.md index 8efc6e63..cc5c0eb9 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,9 +82,35 @@ 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 ```bash From ab1c1fbc3c4ebc227262b0f7345ba02c3aa45b79 Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Fri, 31 Oct 2025 20:32:48 -0300 Subject: [PATCH 05/10] #1082 Adding diagrams to fuzzing page --- docs/CLI/Fuzz Testing.md | 81 ++++++++++++++++++++++++++++++++++++++++ docs/CLI/index.md | 1 + mkdocs.yml | 8 +++- 3 files changed, 88 insertions(+), 2 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index 02ee2a84..3856ce88 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -21,6 +21,87 @@ The integrated attack strategy engine applies heuristics and exploit templates i 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 + +#### Process Flow + +
+``` mermaid + flowchart TD + %% Styles + classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; + classDef path stroke:#ae6ae0,stroke-width:2px; + + %% Nodes + A[**User**]:::node --> B[**Fuzzing Application**]:::node + B --> C[**Symbolic Execution Engine**
Performs path exploration over the IR and generates inputs to trigger each path]:::node + C --> D[**Exploit Detection**
Apply attack strategies to reproduce exploits]:::node + D --> E[**Email Report**]:::node + + %% Paths + class A,B,C,D path; +``` +
+ +#### 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 + +
+``` 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 diff --git a/docs/CLI/index.md b/docs/CLI/index.md index cc5c0eb9..b95775b9 100644 --- a/docs/CLI/index.md +++ b/docs/CLI/index.md @@ -84,6 +84,7 @@ When generating mutation tests, you have the following options: *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 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 From 29da6f04f26fa9071b8bccb4d2d353c17af427bb Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Wed, 12 Nov 2025 17:11:18 -0300 Subject: [PATCH 06/10] #1082 Improving fuzzing page --- docs/CLI/Fuzz Testing.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index 3856ce88..4c5bd031 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -1,4 +1,4 @@ -# Fuzz Testing Generation +# Fuzz Test Generation ## Overview @@ -23,8 +23,6 @@ Each generated proof-of-concept provides a concrete demonstration of a potential ### How it works -#### Process Flow -
``` mermaid flowchart TD @@ -43,7 +41,7 @@ Each generated proof-of-concept provides a concrete demonstration of a potential ```
-#### Coverage Modes +### Coverage Modes Take this function as example: From 28b3414cb7b2be89c3c926194e6e8dffee15931a Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Wed, 12 Nov 2025 19:16:54 -0300 Subject: [PATCH 07/10] #1082 Improving fuzzing workflow --- docs/CLI/Fuzz Testing.md | 46 +++++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index 4c5bd031..e6e8750f 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -23,23 +23,35 @@ Each generated proof-of-concept provides a concrete demonstration of a potential ### How it works -
-``` mermaid - flowchart TD - %% Styles - classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; - classDef path stroke:#ae6ae0,stroke-width:2px; - - %% Nodes - A[**User**]:::node --> B[**Fuzzing Application**]:::node - B --> C[**Symbolic Execution Engine**
Performs path exploration over the IR and generates inputs to trigger each path]:::node - C --> D[**Exploit Detection**
Apply attack strategies to reproduce exploits]:::node - D --> E[**Email Report**]:::node - - %% Paths - class A,B,C,D path; -``` -
+
+ +```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 project]:::node --> + B[**Fuzzing Application**
Coordinates the analysis]:::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 + + %% Hide the internal dotted link + linkStyle 2 stroke-width:0px,fill:none; +``` +
### Coverage Modes From ba6813f65b54f442ca1eaaefdf94ea977d0079fc Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Wed, 12 Nov 2025 19:53:24 -0300 Subject: [PATCH 08/10] #1082 Improving fuzzing descriptions --- docs/CLI/Fuzz Testing.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index e6e8750f..790f6c21 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -33,12 +33,12 @@ flowchart TD linkStyle default stroke:#ae6ae0,stroke-width:1px; %% Nodes - A[**User**
Submits project]:::node --> - B[**Fuzzing Application**
Coordinates the analysis]:::node -.-> Internal + 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 --- + 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 @@ -47,9 +47,6 @@ flowchart TD %% Assign classes class A,B,E node class C,D internal - - %% Hide the internal dotted link - linkStyle 2 stroke-width:0px,fill:none; ``` From f8e8207a28c83e0d92d6b58e0ee5d3721af780f0 Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Thu, 13 Nov 2025 10:35:24 -0300 Subject: [PATCH 09/10] #1082 Improving branch coverage description --- docs/CLI/Fuzz Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index 790f6c21..ff873c09 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -90,7 +90,7 @@ flowchart TD ``` -**Branch Coverage**: 1 path explored, covering all branches with minimum number of paths needed +**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 From 8bbe5fed0d3e824b2bc18f0206a884eb3a52aedd Mon Sep 17 00:00:00 2001 From: raphaelcastilhoc Date: Thu, 13 Nov 2025 13:27:29 -0300 Subject: [PATCH 10/10] #1082 formatting mermaid flows --- docs/CLI/Fuzz Testing.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/CLI/Fuzz Testing.md b/docs/CLI/Fuzz Testing.md index ff873c09..eb3be07c 100644 --- a/docs/CLI/Fuzz Testing.md +++ b/docs/CLI/Fuzz Testing.md @@ -69,7 +69,8 @@ function example(uint256 a, uint256 b) external { **Path Coverage**: 4 paths explored, covering all branch combinations
-``` mermaid + +```mermaid flowchart TD %% Styles classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; @@ -88,12 +89,14 @@ flowchart TD %% 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 + +```mermaid flowchart TD %% Styles classDef node fill:#f9f9ff,stroke:#6a0dad,stroke-width:1px; @@ -107,6 +110,7 @@ flowchart TD %% Paths class A,B,C,D path; ``` +
---