Skip to content

Commit f7edd2d

Browse files
robotroborobotrobo
authored
Merge pull request #9 from olympix/add_bugpocer_docs
2 parents b59dc20 + cf6e46c commit f7edd2d

2 files changed

Lines changed: 255 additions & 8 deletions

File tree

‎docs/CLI/BugPoCer.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# BugPoCer
2+
3+
BugPoCer is an AI-powered internal audit tool that automates end-to-end vulnerability exploitation for smart contracts — moving beyond static warnings to deliver **concrete, verifiable Proof-of-Concept (PoC) exploits**.
4+
5+
---
6+
7+
## Overview
8+
9+
Built on Olympix's proprietary Intermediate Representation (IR) and symbolic execution engine, BugPoCer combines results from multiple analysis engines to identify **confirmed** security issues. For each vulnerability, it automatically generates a **ready-to-run Foundry-format PoC test** that reproduces the exploit under realistic attack conditions.
10+
11+
### Key Capabilities
12+
13+
- **Automated Vulnerability Detection** — AI-driven protocol scanning
14+
- **Project Context and Invariant Building** — Approve inferred project context
15+
- **PoC Generation** — Automatically creates Foundry test files that demonstrate exploits
16+
- **Interactive Analysis** — Ask follow-up questions about findings
17+
18+
---
19+
20+
## Prerequisites
21+
22+
!!! info "Project Requirements"
23+
- A successfully compiling Foundry project
24+
- Valid Olympix credentials (obtain via `olympix login`)
25+
26+
---
27+
28+
## CLI Commands
29+
30+
### Starting a BugPoCer Scan
31+
32+
To start a new scan or reconnect to past sessions, navigate to your project root and run:
33+
34+
!!! tip "Quick Start"
35+
```bash
36+
olympix bug-pocer
37+
```
38+
39+
The scan will analyze your smart contracts, identify vulnerabilities, generate PoC tests, and produce a comprehensive report.
40+
41+
**Available Options:**
42+
43+
| Option | Description |
44+
|--------|-------------|
45+
| `-w, --workspace-path` | Root project directory path (default: current directory) |
46+
| `-env, --include-dot-env` | Include .env file for fork testing secrets (RPC URLs, API keys, etc.) |
47+
| `--env-file` | Path to custom .env file (requires `-env` flag) |
48+
| `-ext, --extension` | Additional file extensions to include (can be used multiple times) |
49+
50+
!!! tip "Including env variables"
51+
We provide the ability to pass environment variables with your Solidity files. If you would like to provide `RPC URLs`, `API keys`, `private keys`, etc., you can do so by using the `-env` flag which will read these parameters from your `.env` file. You can also specify a custom filepath for your `env` file using the `--env-file` flag.
52+
Refer here for format guidelines: `https://book.getfoundry.sh/cheatcodes/env-string`.
53+
54+
Note: If you do require passing `env variables` for your `forge` run, this is the recommended way to do it. We encrypt all communication of this file with an extra layer of RSA on top of the regular encryption.
55+
56+
---
57+
58+
## Scan Workflow
59+
60+
When you run `olympix bug-pocer`, here's what to expect from start to finish:
61+
62+
### Step 1: Session Selection
63+
64+
The CLI displays a session picker where you can:
65+
- **Start a new session** — Begin a fresh scan
66+
- **Return to active session** — Continue an in-progress scan
67+
- **Connect to a past session** — Review results from a completed scan
68+
69+
Use arrow keys to navigate, Enter to select, or press `n` for new, `r` to refresh, `q` to quit.
70+
71+
### Step 2: Session Naming (New Sessions Only)
72+
73+
When starting a new session, you'll be prompted to name it:
74+
```
75+
Name for this session (Enter for 'org/repo@abc1234'):
76+
```
77+
78+
The default name is generated from your git repository info. Press Enter to accept or type a custom name.
79+
80+
### Step 3: File Upload
81+
82+
Your project files are scanned and uploaded to the Olympix servers. This includes:
83+
- All Solidity files (`.sol`)
84+
- Configuration files (`foundry.toml`, `remappings.txt`)
85+
- Documentation files (README, etc.)
86+
- Environment variables (if `-env` flag was used)
87+
88+
### Step 4: Project Context Validation
89+
90+
BugPoCer analyzes your codebase and infers project context. You'll be asked to review and validate:
91+
92+
- **Project Identity** — Name, type, and purpose of the protocol
93+
- **Intent/Description** — What the protocol does
94+
- **Core Functions** — Key functionality of the system
95+
- **Design Goals** — Intended behavior and constraints
96+
- **Patterns** — Detected architectural patterns
97+
- **Invariants** — Properties that should always hold
98+
- **Security Assumptions** — Trust boundaries and assumptions
99+
100+
For each item below the confidence threshold, you can:
101+
- Press **Y** to confirm it's correct
102+
- Press **N** to reject and provide an explanation
103+
104+
!!! info "Why Validation Matters"
105+
Your feedback helps BugPoCer understand what's intentional vs. what might be a vulnerability. Accurate context leads to better findings and fewer false positives.
106+
107+
### Step 5: Scan Execution
108+
109+
After you approve the project context, the scan begins. At this point:
110+
111+
- The CLI displays: *"Bug pocer started successfully, waiting for initial scan to complete..."*
112+
- You'll receive your **Session ID** for reconnecting later
113+
- **You will receive an email** when the scan completes
114+
115+
!!! tip "Long-Running Scans"
116+
You can safely close the CLI and reconnect later using `olympix bug-pocer`. Your session will appear in the session picker with its current status.
117+
118+
### Step 6: Results Review
119+
120+
When the scan completes, on session reconnection you'll be able to:
121+
122+
1. **View Findings** — Parse through findings and PoCs
123+
2. **Update Findings** — Mark true positive/false positive verdicts and add comments
124+
3. **Save Findings** — Option to save the report to a local file
125+
126+
### Step 7: Interactive Q&A
127+
128+
After viewing results, you can ask follow-up questions:
129+
```
130+
You can now ask questions to BugPocer or enter nothing to exit:>
131+
```
132+
133+
Example questions:
134+
- "Explain the reentrancy vulnerability in more detail"
135+
- "How can I fix the access control issue in Vault.sol?"
136+
- "Are there any other functions affected by this pattern?"
137+
138+
---
139+
140+
## Session Status Reference
141+
142+
When viewing the session picker, sessions display their current status:
143+
144+
| Status | Meaning |
145+
|--------|---------|
146+
| `CHATSTARTED` | Session created, awaiting context validation |
147+
| `VALIDATIONREQUESTED` | Waiting for you to validate project context |
148+
| `VALIDATIONCOMPLETED` | Context approved, scan in progress |
149+
| `INITIALSCANCOMPLETED` | Scan finished, results available |
150+
| `QUESTIONRECEIVED` | Processing a follow-up question |
151+
| `QUESTIONANSWERED` | Response ready |
152+
153+
---
154+
155+
## Scope and Ignore Configuration
156+
157+
BugPoCer uses its own scope and ignore settings, separate from the general Olympix configuration options. These are configured in your `olympix-config.json` file at the project root.
158+
159+
### BugPoCer-Specific Options
160+
161+
```json
162+
{
163+
"BugPocerScopePaths": [
164+
"src/core/",
165+
"src/vaults/vault.sol"
166+
],
167+
"BugPocerIgnorePaths": [
168+
"src/examples/",
169+
"src/mocks/mock.sol"
170+
]
171+
}
172+
```
173+
174+
| Option | Description |
175+
|--------|-------------|
176+
| `BugPocerScopePaths` | **Positive scoping** — If defined, BugPoCer will ONLY analyze files whose paths start with one of these entries. Leave empty or omit to analyze all files. |
177+
| `BugPocerIgnorePaths` | Paths to exclude from the scan. Any file whose path starts with one of these entries will be ignored. |
178+
179+
!!! info "How Scope and Ignore Interact"
180+
1. If `BugPocerScopePaths` is defined and non-empty, only files matching a scope path are considered
181+
2. From the scoped files, any matching `BugPocerIgnorePaths` are excluded
182+
3. If `BugPocerScopePaths` is empty or omitted, all files are in scope (minus ignores)
183+
184+
### Default Ignore List
185+
186+
BugPoCer automatically excludes common non-production paths. Files containing any of the following in their path are always ignored:
187+
188+
`test`, `mock`, `example`, `dependencies`, `forge-std`, `openzeppelin`, `solmate`, `solady`, `prb-math`, `prb-test`, `murky`, `permit2`, `v3-core`, `v3-periphery`, `v2-core`, `v2-periphery`
189+
190+
!!! note "Difference from Other Olympix Tools"
191+
BugPoCer does **not** use the general `IgnoredPaths`, `TrustedPaths`, `TrustedVariables`, or `TrustedContracts` options. Use `BugPocerScopePaths` and `BugPocerIgnorePaths` instead.
192+
193+
---
194+
195+
## Scan Report
196+
197+
Each finding in the BugPoCer scan report includes:
198+
199+
### Vulnerability Details
200+
201+
- **Description** — What the vulnerability is and how it can be exploited
202+
- **Severity** — Risk level (High, Medium, or Low)
203+
- **Location** — Affected file and line numbers
204+
205+
### Exploit Demonstration
206+
207+
- **PoC Test** — A ready-to-run Foundry test that reliably triggers the issue
208+
- **Test Location** — Path to the generated test file
209+
- **Summary** — Explanation of how the PoC demonstrates the vulnerability
210+
211+
---
212+
213+
!!! note "Processing Time"
214+
Scan duration depends on project size and complexity. Larger projects with more complex logic will take longer to analyze.
215+
216+
---
217+
218+
## Need Help?
219+
220+
If you encounter any issues or have questions, reach out:
221+
222+
**Email:** [contact@olympix.ai](mailto:contact@olympix.ai)

‎docs/CLI/index.md‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@ Welcome to the Olympix CLI usage guide! This guide will help you quickly get sta
88

99
When you run the Olympix CLI, you have access to several commands:
1010

11-
- **`analyze`**: Perform code analysis
12-
- **`generate-unit-tests`**: Generate unit tests
13-
- **`generate-mutation-tests`**: Generate mutation tests
14-
- **`login`**: Request access and log in to your account
15-
- **`show-vulnerabilities`**: Show the vulnerability types that the analyzer aims to find
11+
- **`analyze`**: Perform code analysis
12+
- **`generate-unit-tests`**: Generate unit tests
13+
- **`generate-mutation-tests`**: Generate mutation tests
14+
- **`bug-pocer`**: AI-powered vulnerability detection with automated PoC generation
15+
- **`login`**: Request access and log in to your account
16+
- **`show-vulnerabilities`**: Show the vulnerability types that the analyzer aims to find
1617
- **`version`**: Show CLI version
1718

1819
---
@@ -83,6 +84,24 @@ When generating mutation tests, you have the following options:
8384
- **`--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.
8485
*Default*: `.env`
8586
- **`-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.
87+
88+
---
89+
90+
## BugPoCer Options
91+
92+
When using the `bug-pocer` command for AI-powered vulnerability detection and PoC generation:
93+
94+
- **`-w | --workspace-path`**
95+
Defines the root project directory path.
96+
*Default:* current directory
97+
98+
- **`-env | --include-dot-env`**: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often needed for fork testing). To specify a custom env file, include the --env-file argument.
99+
100+
- **`--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.
101+
*Default*: `.env`
102+
103+
- **`-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.
104+
86105
---
87106

88107
## Usage Examples
@@ -97,6 +116,9 @@ generate-unit-tests [-w | --workspace-path <workspace directory>] [-ca | --confi
97116
# Generate mutation tests
98117
generate-mutation-tests [-w | --workspace-path <workspace directory>] [-p | --path <solidity file path>] [-t | --t <timeout>] [-env | --include-dot-env] [--env-file <env file path>] [-ext | --extension .<extension-to-include>]
99118

119+
# BugPoCer - AI-powered vulnerability detection
120+
bug-pocer [-w | --workspace-path <workspace directory>] [-env | --include-dot-env] [--env-file <env file path>] [-ext | --extension .<extension-to-include>]
121+
100122
# Login
101123
login [-e | --email <user email>]
102124
```
@@ -105,15 +127,18 @@ login [-e | --email <user email>]
105127

106128
## Helpful Links
107129

108-
- **[Installation](../Installation.md)**
130+
- **[Installation](../Installation.md)**
109131
Get started by installing the CLI binaries and the VSCode extension.
110132

111-
- **[Unit Test Generation](./Unit%20Testing.md)**
133+
- **[Unit Test Generation](./Unit%20Testing.md)**
112134
Learn how to generate unit tests for your smart contracts using the Olympix Unit Test Generator.
113135

114-
- **[Mutation Tests Generation](./Mutation%20Testing.md)**
136+
- **[Mutation Tests Generation](./Mutation%20Testing.md)**
115137
Find out how to generate mutation tests to assess your unit test quality.
116138

139+
- **[BugPoCer](./BugPoCer.md)**
140+
Learn about the AI-powered vulnerability scanner with automated PoC generation.
141+
117142
---
118143

119144
With these commands and options at your disposal, you're well-equipped to leverage Olympix for efficient static analysis and robust test generation. If you have any questions, our support team is ready to help at [contact@olympix.ai](mailto:contact@olympix.ai).

0 commit comments

Comments
 (0)