115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
<div align="center">
|
|
|
|
# Trebuchet — AI Pentester
|
|
|
|
Trebuchet is a fork of [Shannon](https://github.com/KeygraphHQ/shannon) by Keygraph, wrapped with a REST API and Kubernetes tooling for cluster-based deployments.
|
|
|
|
</div>
|
|
|
|
## What is Trebuchet?
|
|
|
|
Trebuchet is an API-driven AI pentester built on top of Shannon's autonomous penetration testing engine. It performs white-box security testing of web applications and APIs by combining source code analysis with live exploitation.
|
|
|
|
Unlike the upstream Shannon CLI, Trebuchet is designed to run as a service on Kubernetes — scans are triggered via REST API, orchestrated by Temporal, and executed in ephemeral worker pods.
|
|
|
|
> [!IMPORTANT]
|
|
> **White-box only.** Trebuchet expects access to your application's source code and repository layout.
|
|
|
|
## Features
|
|
|
|
- **Fully Autonomous Operation**: A single API call launches the full pentest. Handles 2FA/TOTP logins (including SSO), browser navigation, exploitation, and report generation without manual intervention.
|
|
- **Reproducible Proof-of-Concept Exploits**: The final report contains only proven, exploitable findings with copy-and-paste PoCs. Vulnerabilities that cannot be exploited are not reported.
|
|
- **OWASP Vulnerability Coverage**: Identifies and validates Injection, XSS, SSRF, and Broken Authentication/Authorization.
|
|
- **Code-Aware Dynamic Testing**: Analyzes source code to guide attack strategy, then validates findings with live browser and CLI-based exploits against the running application.
|
|
- **Integrated Security Tooling**: Leverages Nmap, Subfinder, WhatWeb, and Schemathesis during reconnaissance and discovery phases.
|
|
- **Parallel Processing**: Vulnerability analysis and exploitation phases run concurrently across all attack categories.
|
|
|
|
## Architecture
|
|
|
|
Trebuchet uses a multi-agent architecture that combines white-box source code analysis with dynamic exploitation across five phases:
|
|
|
|
```
|
|
+----------------------+
|
|
| Pre-Reconnaissance |
|
|
| (nmap, subfinder, |
|
|
| whatweb, code scan) |
|
|
+----------+-----------+
|
|
|
|
|
v
|
|
+----------------------+
|
|
| Reconnaissance |
|
|
| (attack surface |
|
|
| mapping) |
|
|
+----------+-----------+
|
|
|
|
|
v
|
|
+----------+----------+
|
|
| | |
|
|
v v v
|
|
+-----------+ +---------+ +---------+
|
|
| Vuln | | Vuln | | ... |
|
|
|(Injection)| | (XSS) | | |
|
|
+-----+-----+ +----+----+ +----+----+
|
|
| | |
|
|
v v v
|
|
+-----------+ +---------+ +---------+
|
|
| Exploit | | Exploit | | ... |
|
|
|(Injection)| | (XSS) | | |
|
|
+-----+-----+ +----+----+ +----+----+
|
|
| | |
|
|
+------+------+-----------+
|
|
|
|
|
v
|
|
+----------------------+
|
|
| Reporting |
|
|
+----------------------+
|
|
```
|
|
|
|
Each scan runs as an ephemeral Kubernetes Job with a per-invocation Temporal task queue, enabling concurrent scans with different target repositories.
|
|
|
|
## Deployment
|
|
|
|
Kubernetes manifests live in a separate repository: [farhoodlabs/trebuchet-infra](https://github.com/farhoodlabs/trebuchet-infra).
|
|
|
|
## Sample Reports
|
|
|
|
Sample penetration test reports from industry-standard vulnerable applications:
|
|
|
|
- **OWASP Juice Shop** — 20+ vulnerabilities including auth bypass and database exfiltration. [View Report](sample-reports/shannon-report-juice-shop.md)
|
|
- **c{api}tal API** — ~15 critical/high vulnerabilities including command injection and auth bypass. [View Report](sample-reports/shannon-report-capital-api.md)
|
|
- **OWASP crAPI** — 15+ critical/high vulnerabilities including JWT attacks and database compromise. [View Report](sample-reports/shannon-report-crapi.md)
|
|
|
|
## Benchmark
|
|
|
|
Shannon Lite scored **96.15% (100/104 exploits)** on a hint-free, source-aware variant of the XBOW security benchmark.
|
|
|
|
[Full results with detailed agent logs and per-challenge pentest reports](https://github.com/KeygraphHQ/xbow-validation-benchmarks/blob/main/xben-benchmark-results/)
|
|
|
|
## Disclaimers
|
|
|
|
> [!WARNING]
|
|
> **DO NOT run Trebuchet on production environments.**
|
|
> It actively executes attacks to confirm vulnerabilities. Use only on sandboxed, staging, or local development environments.
|
|
|
|
> [!CAUTION]
|
|
> **You must have explicit, written authorization** from the owner of the target system before running Trebuchet. Unauthorized scanning is illegal.
|
|
|
|
- **Verification is Required**: Human oversight is essential to validate all reported findings. LLMs can still generate hallucinated content.
|
|
- **Targeted Vulnerabilities**: Broken Authentication & Authorization, Injection, XSS, SSRF.
|
|
- **Cost**: A full test run typically takes 1-1.5 hours and may cost ~$50 USD using Claude Sonnet.
|
|
|
|
## License
|
|
|
|
Released under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE).
|
|
|
|
## Support
|
|
|
|
- **Report bugs**: [GitHub Issues](https://github.com/farhoodlabs/trebuchet/issues)
|
|
- **Discussions**: [GitHub Discussions](https://github.com/farhoodlabs/trebuchet/discussions)
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
Based on <a href="https://github.com/KeygraphHQ/shannon">Shannon</a> by <a href="https://keygraph.io">Keygraph</a>
|
|
</p>
|