https://github.com/praetorian-inc/hadrian
API security testing framework for REST, GraphQL, and gRPC that validates authorization logic using role-based testing and YAML-driven templates
https://github.com/praetorian-inc/hadrian
api-security api-testing application-security authorization-testing bola capability graphql grpc openapi owasp owasp-api-security penetration-testing rest-api security-tools
Last synced: about 5 hours ago
JSON representation
API security testing framework for REST, GraphQL, and gRPC that validates authorization logic using role-based testing and YAML-driven templates
- Host: GitHub
- URL: https://github.com/praetorian-inc/hadrian
- Owner: praetorian-inc
- License: apache-2.0
- Created: 2026-01-25T00:52:06.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-07-05T17:46:40.000Z (3 days ago)
- Last Synced: 2026-07-05T19:20:18.706Z (3 days ago)
- Topics: api-security, api-testing, application-security, authorization-testing, bola, capability, graphql, grpc, openapi, owasp, owasp-api-security, penetration-testing, rest-api, security-tools
- Language: Go
- Homepage: https://github.com/praetorian-inc/hadrian
- Size: 590 KB
- Stars: 66
- Watchers: 0
- Forks: 4
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Hadrian: Open-Source API Security Testing Framework
[](https://github.com/praetorian-inc/hadrian/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/praetorian-inc/hadrian)
[](LICENSE)
**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.
## Why Hadrian?
Most 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:
- **Define your roles once** (admin, user, guest) with permissions and credentials
- **Hadrian cross-tests every role combination** against every endpoint automatically
- **Three-phase mutation testing** proves write/delete vulnerabilities actually occurred — not just that a 200 OK was returned
> 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)
## Key Features
| Feature | Description |
|---------|-------------|
| **OWASP API Top 10 Coverage** | 30 built-in templates covering BOLA, broken auth, BFLA, data exposure, and misconfigurations |
| **Role-Based Authorization Testing** | Define roles with permission levels and test cross-role access automatically |
| **Mutation Testing** | Three-phase setup → attack → verify pattern proves write/delete vulnerabilities actually occurred |
| **REST + GraphQL + gRPC** | Test any API protocol with protocol-specific security checks |
| **Template-Driven** | YAML templates for customizable security tests — no code required |
| **Multiple Output Formats** | Terminal, JSON, Markdown, and SARIF v2.1.0 (GitHub Code Scanning) reports |
| **Adaptive Rate Limiting** | Proactive request throttling with reactive backoff on 429/503 responses |
| **Proxy Support** | Route traffic through Burp Suite or other intercepting proxies |
| **LLM-Powered Triage** | Optional AI analysis of findings via Ollama, OpenAI, or Anthropic to reduce false positives |
| **LLM-Assisted Attack Planning** | AI-driven prioritization of which endpoints and vulnerability patterns to test first |
| **Claude Code Integration** | Auto-generate auth and role configs from OpenAPI, GraphQL SDL, or proto files |
## OWASP API Security Top 10 Coverage
Hadrian includes 30 templates (8 REST, 13 GraphQL, 9 gRPC) covering the most critical API security risks:
| Category | Vulnerability | REST | GraphQL | gRPC |
|----------|--------------|------|---------|------|
| API1:2023 | Broken Object Level Authorization (BOLA) | ✅ | ✅ | ✅ |
| API2:2023 | Broken Authentication | ✅ | ✅ | ✅ |
| API3:2023 | Broken Object Property Level Authorization (BOPLA) | ✅ | ✅ | ✅ |
| API4:2023 | Unrestricted Resource Consumption | — | ✅ | — |
| API5:2023 | Broken Function Level Authorization (BFLA) | ✅ | ✅ | ✅ |
| API6:2023 | Unrestricted Access to Sensitive Business Flows | — | — | — |
| API7:2023 | Server Side Request Forgery | — | — | — |
| API8:2023 | Security Misconfiguration | ✅ | ✅ | ✅ |
| API9:2023 | Improper Inventory Management | ✅ | — | — |
| API10:2023 | Unsafe Consumption of APIs | — | — | — |
## How to Install Hadrian
### Install from Source (Go)
```bash
go install github.com/praetorian-inc/hadrian/cmd/hadrian@latest
```
### Download Pre-Built Binary
Download the latest binary for your platform from the [Releases](https://github.com/praetorian-inc/hadrian/releases) page.
### Build from Source
```bash
git clone https://github.com/praetorian-inc/hadrian.git
cd hadrian
make build
```
## How to Test Your API with Hadrian
### REST API Security Testing
```bash
hadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml
```
### GraphQL API Security Testing
```bash
hadrian test graphql --target https://api.example.com --auth auth.yaml --roles roles.yaml
```
### gRPC API Security Testing
```bash
hadrian test grpc --target localhost:50051 --proto service.proto --auth auth.yaml --roles roles.yaml
```
### Common Options
```bash
# Preview what would be tested (dry run)
hadrian test rest --api api.yaml --roles roles.yaml --dry-run
# Export findings as JSON
hadrian test rest --api api.yaml --roles roles.yaml --output json --output-file report.json
# Export findings as SARIF for GitHub Code Scanning upload
hadrian test rest --api api.yaml --roles roles.yaml --output sarif --output-file report.sarif
# AI-powered triage with Ollama (local)
hadrian test rest --api api.yaml --roles roles.yaml \
--llm-host http://localhost:11434 --llm-model llama3.2:latest
# AI-powered triage with OpenAI (requires OPENAI_API_KEY)
hadrian test rest --api api.yaml --roles roles.yaml --llm-provider openai
# AI-powered triage with Anthropic (requires ANTHROPIC_API_KEY)
hadrian test rest --api api.yaml --roles roles.yaml --llm-provider anthropic
# AI-assisted attack planning (requires OPENAI_API_KEY, or use --planner-provider for Anthropic/Ollama)
hadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml --planner
# Run only LLM-planned steps (faster, targeted testing)
hadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml --planner --planner-only
# Route through a proxy for manual inspection
hadrian test rest --api api.yaml --roles roles.yaml --proxy http://localhost:8080 --insecure
```
## How Does Hadrian's Mutation Testing Work?
Unlike scanners that only check HTTP status codes, Hadrian's **three-phase mutation testing** proves that unauthorized actions actually succeeded:
```
Phase 1: SETUP → Victim creates a resource (stores resource ID)
Phase 2: ATTACK → Attacker attempts to delete victim's resource
Phase 3: VERIFY → Confirm the resource was actually deleted
```
This 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)
## Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started](https://github.com/praetorian-inc/hadrian/wiki/Getting-Started) | Installation, first scan, and configuration walkthrough |
| [REST API Testing](https://github.com/praetorian-inc/hadrian/wiki/REST-API-Testing) | REST testing guide, 8 templates, and OpenAPI integration |
| [GraphQL Security Testing](https://github.com/praetorian-inc/hadrian/wiki/GraphQL-Security-Testing) | 13 GraphQL checks including introspection, DoS, and auth bypass |
| [gRPC Security Testing](https://github.com/praetorian-inc/hadrian/wiki/gRPC-Security-Testing) | gRPC patterns, proto file integration, and mutation testing |
| [Configuration](https://github.com/praetorian-inc/hadrian/wiki/Configuration) | Auth methods, roles, rate limiting, proxy, LLM triage, output formats |
| [Template System](https://github.com/praetorian-inc/hadrian/wiki/Template-System) | How to write custom YAML security test templates |
| [Architecture](https://github.com/praetorian-inc/hadrian/wiki/Architecture) | Internal design, data flow, and component overview |
| [FAQ](https://github.com/praetorian-inc/hadrian/wiki/FAQ) | Frequently asked questions about Hadrian |
### Tutorials
- **REST**: [crAPI Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#rest-crapi-tutorial) — Test OWASP crAPI (intentionally vulnerable REST API)
- **GraphQL**: [DVGA Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#graphql-dvga-tutorial) — Test Damn Vulnerable GraphQL Application
- **gRPC**: [gRPC Server Tutorial](https://github.com/praetorian-inc/hadrian/wiki/Tutorials#grpc-vulnerable-server-tutorial) — Test an intentionally vulnerable gRPC server
### Claude Code Integration
Hadrian 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.
```bash
# Launch Claude Code with Hadrian as a plugin
claude --plugin-dir /path/to/hadrian
# Then ask it to generate your config:
# "Generate Hadrian auth.yaml and roles.yaml from my openapi.yaml"
# "Create Hadrian authorization templates from schema.graphql"
# "Build Hadrian config from service.proto"
```
Supports OpenAPI/Swagger, GraphQL SDL, and gRPC proto files. See the [skill documentation](skills/hadrian-openapi-authz/SKILL.md) for details.
## Frequently Asked Questions
### What types of APIs can Hadrian test?
Hadrian 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.
### How is Hadrian different from OWASP ZAP or Burp Suite?
ZAP 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.
### Does Hadrian modify or delete data during testing?
Mutation 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.
### Can I write custom security test templates?
Yes. 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).
### Does Hadrian integrate with CI/CD pipelines?
Yes. 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.
## Development
### Prerequisites
- [Go 1.24+](https://go.dev/dl/)
- [golangci-lint](https://golangci-lint.run/welcome/install/)
### Build and Test
```bash
git clone https://github.com/praetorian-inc/hadrian.git
cd hadrian
make build # Build the binary
make test # Run tests
make lint # Run linters
make check # Run all checks (fmt, vet, lint, test)
```
```bash
go test ./... # Unit tests
go test -tags=integration ./... # Integration tests (fully in-process, no Docker)
go test -race ./... # Race detection
```
> **No Docker required.** The Go integration tests stand up in-process `httptest`
> fixtures with seeded BOLA / BFLA / BOPLA / IDOR bugs, so the full suite —
> including `-tags=integration` — runs in a fresh devcontainer with no Docker
> daemon. The crAPI / DVGA Docker harnesses under `test/` are for optional
> end-to-end *live* testing only (see the wiki tutorials), not for the test suite.
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -am 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request
Please ensure all CI checks pass before requesting review.
## License
This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.
## About Praetorian
[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.