> For the complete documentation index, see [llms.txt](https://shepherd-1.gitbook.io/shepherd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shepherd-1.gitbook.io/shepherd/key-features.md).

# Key Features

## Autonomous Security Testing

Shepherd runs end-to-end smart contract assessments without needing human orchestration. Our agents autonomously handles:

* **Contract discovery and information gathering**\
  Shepherd autonomously collects deployed bytecode, verified source code, ABIs, and function selectors from public block explorers or user-submitted sources. It resolves proxy contracts, factory deployments, and upgradeable patterns, ensuring complete coverage of multi-contract systems and storage layouts before initiating tests.

***

* **Attack hypothesis generation**\
  Using past exploit memory and programmatic composability analysis, our Planner Agent formulates hypotheses about potential vulnerabilities. It scans for weak permissioning, control flow gaps, and dangerous architectural assumptions, proposing prioritized attack strategies based on likelihood of exploitation and severity.

***

* **Simulated exploit execution**\
  The Executor Agent deploys malicious payloads and simulates attacks inside a forked testnet environment. These simulations mirror realistic conditions, including flash loan setups, token callbacks, delegatecall chains, and time-based manipulations — all without touching mainnet. Shepherd safely executes attacks against live contract logic.

***

* **Continuous feedback loop**\
  The Reflector Agent monitors on-chain effects and adjusts the strategy in real time. Failed or partial exploits trigger deeper reasoning and reruns with modified calldata or gas usage. This feedback loop lets Shepherd refine its hypotheses over time, simulating persistent adversarial behavior with memory and state awareness.

***

* **Actionable reporting**\
  Once a vulnerability is validated, Shepherd generates clear, replayable PoCs along with human-readable explanations, attacker contract logic, and trace-backed reasoning. Each report includes mappings to common vulnerability classes and actionable remediation suggestions, making findings digestible to both developers and auditors.

## Real-World Attack Coverage

Shepherd is built to simulate *actual exploit behavior*, not just scan for theoretical risks. While traditional tools stop at detection, Shepherd validates whether vulnerabilities can truly be exploited — under realistic conditions and across full protocol stacks.

* **Dynamic simulations**\
  Shepherd executes adversarial interactions in forked testnets, modeling attacker behavior at the transaction level. By deploying malicious contracts and triggering on-chain edge cases, it reveals whether vulnerabilities are practically exploitable — not just present in code.

***

* **Composability awareness** \
  Many critical vulnerabilities only emerge across contract boundaries. Shepherd models composable threats by tracing interactions through proxies, multi-contract flows, and upgradable patterns. Support for factory-discovered deployments and upgrade simulation is in active development, giving Shepherd a protocol-level view attackers often exploit.

## [Explainable & Actionable Results](#user-content-fn-1)[^1]

##

Shepherd is designed to not only find vulnerabilities — but to explain them in a way that developers, auditors, and decision-makers can act on. Each output goes beyond raw error codes or abstract warnings. It delivers contextualized findings with human-readable explanations of what the issue is, how it could be exploited, and why it matters in a live environment.

Findings are accompanied by replayable proofs of concept, including transaction traces, calldata, and attacker contract logic. These aren't theoretical risks — they’re reproducible behaviors tied to actual on-chain execution. When applicable, Shepherd also suggests potential remediations, aligned with secure development best practices, making it easier for teams to triage, prioritize, and fix.

By transforming raw execution traces into clear narratives, Shepherd closes the gap between detection and decision — whether you're fixing code, assessing risk, or reviewing a potential exploit with limited context.

[^1]: This section needs diagram to show what this actionable result looks like