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 where cargo build succeeds. A prebuilt target/deploy/*.so is needed only when the program is tested from TypeScript or its Rust tests load the compiled program (for example ProgramTest without a processor, LiteSVM’s add_program_from_file, or an .so path); then run anchor build (or cargo-build-sbf) locally first. 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 test 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.
--directed	Start a directed scan — investigate only the domains and custom directions you choose
--domains <id,...>	Comma-separated domains to investigate. Requires --directed
--directions-file <path>	File of custom directions. Requires --directed

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.

---

Directed Mode

A standard scan prioritizes the riskiest code across your whole scope. A directed scan focuses BugPoCer on what you care about: a set of risk domains, your own custom directions (specific questions about the code), or both. BugPoCer plans its work around those targets, and an independent scope review drops any finding that doesn’t connect to one of them before it’s verified or reported.

# Open the directed setup screen
olympix bug-pocer --directed

# Prefill it with domains and a directions file
olympix bug-pocer --directed --domains vaults,oracles --directions-file targets.md

Flag	Description
--directed	Enables directed mode. Skips the session picker and goes straight to a new directed session.
--domains <id,...>	Comma-separated domain IDs from the table below. Requires --directed.
--directions-file <path>	A file of custom directions. Requires --directed. Relative paths resolve from the directory you run the CLI in, not from -w.

Passing --domains or --directions-file without --directed is an error.

You can also start a directed scan from the session picker: choose Start a new session, then Directed scan.

Setup screen

Interactive runs open a setup screen before scope selection, prefilled with any flags you passed:

• Toggle domains with Space; the highlighted domain’s description is shown below the list.
• Add / replace directions file, Preview directions (page through each loaded direction), and Remove directions file.
• Continue to scope review once at least one domain or direction is selected.

Scope selection, diff mode, and your scope/ignore config still apply: directed mode decides what to look for within the code you’ve scoped. In non-interactive runs (--confirm-all, CI, or agent mode) the flags are used as given, so pass at least one domain or a directions file.

Domains

Domains are available for Solidity projects.

ID	Domain	Covers
tokens	Tokens & ERC standards	Token transfers, approvals, permit signatures, minting and NFT integration behavior
vaults	Vaults & yield strategies	Vault shares, deposits, withdrawals, yield strategies, fees and ERC-4626 accounting
lending	Lending & liquidations	Collateral, debt, interest, borrowing and liquidation safety
trading	Exchanges, liquidity & trading	Swaps, liquidity, routing, AMM hooks, slippage and trading-related price manipulation
staking	Staking & rewards	Stake accounting, reward distribution, delegation, slashing and withdrawals
oracles	Oracles & pricing	Price freshness, manipulation, normalization, derived prices and fallback behavior
bridges	Bridges & cross-chain messaging	Message authenticity, replay, finality and cross-chain asset accounting
governance	Governance & voting	Voting power, proposals, timelocks and governance execution
signatures	Signatures & authorization	Signed-message validation, replay protection, smart-wallet signatures and relayed authorization
upgrades	Proxies & upgrades	Initialization, upgrade authorization, storage compatibility and delegatecall behavior
access-control	Access control & permissions	Role assignment, privileged entry points, ownership, configuration setters and permission boundaries
external-calls	External calls & reentrancy	External interactions, callbacks, hooks, call ordering, reentrancy and return-value handling

Custom directions

A custom direction is one security question you want BugPoCer to answer about your code. BugPoCer plans its work around each question, looks for a concrete exploit path, and only reports findings that connect to one of your directions or domains. Directions work for every supported language (domains are Solidity-only).

What to write

Write each direction as a specific, answerable question about your own code: name the contract or function, the actor, and the outcome you’re worried about. One concern per direction.

Less useful	Better
Check for reentrancy.	Can a contract re-enter SavingsAccount.withdraw() through the _sendFunds callback and claim the loyalty bonus twice?
Look at access control.	Can anyone other than the owner call resetHasWithdrawnBonus() to re-arm another user's bonus?
Oracle issues?	Can LendingPool.borrow() use a Chainlink price older than the heartbeat and let a user borrow more than their collateral allows?
Audit the vault.	Can the first depositor into an empty Vault inflate the share price with a donation so later deposits round down to zero shares?

Tips:

• Name code, not categories. A broad topic such as “reentrancy” is better covered by selecting a domain; use directions for the questions only you know to ask.
• State the harm. “…and drain more than they deposited”, “…and block withdrawals for everyone” tells BugPoCer what a successful exploit looks like.
• Add context on continuation lines — assumptions, trusted roles, invariants you rely on (“the owner is a 3/5 multisig”, “fees are capped at 5%”).
• Don’t restate out-of-scope code. Directions narrow what to look for; they don’t add files to the scan. Make sure the contracts you mention are in the scope.

File format

Pick the format by file extension: .json is parsed as JSON; anything else (.md, .txt, no extension) is parsed as Markdown/plain text. Files must be UTF-8.

Markdown or plain text

• Each bullet (-, *, +) or numbered item (1. or 1)) starts a new direction.
• Indented lines after a bullet continue that direction (use them for context).
• A plain paragraph without a bullet is one direction; consecutive lines join until a blank line.
• Headings (# … ######) and blank lines are ignored, so you can organize the file freely.
• Nested bullets become separate directions, not sub-points.
• Don’t wrap the content in a code fence — the ``` lines would be read as directions.

# Withdrawals

- Can a contract re-enter SavingsAccount.withdraw() through the _sendFunds
  callback and claim the loyalty bonus more than once?
  The bonus flag is only set after the external call.

# Admin functions

- Can anyone other than the owner call resetHasWithdrawnBonus() to re-arm
  another user's bonus?

This file contains two directions.

JSON

An object with a targets array of non-empty strings; other keys are ignored. A JSON Schema is available for editor validation and autocompletion:

{
  "$schema": "https://olympix.github.io/schemas/directed-targets.schema.json",
  "targets": [
    "Can a contract re-enter SavingsAccount.withdraw() through the _sendFunds callback and claim the loyalty bonus more than once?",
    "Can anyone other than the owner call resetHasWithdrawnBonus() to re-arm another user's bonus?"
  ]
}

Limits and errors

Rule	Error if broken
At least one direction (or a selected domain)	Select at least one domain or add a directions file.
At most 32 directions, each non-empty and at most 8,000 characters	Supply at most 32 non-empty directions of at most 8000 characters each.
At most 32,000 characters in total	Directions must contain at most 32000 characters in total. / Directions file is too large.
JSON must be an object with a targets array of strings	Directions JSON must contain a targets array of strings.

Relative paths resolve from the directory you run the CLI in, not from -w. In the setup screen, use Preview directions to page through exactly what was parsed before you continue.

Quota and coverage

Directed scans use the same Full or Diff run quota as a standard scan, depending on their code scope. A directed scan with no findings is not proof that the targeted area is safe — BugPoCer may miss relevant paths or fail to establish a real bug.

Directed sessions are labelled DIRECTED in the session picker.

---

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. The sweep resolves imports the way forge does: through your declared remappings and then forge remappings, so a dependency nested under lib/ (for example forge-std inside lib/openzeppelin-contracts/lib/) counts as found.
• 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 only when it’s tested from TypeScript or its Rust tests load the compiled program; 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 Needs Further Review, never Verified (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. You’re asked whether it’s a Standard scan or a Directed 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
k	Kill the selected session
c	Clone a finished session (completed, killed or expired) into a new one with the same settings
← / →	Previous / next page
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. The picker shows it as SCANNING
InitialScanCompleted	Scan finished, findings available for review
Killed	Killed by you, or when validation timed out, before the scan completed. No findings; clone it (c) to start again with the same settings
ContextExpired	Ended before the scan completed. No findings; clone it (c) to start again with the same settings

Connecting to a session whose scan hasn’t finished says the scan is still running, rather than showing an empty findings list. Reconnect once it reaches InitialScanCompleted. A killed or expired session says it ended without findings.

Killing a session

To terminate an active session — one started by mistake, or one you no longer want to continue — use:

olympix kill-bp-session -s <session-id>

The CLI confirms whether the session was actually running when killed, or had already completed. To find the session ID, run olympix list-bp-sessions (prints each session’s ID and status) or olympix sessions --agent.

The command also works in agent mode, emitting a session_killed event.

---

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, BugPoCer leaves out:

• everything under the root lib/ directory

• test and script files: *.t.sol, *.s.sol, and the test and script directories set in foundry.toml

• any file with a test, tests, mock, mocks, example, examples, script, scripts or certora path segment

• any file with one of these dependency path segments:

  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

The scope picker applies the same rules, so it lists only code BugPoCer scans.

For Rust projects: target, test, tests, mock, mocks, example, examples, script, scripts, certora, fixtures, benches, vendor, node_modules. Each workspace member is listed once, and members in [workspace].exclude are left out.

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

BugPoCer assessment and your verdict

Every finding carries two separate calls: what BugPoCer concluded, and what you decided.

BugPoCer assessment: how far BugPoCer got in proving the finding.

Assessment	Badge	Meaning
Verified	VERIFIED (green)	BugPoCer confirmed the bug with a proof-of-concept exploit that runs against your project’s code and shows the harm.
Needs Further Review	NFR (yellow)	BugPoCer flagged the issue but couldn’t prove it: the PoC didn’t compile, ran without showing harm, or didn’t exercise your project’s code; the project build failed; or verification needed context it didn’t have. These still warrant a human look.
Not Exploitable	NOT EXPLOITABLE (grey)	BugPoCer investigated the finding and ruled it out.

Your verdict: ACCEPTED (green), REJECTED (grey) or NOT REVIEWED (grey), set from the findings pager. Your verdict takes precedence: a finding you accept shows and counts as Verified, and one you reject as Not Exploitable, in the pager, its counts and every export. The reviewer badge stays beside it, so you can always tell a person made the call.

Not Exploitable findings are hidden by default

Findings BugPoCer ruled out don’t appear in the pager or its counts; the header shows how many are hidden. To show them, open Settings from the main menu (s) and turn on Show Not Exploitable findings, or set "showNotExploitableFindings": true in ~/.opix/config.json. Findings you rejected yourself always stay visible. Exports aren’t affected: they use the filter you pick when exporting.

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.

Finding groups

BugPoCer groups findings that share one root cause and one fix, for example the same access check missing from several functions. Each member is still its own finding with its own severity, assessment and verdict; the group tells you they are one defect to fix once.

• In the pager, every member carries a GROUP badge, and the group’s lead finding carries GROUP*. The lead is always a Verified finding when the group has one. Members are listed together, lead first, and the group sorts by its most severe member. Press Enter on a member to see the group’s title and shared root cause.
• In the Markdown and PDF exports, a group is one entry: a heading with the group’s title, the root cause and the fix, then its members lettered a), b), …. The group is filed under the severity of its most severe member, so a Medium member can appear under High.

Interactive findings pager

The pager lists ten findings per page. The header shows the session, the number of findings (and how many Not Exploitable ones are hidden), and the count per assessment: Verified, Needs review, and Rejected, or Not exploitable once you’ve chosen to show those.

Each row reads left to right: severity, BugPoCer’s assessment, the group badge (grouped findings only), your verdict and its reason if you gave one, then the unit and vulnerability name:

> [  1]  HIGH   VERIFIED   GROUP*   ACCEPTED  Vault :: missing_access_control_on_withdraw
  [  2]  MEDIUM   NFR   GROUP   NOT REVIEWED  Vault :: missing_access_control_on_sweep
  [  3]  LOW   VERIFIED   NOT REVIEWED  Vault :: rounding_direction_favours_user

Badge	Meaning
HIGH MEDIUM LOW INFO	Severity. INFO marks an informational finding and is listed in the legend only when the session has one.
VERIFIED NFR NOT EXPLOITABLE	BugPoCer’s assessment, after your verdict is applied.
GROUP* / GROUP	The lead / another member of a finding group.
ACCEPTED REJECTED NOT REVIEWED	Your verdict.

The footer lists the common keys. Press h to show every key plus a badge legend, and h again to hide them.

Key	Action
↑ / ↓	Select a finding (moves to the next or previous page at the edges)
← / →	Previous / next page
Enter	Expand / collapse the selected finding: location, description, verdict reason, group title and root cause, PoC summary and a PoC preview
o	View the finding’s PoC full-screen
y	Accept the finding (prompts for an optional reason)
n	Reject the finding (prompts for an optional reason)
Space	Flip your verdict between accepted and rejected. On a finding you haven’t reviewed, it records the opposite of BugPoCer’s raw true/false call; on a Needs Further Review finding, use y or n instead
Backspace	Clear your verdict
t	Show only findings BugPoCer called a true positive. This is its raw call, so it can include Needs Further Review findings. After v, show only the findings you accepted
r	Show only findings that need review
v	Switch what t filters on: BugPoCer’s call, or your accepted verdicts
b	Back to the session list
q	Back to the main menu (ends the command if you didn’t open the findings from the main menu)
Esc	Back to the main menu
h	Show or hide all keys and the badge legend

---

Exporting Results

Every export option (the PDF, Markdown, and PoC files exports) first asks which findings to include, on two screens (Space toggles, Enter confirms, q cancels).

Screen 1: assessment and reviewer verdict

• BugPoCer Assessment: Verified (default: on), Needs Further Review (default: on), Not Exploitable (default: off)
• Reviewer Verdict: Accepted or not yet reviewed (default: on), Rejected by a reviewer (default: off)

Screen 2: severity

• High, Medium, Low (default: all on). Informational findings count as Low.

At least one option must be selected in each group. The assessment here already reflects your verdicts, so a finding you accepted counts as Verified.

Markdown export — lightweight 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 up to two files to your current working directory:

• findings_<sessionId>_<timestamp>.md: Verified and Needs Further Review findings
• ruled_out_<sessionId>_<timestamp>.md: Not Exploitable findings, when you include them

A group is never split across the two: it goes in the findings file if any of its members is Verified or needs review.

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
• Findings under ## High, ## Medium and ## Low, with groups as described in Finding groups. Each finding shows its severity, assessment and your verdict as badges (for example [High] [Verified] [Accepted]), then the unit name, location, description, your verdict reason (if set), the evidence (the affected code), and the PoC summary for findings BugPoCer verified with a PoC

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.

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
• Ingested Documentation — the documents BugPoCer read: docs, Certora specs and PDFs found in the repository, plus any you added
• Summary — scan start/complete/generation times, a severity bar chart split by assessment, an index of the issues in the report (a group counts once), and glossaries of the severity levels and assessments
• Findings — Verified and Needs Further Review findings, banded by severity. Each finding has chips for its severity, assessment and your verdict, then the unit, location, description, your verdict reason (if set), evidence, and for findings BugPoCer verified with a PoC, the PoC summary and the full PoC code in its own language (Solidity PoCs are syntax-highlighted). A group appears as one issue with a root cause / fix card and lettered members
• Findings Ruled Out — Not Exploitable findings, when you include them, in the same layout

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

PoC test files

One file per exported finding that has a PoC, written under pocs_<sessionId>/ in your current working directory. Each file mirrors the path the scanner built it at, so you can copy the folder’s contents straight into your project (cp -r pocs_<sessionId>/* .); findings from older scans use a flat <unit>_<vulnerability> file name instead. Extensions follow the project’s test framework: .t.sol for Foundry, .js or .ts for Hardhat, .rs for Rust / Anchor, .ts for TypeScript-tested Anchor projects, .cairo for Starknet Foundry. In a Rust workspace a PoC lands in the tests/ directory of the package that owns the finding (for example program/tests/), so it can use that crate.

---

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). A finding can occasionally be marked Informational; the pager shows it as INFO and exports count it as Low
• Location — affected file and line numbers

Exploit Demonstration

• PoC Test — a ready-to-run test in the project’s own framework (Foundry, Hardhat, Rust / Anchor or Starknet Foundry) 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