How Shepherd Works
This page walks through Shepherd's technical workflow from onboarding to results.
Step 1: Snapshot Build
Shepherd starts by reading onchain state to build a snapshot of your protocol:
Resolves deployed contract addresses
Maps proxy contracts to their current implementations
Extracts admin and upgrade authorities
Reads configuration values from storage and view functions
Identifies external dependencies (orcales, pools, routers)
Input: Deployed addresses + ABIs (minimum). Source code improves coverage and interpretation but isn't always required.
Output: A snapshot and twin fingerprint that anchors everything to onchain reality at a specific block.
Step 2: Knowledge Graph Construction
From the snapshot, source code, and ABIs, Shepherd build a structured model of your protocol:
Contracts, functions, and roles: What exists and who can call what
Value flows: How funds move between contracts
Dependency links: Which external protocols yours interacts with
Upgrade paths: Proxy patterns and admin surfaces
This graph is continuously updated as new information comes in from test runs and runtime traces.
Step 3: Fork and Twin
Shepherd creates an fork pinned to the snapshot's block number. This fork is your digital twin, a isolated high-fidelity replica of your protocol and its surrounding environment.
The twin preserves:
All contract state and balances
Current market conditions and liquidity
Cross-protocol interactions and composability
Step 4: Episode Execution
Shepherd runs episodes against the twin. Each episode tests a specfic hypothesis through actual transaction execution. Episodes are generated from 3 sources:
Hypothesis-driven
Specific theories from auditors, the team, or Shepherd's agents
Template-driven
Common DeFi exploit patterns applied to your architecture
Regression-driven
Re-running past findings after code changes to confirm fixes
During execution, agents:
Construct the attack transaction sequence
Execute each step on the fork
Record state changes, call traces, and balance diffs
Evaluate invariants
Capture the full result as an exploit proof (if successful) or a disproof (if the hypothesis doesn't hold)
Step 5: Results
For each episode, Shepherd produces:
Exploit proof or disproof: Did the attack work or not?
Transaction sequence: The exact calls made, in order
State diffs: What changed in balances and storage
Interactive execution graph: Visual representation of the attack path
Replay pack: A Foundry/Hardhat test you can run locally to reproduce the result
Findings are classified by severity based on exploitability and potential impact.
Step 6: Continuous Maintenance
For ongoing engagements, Shepherd's twin evolves with your protocol:
New snapshots are taken as you deploy upgrades or change parameters
Regression episodes re-test previous findings against updated code
New threat patterns observed across the ecosystem are tested against your twin
Results feed back into the knowledge graph, improving coverage over time
Last updated