{"id":51521742,"url":"https://github.com/praetorian-inc/hadrian","last_synced_at":"2026-07-08T16:30:44.936Z","repository":{"id":349261075,"uuid":"1141521747","full_name":"praetorian-inc/hadrian","owner":"praetorian-inc","description":"API security testing framework for REST, GraphQL, and gRPC that validates authorization logic using role-based testing and YAML-driven templates","archived":false,"fork":false,"pushed_at":"2026-07-05T17:46:40.000Z","size":604,"stargazers_count":66,"open_issues_count":9,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T19:20:18.706Z","etag":null,"topics":["api-security","api-testing","application-security","authorization-testing","bola","capability","graphql","grpc","openapi","owasp","owasp-api-security","penetration-testing","rest-api","security-tools"],"latest_commit_sha":null,"homepage":"https://github.com/praetorian-inc/hadrian","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/praetorian-inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","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-01-25T00:52:06.000Z","updated_at":"2026-06-30T08:05:52.000Z","dependencies_parsed_at":"2026-06-03T02:03:02.960Z","dependency_job_id":null,"html_url":"https://github.com/praetorian-inc/hadrian","commit_stats":null,"previous_names":["praetorian-inc/hadrian"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/praetorian-inc/hadrian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praetorian-inc%2Fhadrian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praetorian-inc%2Fhadrian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praetorian-inc%2Fhadrian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praetorian-inc%2Fhadrian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/praetorian-inc","download_url":"https://codeload.github.com/praetorian-inc/hadrian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praetorian-inc%2Fhadrian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35271852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api-security","api-testing","application-security","authorization-testing","bola","capability","graphql","grpc","openapi","owasp","owasp-api-security","penetration-testing","rest-api","security-tools"],"created_at":"2026-07-08T16:30:44.095Z","updated_at":"2026-07-08T16:30:44.929Z","avatar_url":"https://github.com/praetorian-inc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"1200\" height=\"628\" alt=\"Hadrian - Open source API security testing framework for REST, GraphQL, and gRPC. Test for OWASP API Top 10 authorization vulnerabilities using YAML-driven templates.\" src=\"https://github.com/user-attachments/assets/5703e1d4-7a1d-4c8f-a8e0-9ab45e9ed248\" /\u003e\n\n# Hadrian: Open-Source API Security Testing Framework\n\n[![CI](https://github.com/praetorian-inc/hadrian/actions/workflows/ci.yml/badge.svg)](https://github.com/praetorian-inc/hadrian/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/praetorian-inc/hadrian)](https://goreportcard.com/report/github.com/praetorian-inc/hadrian)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n**Hadrian is an open-source API security testing framework that detects OWASP API Top 10 vulnerabilities in REST, GraphQL, and gRPC APIs.** It uses role-based authorization testing and YAML-driven templates to automatically find broken object-level authorization (BOLA), broken function-level authorization (BFLA), broken authentication, and other critical API security flaws — without writing custom test code.\n\n## Why Hadrian?\n\nMost API security scanners test for injection and configuration issues but miss **authorization logic bugs** — the #1 and #5 most critical API vulnerabilities according to OWASP. Hadrian is purpose-built for authorization testing:\n\n- **Define your roles once** (admin, user, guest) with permissions and credentials\n- **Hadrian cross-tests every role combination** against every endpoint automatically\n- **Three-phase mutation testing** proves write/delete vulnerabilities actually occurred — not just that a 200 OK was returned\n\n\u003e Hadrian found 3 critical BOLA vulnerabilities in [OWASP crAPI](https://github.com/OWASP/crAPI) in under 60 seconds. [Try the tutorial →](https://github.com/praetorian-inc/hadrian/wiki/Tutorials)\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **OWASP API Top 10 Coverage** | 30 built-in templates covering BOLA, broken auth, BFLA, data exposure, and misconfigurations |\n| **Role-Based Authorization Testing** | Define roles with permission levels and test cross-role access automatically |\n| **Mutation Testing** | Three-phase setup → attack → verify pattern proves write/delete vulnerabilities actually occurred |\n| **REST + GraphQL + gRPC** | Test any API protocol with protocol-specific security checks |\n| **Template-Driven** | YAML templates for customizable security tests — no code required |\n| **Multiple Output Formats** | Terminal, JSON, Markdown, and SARIF v2.1.0 (GitHub Code Scanning) reports |\n| **Adaptive Rate Limiting** | Proactive request throttling with reactive backoff on 429/503 responses |\n| **Proxy Support** | Route traffic through Burp Suite or other intercepting proxies |\n| **LLM-Powered Triage** | Optional AI analysis of findings via Ollama, OpenAI, or Anthropic to reduce false positives |\n| **LLM-Assisted Attack Planning** | AI-driven prioritization of which endpoints and vulnerability patterns to test first |\n| **Claude Code Integration** | Auto-generate auth and role configs from OpenAPI, GraphQL SDL, or proto files |\n\n## OWASP API Security Top 10 Coverage\n\nHadrian includes 30 templates (8 REST, 13 GraphQL, 9 gRPC) covering the most critical API security risks:\n\n| Category | Vulnerability | REST | GraphQL | gRPC |\n|----------|--------------|------|---------|------|\n| API1:2023 | Broken Object Level Authorization (BOLA) | ✅ | ✅ | ✅ |\n| API2:2023 | Broken Authentication | ✅ | ✅ | ✅ |\n| API3:2023 | Broken Object Property Level Authorization (BOPLA) | ✅ | ✅ | ✅ |\n| API4:2023 | Unrestricted Resource Consumption | — | ✅ | — |\n| API5:2023 | Broken Function Level Authorization (BFLA) | ✅ | ✅ | ✅ |\n| API6:2023 | Unrestricted Access to Sensitive Business Flows | — | — | — |\n| API7:2023 | Server Side Request Forgery | — | — | — |\n| API8:2023 | Security Misconfiguration | ✅ | ✅ | ✅ |\n| API9:2023 | Improper Inventory Management | ✅ | — | — |\n| API10:2023 | Unsafe Consumption of APIs | — | — | — |\n\n## How to Install Hadrian\n\n### Install from Source (Go)\n\n```bash\ngo install github.com/praetorian-inc/hadrian/cmd/hadrian@latest\n```\n\n### Download Pre-Built Binary\n\nDownload the latest binary for your platform from the [Releases](https://github.com/praetorian-inc/hadrian/releases) page.\n\n### Build from Source\n\n```bash\ngit clone https://github.com/praetorian-inc/hadrian.git\ncd hadrian\nmake build\n```\n\n## How to Test Your API with Hadrian\n\n### REST API Security Testing\n\n```bash\nhadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml\n```\n\n### GraphQL API Security Testing\n\n```bash\nhadrian test graphql --target https://api.example.com --auth auth.yaml --roles roles.yaml\n```\n\n### gRPC API Security Testing\n\n```bash\nhadrian test grpc --target localhost:50051 --proto service.proto --auth auth.yaml --roles roles.yaml\n```\n\n### Common Options\n\n```bash\n# Preview what would be tested (dry run)\nhadrian test rest --api api.yaml --roles roles.yaml --dry-run\n\n# Export findings as JSON\nhadrian test rest --api api.yaml --roles roles.yaml --output json --output-file report.json\n\n# Export findings as SARIF for GitHub Code Scanning upload\nhadrian test rest --api api.yaml --roles roles.yaml --output sarif --output-file report.sarif\n\n# AI-powered triage with Ollama (local)\nhadrian test rest --api api.yaml --roles roles.yaml \\\n  --llm-host http://localhost:11434 --llm-model llama3.2:latest\n\n# AI-powered triage with OpenAI (requires OPENAI_API_KEY)\nhadrian test rest --api api.yaml --roles roles.yaml --llm-provider openai\n\n# AI-powered triage with Anthropic (requires ANTHROPIC_API_KEY)\nhadrian test rest --api api.yaml --roles roles.yaml --llm-provider anthropic\n\n# AI-assisted attack planning (requires OPENAI_API_KEY, or use --planner-provider for Anthropic/Ollama)\nhadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml --planner\n\n# Run only LLM-planned steps (faster, targeted testing)\nhadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml --planner --planner-only\n\n# Route through a proxy for manual inspection\nhadrian test rest --api api.yaml --roles roles.yaml --proxy http://localhost:8080 --insecure\n```\n\n## How Does Hadrian's Mutation Testing Work?\n\nUnlike scanners that only check HTTP status codes, Hadrian's **three-phase mutation testing** proves that unauthorized actions actually succeeded:\n\n```\nPhase 1: SETUP     → Victim creates a resource (stores resource ID)\nPhase 2: ATTACK    → Attacker attempts to delete victim's resource\nPhase 3: VERIFY    → Confirm the resource was actually deleted\n```\n\nThis eliminates false positives from APIs that return 200 OK but silently ignore unauthorized requests. [Learn more about mutation testing →](https://github.com/praetorian-inc/hadrian/wiki/Architecture)\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](https://github.com/praetorian-inc/hadrian/wiki/Getting-Started) | Installation, first scan, and configuration walkthrough |\n| [REST API Testing](https://github.com/praetorian-inc/hadrian/wiki/REST-API-Testing) | REST testing guide, 8 templates, and OpenAPI integration |\n| [GraphQL Security Testing](https://github.com/praetorian-inc/hadrian/wiki/GraphQL-Security-Testing) | 13 GraphQL checks including introspection, DoS, and auth bypass |\n| [gRPC Security Testing](https://github.com/praetorian-inc/hadrian/wiki/gRPC-Security-Testing) | gRPC patterns, proto file integration, and mutation testing |\n| [Configuration](https://github.com/praetorian-inc/hadrian/wiki/Configuration) | Auth methods, roles, rate limiting, proxy, LLM triage, output formats |\n| [Template System](https://github.com/praetorian-inc/hadrian/wiki/Template-System) | How to write custom YAML security test templates |\n| [Architecture](https://github.com/praetorian-inc/hadrian/wiki/Architecture) | Internal design, data flow, and component overview |\n| [FAQ](https://github.com/praetorian-inc/hadrian/wiki/FAQ) | Frequently asked questions about Hadrian |\n\n### Tutorials\n\n- **REST**: [crAPI Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#rest-crapi-tutorial) — Test OWASP crAPI (intentionally vulnerable REST API)\n- **GraphQL**: [DVGA Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#graphql-dvga-tutorial) — Test Damn Vulnerable GraphQL Application\n- **gRPC**: [gRPC Server Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#grpc-vulnerable-server-tutorial) — Test an intentionally vulnerable gRPC server\n\n### Claude Code Integration\n\nHadrian includes a [Claude Code](https://claude.ai/code) skill that **auto-generates `auth.yaml` and `roles.yaml`** from your API specification — no manual config writing needed.\n\n```bash\n# Launch Claude Code with Hadrian as a plugin\nclaude --plugin-dir /path/to/hadrian\n\n# Then ask it to generate your config:\n# \"Generate Hadrian auth.yaml and roles.yaml from my openapi.yaml\"\n# \"Create Hadrian authorization templates from schema.graphql\"\n# \"Build Hadrian config from service.proto\"\n```\n\nSupports OpenAPI/Swagger, GraphQL SDL, and gRPC proto files. See the [skill documentation](skills/hadrian-openapi-authz/SKILL.md) for details.\n\n## Frequently Asked Questions\n\n### What types of APIs can Hadrian test?\n\nHadrian tests **REST APIs** (via OpenAPI/Swagger specs), **GraphQL APIs** (via introspection or SDL schemas), and **gRPC APIs** (via proto files). It supports bearer tokens, basic auth, API keys, and cookie-based authentication across all three protocols.\n\n### How is Hadrian different from OWASP ZAP or Burp Suite?\n\nZAP and Burp are general-purpose web security scanners focused on injection, XSS, and configuration issues. Hadrian is **purpose-built for API authorization testing** — it understands roles, permissions, and cross-user access patterns. It tests whether User A can access User B's resources, which generic scanners cannot do without extensive manual configuration.\n\n### Does Hadrian modify or delete data during testing?\n\nMutation tests create temporary resources during the setup phase and may attempt to modify or delete them. Always **test against staging environments first** and use `--dry-run` to preview what will be tested before executing.\n\n### Can I write custom security test templates?\n\nYes. Hadrian uses YAML templates that define endpoint selectors, role selectors, and detection logic. You can create custom templates for application-specific authorization rules beyond the OWASP Top 10. See the [Template System guide](https://github.com/praetorian-inc/hadrian/wiki/Template-System).\n\n### Does Hadrian integrate with CI/CD pipelines?\n\nYes. Use `--output json --output-file report.json` to generate machine-readable reports, or `--output sarif --output-file report.sarif` to publish findings to GitHub Code Scanning (a complete example workflow lives at [`.github/workflows/example-sarif-upload.yml`](.github/workflows/example-sarif-upload.yml)). Hadrian returns a non-zero exit code when vulnerabilities are found, making it suitable for CI/CD gates.\n\n## Development\n\n### Prerequisites\n\n- [Go 1.24+](https://go.dev/dl/)\n- [golangci-lint](https://golangci-lint.run/welcome/install/)\n\n### Build and Test\n\n```bash\ngit clone https://github.com/praetorian-inc/hadrian.git\ncd hadrian\nmake build       # Build the binary\nmake test        # Run tests\nmake lint        # Run linters\nmake check       # Run all checks (fmt, vet, lint, test)\n```\n\n```bash\ngo test ./...                        # Unit tests\ngo test -tags=integration ./...      # Integration tests (fully in-process, no Docker)\ngo test -race ./...                  # Race detection\n```\n\n\u003e **No Docker required.** The Go integration tests stand up in-process `httptest`\n\u003e fixtures with seeded BOLA / BFLA / BOPLA / IDOR bugs, so the full suite —\n\u003e including `-tags=integration` — runs in a fresh devcontainer with no Docker\n\u003e daemon. The crAPI / DVGA Docker harnesses under `test/` are for optional\n\u003e end-to-end *live* testing only (see the wiki tutorials), not for the test suite.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes (`git commit -am 'Add my feature'`)\n4. Push to the branch (`git push origin feature/my-feature`)\n5. Open a Pull Request\n\nPlease ensure all CI checks pass before requesting review.\n\n## License\n\nThis project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.\n\n## About Praetorian\n\n[Praetorian](https://www.praetorian.com/) is a cybersecurity company that helps organizations secure their most critical assets through offensive security services and the [Praetorian Guard](https://www.praetorian.com/guard) attack surface management platform.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpraetorian-inc%2Fhadrian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpraetorian-inc%2Fhadrian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpraetorian-inc%2Fhadrian/lists"}