Hadrian: Open-Source API Security Testing Framework

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 in under 60 seconds. Try the tutorial →

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)

go install github.com/praetorian-inc/hadrian/cmd/hadrian@latest

Download Pre-Built Binary

Download the latest binary for your platform from the Releases page.

Build from Source

git clone https://github.com/praetorian-inc/hadrian.git
cd hadrian
make build

How to Test Your API with Hadrian

REST API Security Testing

hadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml

GraphQL API Security Testing

hadrian test graphql --target https://api.example.com --auth auth.yaml --roles roles.yaml

gRPC API Security Testing

hadrian test grpc --target localhost:50051 --proto service.proto --auth auth.yaml --roles roles.yaml

Common Options

# 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 →

Documentation

Guide	Description
Getting Started	Installation, first scan, and configuration walkthrough
REST API Testing	REST testing guide, 8 templates, and OpenAPI integration
GraphQL Security Testing	13 GraphQL checks including introspection, DoS, and auth bypass
gRPC Security Testing	gRPC patterns, proto file integration, and mutation testing
Configuration	Auth methods, roles, rate limiting, proxy, LLM triage, output formats
Template System	How to write custom YAML security test templates
Architecture	Internal design, data flow, and component overview
FAQ	Frequently asked questions about Hadrian

Tutorials

• REST: crAPI Tutorial — Test OWASP crAPI (intentionally vulnerable REST API)
• GraphQL: DVGA Tutorial — Test Damn Vulnerable GraphQL Application
• gRPC: gRPC Server Tutorial — Test an intentionally vulnerable gRPC server

Claude Code Integration

Hadrian includes a Claude Code skill that auto-generates auth.yaml and roles.yaml from your API specification — no manual config writing needed.

# 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 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.

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). Hadrian returns a non-zero exit code when vulnerabilities are found, making it suitable for CI/CD gates.

Development

Prerequisites

• Go 1.24+
• golangci-lint

Build and Test

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)

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 file for details.

About Praetorian

Praetorian is a cybersecurity company that helps organizations secure their most critical assets through offensive security services and the Praetorian Guard attack surface management platform.