{"id":47623744,"url":"https://github.com/schlunsen/donna","last_synced_at":"2026-04-01T22:32:31.126Z","repository":{"id":346126727,"uuid":"1188550975","full_name":"schlunsen/donna","owner":"schlunsen","description":"Autonomous AI pentesting platform — orchestrates Claude Code agents via Temporal to continuously find and exploit vulnerabilities","archived":false,"fork":false,"pushed_at":"2026-03-31T00:16:28.000Z","size":42865,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T01:37:33.307Z","etag":null,"topics":["ai","autonomous-agents","claude","pentesting","security","temporal"],"latest_commit_sha":null,"homepage":"https://schlunsen.github.io/donna/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schlunsen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T08:38:14.000Z","updated_at":"2026-03-28T10:01:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/schlunsen/donna","commit_stats":null,"previous_names":["schlunsen/donna"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/schlunsen/donna","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schlunsen%2Fdonna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schlunsen%2Fdonna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schlunsen%2Fdonna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schlunsen%2Fdonna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schlunsen","download_url":"https://codeload.github.com/schlunsen/donna/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schlunsen%2Fdonna/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","autonomous-agents","claude","pentesting","security","temporal"],"created_at":"2026-04-01T22:32:30.389Z","updated_at":"2026-04-01T22:32:31.113Z","avatar_url":"https://github.com/schlunsen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./assets/github-banner.png\" alt=\"Donna — Continuous AI Pentesting Platform\" width=\"100%\"\u003e\n\n# DONNA — Continuous AI Pentesting\n\n\u003e **D**eviant **O**rchestration of **N**on-compliant **N**eural **A**gents\n\n### *Grab 'em by the balls.*\n\n**Continuous AI-powered security scanning with a real-time web dashboard.**\n\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n\n\u003c/div\u003e\n\n---\n\n## What is Donna?\n\nDonna is an autonomous AI pentester that analyzes source code, identifies attack vectors, and executes real exploits against running applications. It continuously monitors your repositories for changes, automatically runs incremental pentests on what changed, tracks findings across scans, and gives you a web dashboard to monitor everything remotely.\n\n### Features\n\n| Feature | Description |\n|---------|-------------|\n| **Donna Sentinel** | Continuous scanning via Temporal cron workflows — watches git repos, detects changes, runs incremental pentests automatically |\n| **Web Dashboard** | Astro-based dashboard replacing Temporal's built-in UI — workflow list, live logs, findings panel, severity tracking |\n| **Finding Lifecycle** | Tracks findings across scans (new → confirmed → resolved) with persistent baselines |\n| **Finding Deduplication** | Normalizes, classifies, and merges duplicate findings using CVSS 3.1, CWE classification, and endpoint canonicalization |\n| **Exploitation Feedback** | Iterative refinement loop — failed exploits feed context back into retry attempts |\n| **Live Streaming** | Real-time agent turn streaming via heartbeat-based TurnBuffer, viewable in the dashboard |\n| **Slack/Discord Alerts** | Webhook notifications on new or resolved findings |\n| **Copy for Agent** | One-click \"Copy All for Agent\" to hand findings to a coding agent for remediation |\n| **Security Hardening** | CSRF protection, rate limiting, security headers, input validation, scoped Docker permissions |\n\n### Why Donna?\n\nDonna isn't just a one-shot scanner — it's a full pentesting **platform**:\n\n- **Continuous monitoring** with cron scheduling, not manual one-off scans\n- **Real-time web dashboard** with live streaming, not just terminal output\n- **Finding lifecycle tracking** (new → confirmed → resolved) across scans\n- **Automatic change detection** — watches git repos, scans only what changed\n- **Smart deduplication** — CVSS normalization, CWE classification, endpoint canonicalization\n- **Slack/Discord notifications** on new or resolved findings\n- **Iterative exploit refinement** — failed exploits feed context into retries\n- **Durable workflows** — Temporal-backed, survives crashes, auto-retries on failure\n- **Authenticated dashboard** with session management, CSRF protection, rate limiting\n\n**Donna runs while you sleep.**\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Docker** ([Install Docker](https://docs.docker.com/get-docker/))\n- **Node.js 20+** (for local development)\n- **Anthropic API key** — [Get one here](https://console.anthropic.com)\n\n### One-shot scan\n\n```bash\n# 1. Clone and configure\ngit clone https://github.com/schlunsen/donna.git\ncd donna\ncp .env.example .env   # Add your ANTHROPIC_API_KEY\n\n# 2. Place your target repo\ngit clone https://github.com/your-org/your-app.git ./repos/your-app\n\n# 3. Run a pentest\n./donna start URL=https://your-app.com REPO=your-app\n```\n\n### Continuous scanning (Sentinel mode)\n\n```bash\n# 1. Start infrastructure\ndocker compose up -d\n\n# 2. Build the project\njust build\n\n# 3. Start Sentinel — scans every 6 hours by default\njust sentinel https://your-app.com ./repos/your-app\n\n# Or set a custom schedule (every 12 hours)\njust sentinel-cron \"0 */12 * * *\" https://your-app.com ./repos/your-app\n```\n\nSentinel watches your repo for git changes. When it detects a diff, it routes the changed files to the relevant vulnerability categories and runs only the affected pipelines. When nothing changed, it exits at zero cost.\n\n### Open the dashboard\n\n```bash\njust dashboard-ui    # Opens http://localhost:4321\n```\n\nThe dashboard shows all workflows, live agent logs, per-finding severity badges, and detailed evidence for each finding.\n\n---\n\n## Architecture\n\nDonna's multi-agent pentest pipeline with a continuous orchestration layer on top:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     Donna Sentinel (Cron)                       │\n│                                                                 │\n│  Git Fetch → Diff → Route Changes → Run Pipeline → Track       │\n│                                         │            Findings   │\n│                                         ▼                       │\n│                              ┌──────────────────┐               │\n│                              │  Pentest Pipeline │  (child wf)  │\n│                              │                   │               │\n│                              │  Recon → Analysis │               │\n│                              │    → Exploit →    │               │\n│                              │      Report       │               │\n│                              └──────────────────┘               │\n│                                         │                       │\n│                    ┌────────────────────┴────────────┐          │\n│                    ▼                                 ▼          │\n│             Finding Tracker                   Notifications     │\n│          (new/confirmed/resolved)          (Slack/Discord)      │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n                    ┌──────────────────┐\n                    │    Dashboard     │  (Astro SSR)\n                    │                  │\n                    │  Workflows List  │\n                    │  Live Logs       │\n                    │  Findings Panel  │\n                    │  Severity Badges │\n                    └──────────────────┘\n```\n\n### Key components\n\n| Component | Location | What it does |\n|-----------|----------|-------------|\n| **Continuous Workflow** | `src/temporal/continuous-workflow.ts` | Temporal cron workflow — git sync, change routing, child pipeline execution, finding tracking, notifications |\n| **Git Monitor** | `src/services/git-monitor.ts` | Fetches latest changes, diffs since last scan, routes files to vulnerability categories |\n| **Finding Tracker** | `src/services/finding-tracker.ts` | Manages finding lifecycle (new → confirmed → resolved) with persistent baselines |\n| **Finding Deduplication** | `src/services/finding-deduplication.ts` | Merges duplicate findings — CVSS normalization, CWE classification, endpoint canonicalization |\n| **Exploitation Feedback** | `src/services/exploitation-feedback.ts` | Parses exploit results, injects prior attempts into retries, generates calibration stats |\n| **Dashboard** | `dashboard/` | Astro SSR app — queries Temporal API and reads audit-logs for real-time monitoring |\n| **Pentest Pipeline** | `src/temporal/workflows.ts` | Core pipeline (recon → analysis → exploitation → reporting) |\n\n### Tech stack\n\n- **Temporal** — Durable workflow orchestration with cron scheduling\n- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — AI agent execution\n- **Astro** — Dashboard SSR framework\n- **Docker Compose** — Temporal server + worker + dashboard + optional router\n- **TypeScript** — All application code\n\n---\n\n## Dashboard\n\nThe dashboard runs at `http://localhost:4321` and provides:\n\n- **Workflow list** — All scans with status, target, phase, cost, and severity badges (e.g., `3C 8H 3M`)\n- **Workflow detail** — Per-agent progress, turn counts, metrics\n- **Live logs** — Real-time streaming of agent turns with auto-scroll and pulse indicator\n- **Findings panel** — List/grid view of all findings with severity, evidence, and detail modals\n- **Copy for Agent** — Copies all findings as structured text for handing off to a coding agent\n- **Workspaces** — Browse and manage scan workspaces\n- **Audit logs** — Historical scan data and reports\n\n### Running the dashboard\n\n```bash\n# Production (via Docker Compose)\ndocker compose up -d dashboard\n\n# Development (hot reload)\njust dashboard-dev\n```\n\n---\n\n## Sentinel: Continuous Scanning\n\nSentinel is a Temporal cron workflow that automates the scan-on-change loop:\n\n1. **Git Fetch** — Pulls the latest changes from the configured remote/branch\n2. **Diff \u0026 Route** — Compares against the last scanned commit, maps changed files to vulnerability categories\n3. **Smart Execution** — Runs a full scan or incremental scan (only affected categories), with forced full scans every N days\n4. **Finding Tracking** — Compares new results against the persistent baseline to classify findings as new, confirmed, or resolved\n5. **Notifications** — Sends a summary to Slack/Discord webhooks when findings change\n6. **Zero-cost skip** — If nothing changed since the last scan, the workflow exits immediately\n\n### Configuration\n\n```bash\n# Basic — scans every 6 hours\njust sentinel https://app.example.com ./repos/my-app\n\n# Custom schedule — every day at midnight\njust sentinel-cron \"0 0 * * *\" https://app.example.com ./repos/my-app\n\n# With deploy key for private repos\njust sentinel https://app.example.com ./repos/my-app --deploy-key ~/.ssh/donna-deploy\n\n# With Slack notifications\njust sentinel https://app.example.com ./repos/my-app --webhook https://hooks.slack.com/...\n\n# Stop a Sentinel workflow\njust sentinel-stop donna-continuous-myapp\n\n# View scan history\njust sentinel-history\n\n# View current finding baseline\njust sentinel-baseline\n```\n\n### Incremental vs full scans\n\nSentinel routes changed files to vulnerability categories based on file patterns:\n\n| File pattern | Vuln categories triggered |\n|-------------|--------------------------|\n| `*.sql`, `*query*`, `*db*` | Injection |\n| `*.html`, `*.jsx`, `*template*` | XSS |\n| `*auth*`, `*login*`, `*session*` | Authentication, Authorization |\n| `*url*`, `*fetch*`, `*request*` | SSRF |\n| Config files, large refactors | Full scan (all categories) |\n\nA forced full scan runs every 7 days by default (configurable via `fullScanEveryDays`).\n\n---\n\n## Finding Deduplication\n\nThe reporting pipeline deduplicates findings before generating the final report:\n\n- **Endpoint canonicalization** — Normalizes URLs, methods, and parameters\n- **CWE classification** — Maps findings to CWE identifiers via pattern matching\n- **CVSS 3.1 normalization** — Standardizes severity scores\n- **Fuzzy matching** — Merges findings sharing the same endpoint + vulnerability class + parameter\n- **Highest-severity wins** — Merged findings retain the most severe rating\n- **Root-cause correlation** — Groups related findings and generates a severity summary table\n\n---\n\n## Exploitation Feedback Loop\n\nWhen enabled (`feedback_iterations \u003e 0` in config), exploitation results feed back into the pipeline:\n\n1. Parse exploitation outcomes (success, failure, partial) with structured evidence\n2. Inject prior attempt context into retry queue files\n3. Generate calibration stats (success rate by vulnerability type, confidence levels)\n4. Re-run exploitation with refined context\n5. Append feedback metadata to the final report\n\n```yaml\n# In your config file\npipeline:\n  feedback_iterations: 2    # Number of feedback rounds (default: 0, disabled)\n```\n\n---\n\n## CLI Reference\n\n```bash\n# ── Scanning ──────────────────────────────────────────────\n./donna start URL=\u003curl\u003e REPO=\u003cname\u003e              # Start a pentest\n./donna start URL=\u003curl\u003e REPO=\u003cname\u003e WORKSPACE=q1 # Named workspace (resumable)\n./donna logs ID=\u003cworkflow-id\u003e                     # Tail workflow logs\n./donna workspaces                                # List all workspaces\n./donna stop                                      # Stop containers\n./donna stop CLEAN=true                           # Stop + remove all data\n\n# ── Sentinel ──────────────────────────────────────────────\njust sentinel \u003curl\u003e \u003crepo\u003e                        # Start continuous scanning\njust sentinel-cron \"\u003ccron\u003e\" \u003curl\u003e \u003crepo\u003e          # Custom schedule\njust sentinel-stop \u003cworkflow-id\u003e                  # Stop a Sentinel workflow\njust sentinel-history                             # View scan history\njust sentinel-baseline                            # View current findings\n\n# ── Infrastructure ────────────────────────────────────────\njust up                                           # Start all containers\njust up-temporal                                  # Start Temporal only\njust up-dashboard                                 # Start dashboard only\njust ps                                           # Show container status\n\n# ── Development ───────────────────────────────────────────\njust build                                        # Build TypeScript\njust watch                                        # Watch mode\njust typecheck                                    # Type check\njust dashboard-dev                                # Dashboard dev server\n\n# ── Utilities ─────────────────────────────────────────────\njust doctor                                       # Check dependencies\njust repos                                        # List target repos\njust import ~/path/to/repo                        # Import a local repo\njust clone-repo \u003cgit-url\u003e \u003cname\u003e                  # Clone a target repo\njust audit-logs                                   # List audit log dirs\n```\n\n---\n\n## Project Structure\n\n```\n.\n├── src/\n│   ├── temporal/\n│   │   ├── continuous-workflow.ts    # Sentinel cron workflow\n│   │   ├── continuous-activities.ts  # Git sync, finding tracking, notifications\n│   │   ├── continuous-client.ts      # CLI to start/stop Sentinel\n│   │   ├── continuous-shared.ts      # Types, queries, notification formatting\n│   │   ├── workflows.ts             # Core pentest pipeline workflow\n│   │   ├── activities.ts            # Pipeline activities\n│   │   ├── worker.ts                # Temporal worker\n│   │   └── client.ts               # One-shot scan client\n│   ├── services/\n│   │   ├── finding-tracker.ts       # Finding lifecycle management\n│   │   ├── finding-deduplication.ts # Dedup engine (CVSS, CWE, fuzzy match)\n│   │   ├── exploitation-feedback.ts # Feedback loop between exploit rounds\n│   │   ├── git-monitor.ts           # Git diff and change routing\n│   │   ├── reporting.ts             # Report generation with dedup\n│   │   └── ...\n│   └── ai/\n│       ├── claude-executor.ts       # Claude Agent SDK integration\n│       └── ...\n├── dashboard/                       # Astro SSR dashboard\n│   ├── src/pages/                   # Workflow list, detail, schedules, docs\n│   ├── src/lib/temporal.ts          # Temporal client for dashboard\n│   └── src/lib/audit-logs.ts        # Audit log parsing for findings\n├── configs/                         # Scan configuration files\n├── prompts/                         # Agent system prompts\n├── audit-logs/                      # Scan output (auto-created)\n├── repos/                           # Target repositories (you add these)\n├── docker-compose.yml               # Temporal + worker + dashboard\n├── donna                            # CLI entrypoint (bash)\n├── justfile                         # Task runner recipes\n└── package.json\n```\n\n---\n\n## Provider Configuration\n\nDonna supports multiple AI providers:\n\n| Provider | Setup |\n|----------|-------|\n| **Anthropic API** (default) | Set `ANTHROPIC_API_KEY` in `.env` |\n| **Claude Code OAuth** | Set `CLAUDE_CODE_OAUTH_TOKEN` in `.env` |\n| **AWS Bedrock** | Set `CLAUDE_CODE_USE_BEDROCK=1` + AWS credentials |\n| **Google Vertex AI** | Set `CLAUDE_CODE_USE_VERTEX=1` + GCP credentials |\n| **Router Mode** (experimental) | `ROUTER=true` with OpenAI or OpenRouter keys |\n\nSee `.env.example` for all configuration options.\n\n---\n\n## Disclaimers\n\nThis tool **actively executes attacks** against target applications.\n\n\u003e **DO NOT run on production environments.** Use sandboxed, staging, or local development environments only.\n\n\u003e **You must have explicit, written authorization** from the system owner before running scans.\n\n\u003e **Human oversight is essential.** LLMs can generate hallucinated findings. Validate all reported vulnerabilities.\n\n---\n\n## Acknowledgments\n\nDonna was originally inspired by and forked from [Shannon](https://github.com/keygraph/shannon) by [Keygraph](https://github.com/keygraph). Thank you to the Shannon team for the foundational work on AI-powered penetration testing.\n\n---\n\n## License\n\nAGPL-3.0 — See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschlunsen%2Fdonna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschlunsen%2Fdonna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschlunsen%2Fdonna/lists"}