skills/trebuchet/SKILL.md

name, version, description, allowed-tools

name	version	description	allowed-tools
trebuchet	1.0.0	Interact with the Trebuchet pentest API — start scans, check status, retrieve reports. Trebuchet is a K8s-deployed penetration testing platform. Use when you need to run a security scan, check scan progress, or retrieve findings.	Bash, Read

Trebuchet: Penetration Testing API

Trebuchet is an AI-powered penetration testing platform forked from KeygraphHQ/shannon. It runs multi-agent security assessments against a target URL and git repository, coordinating up to 13 specialized AI agents (recon, auth testing, injection, etc.) to produce a structured findings report.

Architecture:

• trebuchet-api — Hono REST API. Accepts scan requests, creates Kubernetes Jobs for each scan, queries Temporal for job progress, and serves reports from the workspace PVC.
• Worker — Shannon fork running inside K8s Jobs. Each scan gets its own Job; the worker executes the full AI agent pipeline against the target.
• Temporal — Workflow orchestration engine. Tracks scan state, retries, and completion.
• Workspace PVC — Persistent volume where completed scan reports are stored and served by the API.

Scans are triggered via REST API and run asynchronously. Typical scan duration is ~36 minutes for the full 13-agent pipeline.

Configuration

All settings come from environment variables:

Variable	Description
TREBUCHET_API_URL	Trebuchet REST API base URL (e.g., http://trebuchet-api:3000)
TREBUCHET_API_TOKEN	Bearer auth token for the Trebuchet API

---

Common Operations

List all scans

curl -s -H "Authorization: Bearer $TREBUCHET_API_TOKEN" \
  "$TREBUCHET_API_URL/api/scans"

Start a new scan

curl -s -X POST "$TREBUCHET_API_URL/api/scans" \
  -H "Authorization: Bearer $TREBUCHET_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com",
    "gitUrl": "https://github.com/user/repo",
    "workspace": "my-workspace"
  }'

Response: { "id": "trebuchet-worker-abc123", "workspace": "my-workspace", "status": "running" }

Get scan status by workspace name

curl -s -H "Authorization: Bearer $TREBUCHET_API_TOKEN" \
  "$TREBUCHET_API_URL/api/scans?workspace=my-workspace"

The workspace filter returns all jobs for that workspace. Look for status: "completed" or status: "running".

Get scan report

curl -s -H "Authorization: Bearer $TREBUCHET_API_TOKEN" \
  "$TREBUCHET_API_URL/api/scans/{workspace}/report"

Returns the full markdown report. Use workspace name, not job ID.

Cancel a running scan

curl -s -X POST "$TREBUCHET_API_URL/api/scans/{id}/cancel" \
  -H "Authorization: Bearer $TREBUCHET_API_TOKEN"

---

Report Format

The report is a markdown file with the following structure:

# Comprehensive Security Assessment Report

## Executive Summary
- Assessment Date: YYYY-MM-DD
- Target: https://example.com
- Model: MiniMax-M2.7

## Findings

### [CRITICAL|HIGH|MEDIUM|LOW] Title
- **Location:** URL or code reference
- **Description:** ...
- **PoC:** ...
- **Remediation:** ...

Parsing Findings

Extract findings by looking for ### [SEVERITY] headers:

# Extract all finding titles and severities
grep -E "^### \[(CRITICAL|HIGH|MEDIUM|LOW)\]" report.md

# Extract CRITICAL and HIGH findings only
grep -A 10 "^### \[CRITICAL\]" report.md
grep -A 10 "^### \[HIGH\]" report.md

Scan Lifecycle

1. running — Job is active, worker processing
2. completed — Job succeeded, report available at {workspace}/report
3. failed — Job failed (check pod logs)

---

Notes

• Reports are private to the cluster (PVC); fetch via the API
• For Paperclip issues from findings, parse the report and create issues via the Paperclip API