BugPoCer

BugPoCer is an AI-powered internal audit tool that automates end-to-end vulnerability exploitation for smart contracts on Solidity, Rust (Anchor/Solana and CosmWasm/Cosmos), and Cairo (StarkNet) — moving beyond static warnings to deliver concrete, verifiable Proof-of-Concept (PoC) exploits.

---

Overview

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 PoC test in the project’s native framework — Foundry (.t.sol), Rust cargo test (.rs), or Starknet Foundry snforge (.cairo) — that reproduces the exploit under realistic attack conditions.

Key Capabilities

• Automated Vulnerability Detection — AI-driven protocol scanning
• Project Context and Invariant Building — Approve inferred project context
• PoC Generation — Automatically creates runnable PoC test files that demonstrate exploits

---

Prerequisites

Project Requirements

• A project in one of the supported stacks that builds and tests locally before you start a scan. BugPoCer ships your locally-built artifacts and vendored dependencies in the upload, so the build must succeed on your machine first:
  • Solidity — a Foundry project where forge test succeeds (run forge install locally first), or a Hardhat project where npx hardhat compile succeeds with node_modules installed (Hardhat 3 is supported).
  • Rust / Anchor (Solana) — a Cargo.toml (with solana / anchor-lang / solana-program dependencies) or Anchor.toml project. Run anchor build (or cargo-build-sbf) locally so target/deploy/*.so is on disk. For private crates, run cargo vendor locally so vendor/ ships with the upload. TypeScript-tested Anchor projects also need yarn install (or equivalent) locally first so node_modules/ ships.
  • Rust / CosmWasm (Cosmos) — a Cargo.toml project using cosmwasm-std (or provwasm) where cargo build succeeds locally. For private crates, run cargo vendor and commit Cargo.lock so the build can run offline. No pre-built .so is required.
  • Cairo / StarkNet — a Scarb.toml project. Run scarb build and snforge test locally first. For private packages, vendor under vendor_cairo/ locally.
• An Olympix account — log in with olympix login -e <email> (or olympix login-sso -e <email> if your organization uses SSO) before starting a scan (see Installation)

Access

BugPoCer is a premium feature, granted per account. Each account has separate allowances for full-repo scans and diff scans; when you reach an allowance, contact contact@olympix.ai to request access or a higher limit.

---

Pipeline Overview

BugPoCer runs as a multi-stage pipeline. The analysis itself happens server-side, so most stages are asynchronous — you can close the CLI between stages and reconnect whenever an email tells you it’s your turn again.

#	Stage	What happens	Session state	Email sent
1	Start session	You run olympix bug-pocer, pick a project, name the session, select scope, and optionally attach additional documentation. Nothing is committed server-side until you press Enter to submit the documentation step — at that point the session is created, transitions to ChatStarted, and the Scan Started email fires. Cancelling during scope selection or the documentation step leaves no session behind.	— → ChatStarted	BugPoCer Scan Started
2	Context building	Server scans your uploaded code (including any documentation found in the repo) and infers project identity, intent, core functions, design goals, patterns, invariants, and security assumptions.	ChatStarted	—
3	Context validation	You review and correct the inferences the engine isn’t confident about.	ValidationRequested	[Action Required] Validate Project Context (or the …(Partial) variant if some context agents fell short). You have 72 hours to respond; if you don’t, reminder emails fire inside the window and the session is killed when it expires.
4	Initial scan	Validated context is fed into the vulnerability scan and PoC generation.	ValidationCompleted	—
5	Findings review	Reconnect, browse findings, mark verdicts, export reports.	InitialScanCompleted	BugPoCer Initial Scan Complete

---

Quick Start

1. Log in (once): olympix login -e <email> — or olympix login-sso -e <email> for SSO orgs.

2. Start a scan from your project root: olympix bug-pocer → Start new session → name it → pick scope → (optionally) attach documentation → press Enter to submit. Your session is created at submission.

3. Wait for the validation email (subject: [Action Required] Validate Project Context).

4. Validate: run olympix bug-pocer again, reopen the session, confirm or correct each inference, then submit.

5. Wait for the scan-complete email (subject: BugPoCer Initial Scan Complete).

6. Review findings, record your verdicts, and export results (Markdown / PDF / PoC .sol files).

---

CLI Command

From your project root:

Quick Start

olympix bug-pocer

Available options:

Option	Description
-w, --workspace-path	Root project directory path (default: current directory)
-env, --include-dot-env	Include .env file for fork testing secrets (RPC URLs, API keys, etc.)
--env-file	Path to a custom .env file (requires -env)
-ext, --extension	Additional file extensions to include (can be used multiple times)
-rc, --rebuild-context	Force a fresh project-context build, ignoring the context cache
-sp, --skip-preflight	Skip the local pre-flight validation (build check) before upload
-ca, --confirm-all	Auto-confirm scope, documentation, cache, and pre-flight prompts (non-interactive; implied in CI)
--diff-base <git ref>	Enable diff mode — scan only the code changed relative to this commit, branch, or tag
--diff-target <git ref>	Other end of the diff (must be the checked-out HEAD); defaults to the working tree. Requires --diff-base
--framework foundry|hardhat	Pin the framework for a multiframework repo — one with both a foundry.toml and a hardhat.config.*. No effect on single-framework repos.

Including env variables

If your tests need RPC URLs, API keys, private keys, etc., pass them with -env (reads from .env) or --env-file <path> for a custom file. Use whatever .env format your project’s test framework already reads (e.g. KEY=value lines).

This is the recommended way to pass env variables — the file is encrypted in transit with an extra RSA layer on top of the regular channel encryption.

---

Diff Mode

By default BugPoCer scans your whole project scope. Diff mode narrows a scan to only the source code that changed between two git references — ideal for auditing a single pull request or feature branch without re-scanning the entire codebase.

# Scan only what changed on the current branch since it diverged from main
olympix bug-pocer --diff-base main

# Diff an explicit range (the target must be the checked-out commit)
olympix bug-pocer --diff-base v1.2.0 --diff-target HEAD

Flag	Description
--diff-base <git ref>	Enables diff mode. Commit, branch, or tag to diff against — BugPoCer scans only the code that changed relative to it.
--diff-target <git ref>	The other end of the diff. Optional; defaults to your working tree. If set, it must be the currently checked-out commit (HEAD).

How it behaves:

• The diff is taken from the merge base of --diff-base and the target (the same “what this branch changed” view as a pull request), so commits that landed on --diff-base after you branched aren’t counted.
• Scope comes from the changed lines — only the functions, contracts, and libraries whose lines overlap the diff are selected. Diff mode skips the interactive scope picker and instead prints the source files it derived from the diff. Any BugPocerScopePaths / BugPocerIgnorePaths from your config still apply on top.
• The analysis is change-aware, not just change-scoped — each selected unit is still read in full for context, but the actual diff hunks (the removed - and added + lines) are fed into the scan and weighted heavily. The engine reasons about what each change introduced: new attack surface, weakened or removed checks and invariants, and interactions between the changed lines and the surrounding unchanged code.
• Only source files in your project language (.sol, .rs, .cairo) are considered; deleted files are dropped and renames are followed.
• Untracked files are not scanned — git add or commit them first to include them (the CLI warns about any it skips).
• An empty diff (no changed source files) exits before a session is created, so an unchanged range never starts a billable scan.
• Refs are validated locally before anything uploads, so a bad ref, a missing --diff-base, or a non-git workspace fails instantly.

Uncommitted changes vs. an explicit --diff-target

If you pass an explicit --diff-target commit while your working tree has uncommitted changes, the scan reads files from disk and could misreport changed line numbers against that commit. The CLI detects this and asks whether to compare against your working tree (recommended) or the committed --diff-target.

---

Pre-flight Validation

Before anything is uploaded, the CLI runs a local pre-flight check that confirms your project actually builds. Because BugPoCer ships your locally-built artifacts, a project that doesn’t compile on your machine can’t be analyzed — pre-flight catches that up front instead of failing server-side.

What it checks, by framework:

• Foundry — forge is on your PATH, git submodules are present, foundry.toml remappings resolve, an import-resolution sweep passes, and forge build succeeds.
• Hardhat — node_modules and package.json are present and hardhat compile succeeds.
• Anchor (Solana) / CosmWasm / Cairo — build artifacts exist and the manifest (Cargo.toml / Anchor.toml / Scarb.toml) is readable. Anchor needs a locally built target/deploy/*.so; CosmWasm builds with cargo build; Cairo with scarb build.

If a blocking issue is found, the CLI prints remediation steps and asks whether to continue anyway or abort. In non-interactive runs (CI, PR mode, or --confirm-all) it logs a warning and proceeds.

Skip the pre-flight check entirely with -sp / --skip-preflight.

Server-side build check

After upload, the backend runs its own build (forge build / npx hardhat compile / cargo build / scarb build; up to a ~30-minute cap). A successful build is not required to scan. If the build fails, the scan still runs and findings are still reported — but proof-of-concept generation is skipped, so those findings can only reach Unverified, never a confirmed True Positive (a non-compiling test can’t prove exploitability). You’re prompted [c]ontinue with findings only | [k]ill session (non-interactive runs continue automatically). For full results with PoCs, make the build pass locally and start a new scan.

---

Context Cache

BugPoCer caches the project context it builds so repeat scans don’t start from scratch. The cache is keyed on a fingerprint of your source files — dependencies under lib/ and node_modules/ are excluded so they don’t skew the comparison — so the CLI knows whether your code has changed since the last run:

• Exact match (identical source fingerprint) — interactively you’re offered Approve (reuse as-is), Update (reuse as a baseline and fold in new docs), or Rebuild. In non-interactive runs the cache is reused automatically.
• Partial match (source overlaps a prior run by at least 80%) — the cached context seeds a faster incremental rebuild.
• No cache (below 80% overlap, or no prior run) — context is built from scratch.

Pass -rc / --rebuild-context to ignore the cache and force a fresh build every time.

Cache limit

Projects with more than 100,000 files are too large to fingerprint and skip the cache entirely (this file count is separate from the ~100,000-token budget for attached documentation).

---

Session Picker

Running olympix bug-pocer on a project with existing sessions shows the session picker:

• Start a new session — begin a fresh scan.
• Return to an active session — continue an in-progress scan.
• Reconnect to a past session — review results from a completed scan.

Key	Action
↑ / ↓	Navigate sessions
Enter	Open the selected session
n	New session
r	Refresh
q	Quit

Session status reference

Status	Meaning
Pending	Queued — the scan has been submitted and is waiting for an available worker to start (may sit here longer under heavy load)
ChatStarted	Session created, context building in progress
ValidationRequested	Waiting for you to validate project context
ValidationCompleted	Context approved, initial scan running
InitialScanCompleted	Scan finished, findings available for review

---

Scope Selection

When you start a new session, the CLI displays an interactive scope picker so you can decide which files BugPoCer analyzes. The tree is pre-filtered by the default ignore list (see Scope and ignore config) and by any BugPocerScopePaths / BugPocerIgnorePaths in your olympix-config.json.

What gets deep-scanned

BugPoCer ranks in-scope code by criticality and deep-scans the highest-impact units first (a diff scan covers a focused subset). The scope picker’s footer shows how many units will actually be deep-scanned out of the total in scope (“N of M”) — and, as it notes, findings may span a wider scope if other units are affected. Issues involving units outside the selected scope can still be reported.

Key	Action
Enter	Expand/collapse the selected item
i	Include item
x	Exclude item
Space	Toggle include/exclude
/	Search
a	Expand all
z	Collapse all
h	Hide/show excluded items
e	Exclude all
u	Include all
b	Browse more (add items not shown by default)
s	Save and continue
Esc	Cancel

Scope and ignore config

In addition to the interactive picker, you can pre-seed scope with a config file at the project root:

{
    "BugPocerScopePaths": [
        "src/core/",
        "src/vaults/vault.sol"
    ],
    "BugPocerIgnorePaths": [
        "src/examples/",
        "src/mocks/mock.sol"
    ]
}

Option	Description
BugPocerScopePaths	Positive scoping — if defined, BugPoCer will ONLY consider files whose paths start with one of these entries. Leave empty or omit to consider all files.
BugPocerIgnorePaths	Paths to exclude. Any file whose path starts with one of these entries is ignored.

How scope and ignore interact

1. If BugPocerScopePaths is defined and non-empty, only files matching a scope path are considered.
2. From the scoped files, any matching BugPocerIgnorePaths are excluded.
3. If BugPocerScopePaths is empty or omitted, all files are in scope (minus ignores).
4. The interactive scope picker starts from this config — you can further refine it there.

Default ignore list

BugPoCer automatically excludes common non-production and dependency paths. Entries are matched as case-insensitive path segments — a whole /-delimited path segment must match, not an arbitrary substring.

For Solidity projects, any file with one of these path segments is ignored:

node_modules, dependencies, forge-std, ds-test, openzeppelin, openzeppelin-contracts, openzeppelin-contracts-upgradeable, openzeppelin-foundry-upgrades, solmate, solady, prb-math, prb-test, murky, permit2, erc4626-tests, erc6900, v2-core, v2-periphery, v3-core, v3-periphery, v4-core, v4-periphery, uniswap-v2, uniswap-v3, uniswap-v4, aave-v2, aave-v3, chainlink, chainlink-brownie-contracts, balancer-v2, curve

For Rust projects: target, test, tests, mock, mocks, example, examples, node_modules.

For Cairo projects: target, test, tests, mock, mocks, mock_contracts, example, examples, node_modules, .snfoundry_cache.

Difference from other Olympix tools

BugPoCer does not use the general IgnoredPaths, TrustedPaths, TrustedVariables, or TrustedContracts options. Use BugPocerScopePaths and BugPocerIgnorePaths instead.

---

Adding Project Documentation

After you save scope, BugPoCer gives you a chance to attach additional documentation — material that lives outside the repository and wouldn’t otherwise reach the engine.

BugPoCer already reads in-repo docs automatically

During context building, the server ingests documentation it finds in your codebase on its own: README.md and AGENTS.md at the project root, every *.md file under docs/, and other .md files elsewhere in the tree (truncated for very long ones). You don’t need to re-paste any of that here.

Key	Action
n	Add free-text notes
l	Add a documentation link (URL)
f	Load a local file (.txt, .md, or .pdf)
d	Add a folder of docs — recursively imports the documentation files found under a directory

What to add here

Think private or external context: internal design docs, threat models, audit scopes, Notion pages, architecture diagrams exported to text, protocol specs hosted elsewhere, trust assumptions that aren’t written down in the repo. Anything that explains how the system is supposed to behave but doesn’t live in a .md file in the codebase. This material is one of the biggest levers on result quality — the engine can read your code but it cannot read your whiteboard.

All attached documentation shares a combined budget of roughly 100,000 tokens; the UI shows how much headroom is left as you add items.

Press Enter to submit. This is the point at which your session is created server-side (ChatStarted) and the BugPoCer Scan Started email fires. If you quit before this step, no session is created.

---

Context Validation

Once the server has built its understanding of your project, you’ll receive the [Action Required] Validate Project Context email. Reconnect with olympix bug-pocer, open the session, and walk through the items the engine wants you to confirm.

What gets validated

BugPoCer infers nine categories of context:

• Identity — what the project is (name, type)
• Intent / Description — what the project does
• Core Functions — each key piece of functionality (one item per function)
• Design Goals — each intended design goal (one item per goal)
• Patterns — architectural and code patterns detected
• Invariants — properties that must always hold (one item per invariant)
• Design Decisions — documented intentional behaviors and known limitations (one item per decision)
• Security Assumptions — trust boundaries and assumptions about external entities
• Dependencies — external libraries and protocols the project relies on

Inferences the engine is already confident about are auto-confirmed and don’t appear in the validation queue. You only see the items the engine is unsure of.

Per-item actions

Each validation item shows the engine’s inference, a confidence score, and up to three suggested alternatives.

Key	Action
y	Confirm the inference is correct
n	Reject — then enter a custom replacement
1 – 3	Pick one of the suggested alternatives
0	Enter a custom answer from scratch
e	Expand / collapse the alternative options
← / →	Navigate between items
d	Download the context as Markdown
Enter	Submit all validations (enabled once every item has an answer)

Editing the project context directly

Alongside the per-item TUI, BugPoCer writes the full project context object to your workspace so you can read or edit the whole thing in one place:

File	Purpose
.opix/project-context.json	The complete context object — identity, intent, patterns, invariants, security assumptions, etc. Edit this file directly to mutate the context; your edits are picked up next time you open the session.
.opix/.project-context-state.json	Validation progress for the current request (which items you’ve confirmed, selected alternatives, custom values).

Both files persist across CLI restarts. If you close the CLI mid-validation, the next time you open the session within the 72-hour window you’ll see a “Found existing validation progress (X of Y items validated). Resume?” prompt and pick up exactly where you left off. If you’ve already answered every item, you’ll drop straight into the final review phase before submission.

Why validation matters

Your feedback tells the engine what’s intentional vs. what might be a vulnerability. Accurate context means more real findings and fewer false positives. Treat validation as part of the scan, not paperwork after it.

Once you submit, the session transitions to ValidationCompleted and the initial scan begins. You can close the CLI — the BugPoCer Initial Scan Complete email will tell you when results are ready.

---

Reviewing Findings

When the scan completes, reopen the session from the picker. You’ll land on a menu:

Option	Action
[0]	Display Findings (interactive pager)
[1]	Generate and Save PDF Report
[2]	Save Findings (Markdown)
[3]	Save PoCs (one file per finding)
[4]	Back to Sessions

Verdict terminology

There are two distinct classifications attached to every finding: what the engine thinks, and what you think.

Engine classification — determined by the engine and whether it could machine-verify the exploit:

• True Positive (TP) — the engine confirmed the bug and its generated PoC compiled and reproduced the exploit.
• Unverified — the engine flagged the issue but the PoC did not compile (or the Foundry build failed). Exploitability isn’t machine-verified, so these still warrant a human look.
• False Positive — the PoC compiled but did not reproduce the bug.

TP vs Non-TP in the CLI display

The interactive findings pager collapses this into a binary badge: TP (green) for confirmed true positives, NON-TP (yellow) for everything else. Unverified findings are folded into NON-TP in the pager — you can tell them apart by reading the finding’s PoC summary. The exported reports (PDF and Markdown) break out all three categories separately.

User verdict — your own verdict on each finding, displayed beside the engine badge in the pager as VERDICT: TP / VERDICT: NON-TP / VERDICT: — (unset). User verdicts are stored independently of the engine’s classification.

Record your verdicts

Taking the time to mark each finding pays off twice. Your verdicts show up in every export (so the PDF/Markdown you hand off is already triaged), and they feed back into BugPoCer to improve your future scans on similar code.

Interactive findings pager

Key	Action
↑ / ↓	Navigate findings / page
← / →	Previous / next page
Enter	Expand / collapse a finding
o	View the generated PoC full-screen
y	Mark as true positive (prompts for an optional reason)
n	Mark as false positive (prompts for an optional reason)
Space	Cycle user verdict
Backspace	Clear user verdict
t	Toggle TP-only filter
v	Toggle filter source (engine verdict vs. user verdict)
b	Back to menu
q	Quit the findings view

---

Exporting Results

Every export option (the PDF, Markdown, and PoC files exports) walks you through a two-stage filter dialog first.

Stage 1 — finding category (Space toggles, Enter confirms):

• True Positives (default: on)
• Unverified (default: on)
• False Positives (default: off)

Stage 2 — severity (Space toggles, Enter confirms):

• High (default: on)
• Medium (default: on)
• Low (default: on)

At least one category and at least one severity must be selected.

Markdown export — lightweight per-category report

The Markdown export is a stripped-down version, not the full audit report. It’s meant for sharing a filtered list of findings without the full methodology/scope/invariants/assumptions wrapper.

It writes one file per selected category (so you may get up to three files in a single export):

• true_positives_<sessionId>_<timestamp>.md
• unverified_<sessionId>_<timestamp>.md
• false_positives_<sessionId>_<timestamp>.md

Each file contains:

• A title and scan metadata (session ID, scan start/complete times, report generation time, repository, commit short SHA, branch)
• Total finding count and a Foundry-build-failure disclaimer if relevant
• Per-finding blocks ordered by severity, each with the severity badge, vulnerability name, unit name, location, description, your user verdict (if set) with optional reason, and the PoC summary

The PoC code itself is not inlined in the Markdown export — use the PoC export to get the PoCs as standalone files, or use the PDF export for a single document that includes everything. Files are written to your current working directory.

PDF export — full audit-style report

This export produces an audit-style PDF suitable for handing to stakeholders or clients. It’s generated server-side from the same underlying scan data and includes everything the Markdown export leaves out.

The PDF contains:

• Cover page — Olympix branding, repository org (when available), and the scan’s completed/partial status
• Table of contents — auto-generated
• About — methodology, disclaimer (with a Foundry-build-failure note if relevant), and project overview drawn from your validated context
• Scope — repository, commit short SHA, branch, scanned-unit count, and the list of units analyzed
• Summary — scan start/complete/generation times, a High/Medium/Low severity table for true positives, a pie chart of TP findings by severity, and severity-level definitions
• True Positive Findings, grouped by severity, each with vulnerability name, unit, location, description, your user verdict + reason (if set), PoC summary, and the full PoC Solidity code with syntax highlighting
• Unverified Findings, same structure, for engine-flagged issues whose PoC didn’t compile
• False Positive Findings, same structure

Saved to your current working directory as BugPoCer_Scan_Report_<sessionId>_<timestamp>.pdf.

PoC test files

One file per finding that has a compilable PoC, written under your workspace so you can drop it straight into your test suite. Extension is inferred from the PoC contents: .t.sol for Foundry tests, .rs for Rust / Anchor tests, .cairo for Starknet Foundry tests.

---

Scan Report Fields

Each finding in the BugPoCer scan report includes:

Vulnerability Details

• Description — what the vulnerability is and how it can be exploited
• Severity — risk level (High, Medium, or Low)
• Location — affected file and line numbers

Exploit Demonstration

• PoC Test — a ready-to-run Foundry test that reliably triggers the issue
• Test Location — path to the generated test file
• Summary — explanation of how the PoC demonstrates the vulnerability

Processing Time

Scan duration depends on project size and complexity. Larger projects with more complex logic will take longer to analyze.

---

Need Help?

If you encounter any issues or have questions, reach out:

Email: contact@olympix.ai