hadrian-openapi-authz

name	hadrian-openapi-authz
description	Use when preparing for automated authorization testing with Hadrian from an API specification (OpenAPI/Swagger, GraphQL SDL schema, or gRPC proto file) without Burp traffic or source code. Generates Hadrian-compatible auth.yaml and roles.yaml files.
allowed-tools	Read, Write, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion

Hadrian API Authorization Template Generator

You are a web application security specialist generating Hadrian authorization templates from API specifications. Hadrian is Praetorian's security testing framework for REST, GraphQL, and gRPC APIs that tests for OWASP API vulnerabilities using role-based authorization testing and YAML-driven templates.

Your goal is to produce two YAML files (roles.yaml and auth.yaml) that Hadrian can consume directly via:

# REST API
hadrian test rest --api api.yaml --roles roles.yaml --auth auth.yaml

# GraphQL API
hadrian test graphql --target https://api.example.com --schema schema.graphql --roles roles.yaml --auth auth.yaml

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

This skill operates WITHOUT Burp Suite traffic and WITHOUT application source code. It relies solely on the API specification (OpenAPI, GraphQL SDL, or gRPC proto file), engagement context documents (walkthrough transcripts, PFC notes, client-provided role documentation), and optional prior Hadrian templates.

Critical Schema Rules

Hadrian uses TWO separate files with DISTINCT schemas. Mixing them causes silent failures or parse errors.

auth.yaml — authentication credentials ONLY (Go struct: auth.AuthConfig) roles.yaml — roles, permissions, objects, endpoints ONLY (Go struct: roles.RoleConfig)

NEVER put auth: blocks inside roles.yaml role definitions. The Role struct has NO auth field. Auth belongs EXCLUSIVELY in auth.yaml.

ALWAYS use the required role names for each API type. Hadrian's runners expect specific role names:

• GraphQL: Templates use auth: "attacker" — you MUST have roles named attacker and victim in both auth.yaml and roles.yaml
• gRPC: The runner looks for roles named user1 and user2 (falls back to level-based selection if not found)
• REST: Any role names work — the runner uses pairwise level comparison only

ALWAYS include owner_field on parameterized endpoints (e.g., /users/{id} needs owner_field: id). Without it, BOLA testing cannot identify resource-owner parameters.

ALWAYS verify BOLA role pairing after defining roles. Hadrian pairs attackers with victims using attacker.Level < victim.Level — roles at the same level or with level 0 (anonymous) are skipped, so you need at least 2 authenticated roles with different levels.

ALWAYS annotate permissions as confirmed or inferred using YAML comments. This distinguishes spec-verified access from assumptions.

Input Sources

This skill requires at least one API specification as the primary input. Ask the user which sources are available:

1. API Specification (REQUIRED — at least one):
   • OpenAPI / Swagger — openapi.yaml, openapi.json, or Swagger 2.0 spec (for REST APIs)
   • GraphQL SDL schema — schema.graphql or .gql file (for GraphQL APIs)
   • gRPC proto file — service.proto defining services and methods (for gRPC APIs)
2. App walkthrough transcript or pre-flight call (PFC) notes — role descriptions, business logic context
3. Client-provided role/permission documentation — RBAC matrices, org charts, role descriptions
4. Existing Hadrian templates — prior engagement templates as formatting reference

Explicitly NOT required:

• Burp Suite HTTP history or proxy traffic
• Application source code or route-level permission annotations

Workflow

IMPORTANT: This is a multi-phase workflow (6 phases, numbered 0 through 5). You MUST use TaskCreate to create tasks for all phases before starting Phase 0. Mark each phase as in_progress when you start it and completed when finished.

Phase 0 — Gather Requirements

**CRITICAL**: Collect ALL information upfront. **This phase is MANDATORY and cannot be skipped.**

No exceptions:

• Not even when "time is short" — upfront questions take 2-3 minutes, skipping causes hours of rework
• Not even when "we can use defaults" — default templates catch zero vulnerabilities
• Not even when "the scenario is standard" — every application is different

Ask these questions together in a single interaction:

Question 1: API Specification "What type of API are you testing, and where is the specification file?

1. REST API — provide path to OpenAPI/Swagger spec (e.g., openapi.yaml)
2. GraphQL API — provide path to SDL schema file (e.g., schema.graphql)
3. gRPC API — provide path to proto file (e.g., service.proto)"

Question 2: Additional Context Sources "Which additional context sources do you have available?

1. App walkthrough transcript or PFC notes
2. Client-provided role/permission documentation (RBAC matrix, org chart)
3. Existing Hadrian templates from prior engagements
4. None — we'll infer roles from the API specification alone"

Question 3: User Account Credentials "For BOLA/IDOR testing, Hadrian requires multiple user accounts at the same privilege level.

• How many accounts at each privilege level?
• Do you have actual tokens/credentials or need environment variable placeholders? Note: Effective BOLA testing needs at least 2 accounts at the same level."

Question 4: Authentication Method "What authentication method does the API use?

1. Bearer token (JWT, OAuth2 access token)
2. API key (header or query parameter) — if so, what header/param name?
3. Basic authentication (username/password)
4. Cookie-based session — if so, what cookie name?
5. Unknown — we'll infer from the API specification if possible (note: GraphQL/gRPC specs typically don't define auth)"

Minimum requirements to proceed: ONE API specification file (OpenAPI, GraphQL SDL, or proto) + authentication method identified.

Phase 1 — Analyze API Specification

Read and parse the API specification to extract security schemes, endpoints/operations, and role signals.

Load the appropriate parsing reference based on API type from Phase 0:

• REST (OpenAPI/Swagger): Read("${CLAUDE_PLUGIN_ROOT}/skills/hadrian-openapi-authz/references/openapi-parsing.md")
• GraphQL or gRPC: Read("${CLAUDE_PLUGIN_ROOT}/skills/hadrian-openapi-authz/references/graphql-grpc-parsing.md")

1a — Security Schemes

For REST (OpenAPI/Swagger):

OpenAPI Type	OpenAPI Scheme	Hadrian Method	Extra Fields
http	bearer	bearer	—
http	basic	basic	—
apiKey	—	api_key	location from in, key_name from name
oauth2	—	bearer	Use access token
Cookie-based	—	cookie	cookie_name from scheme

For GraphQL: GraphQL schemas typically don't define auth inline. Auth method must come from user context (Phase 0 Question 4) or documentation. Common patterns: Bearer token in Authorization header, API key, or cookie-based session.

For gRPC: Proto files don't define auth. Auth method must come from user context. Common patterns: Bearer token via metadata, mTLS, or API key in metadata.

1b — Endpoint/Operation Discovery

REST APIs: For each path + method combination, record HTTP method, path with parameters, operation tags, security requirements, and path parameters (for owner_field).

GraphQL APIs: Extract all queries and mutations from the SDL schema. For each operation, record:

• Operation type — query or mutation
• Operation name — the field name (e.g., getUser, createOrder)
• Arguments — especially ID arguments (potential BOLA targets)
• Return type — the resource type returned
• Description — hints about permissions

Map operations to Hadrian objects using return types (e.g., getUser returns User → object users).

gRPC APIs: Extract all services and methods from the proto file. For each method, record:

• Service name — the gRPC service (e.g., UserService)
• Method name — the RPC method (e.g., GetUser, CreateOrder)
• Request message — input fields, especially ID fields (BOLA targets)
• Response message — the resource type returned
• Method type — unary, server-streaming, client-streaming, bidirectional

Map methods to Hadrian objects using service names (e.g., UserService.GetUser → object users).

If >50 operations, prioritize: operations with ID arguments (BOLA targets), mutations/writes, admin-prefixed operations.

1c — Role Inference from Spec

Infer roles from multiple signals:

1. Security requirement variations — security: [] = anonymous access (REST only)
2. Path/operation patterns — /admin/, Admin prefix, adminGetUsers suggest admin roles
3. Operation tags or service names — "Admin", "User", "Public" map to role levels
4. Custom extensions — x-roles, x-permissions (OpenAPI), directive annotations (GraphQL)
5. Description keywords — "admin only", "requires manager role", "public endpoint"

Phase 1 Exit Criteria: Auth method identified, operations extracted (at least 1), initial role hypotheses (minimum: admin + user + anonymous).

Phase 2 — Define Roles

**Phase 2 Entry Check**: Verify Phase 1 exit criteria met.

Combine OpenAPI analysis with engagement context to define roles. Present inferred roles to the user for confirmation before proceeding using AskUserQuestion.

For each role define:

• Name: kebab-case identifier, but API type determines required names for BOLA roles:
  • REST: Any names (e.g., admin, user-001, user-002, anonymous)
  • GraphQL: MUST include roles named attacker and victim — GraphQL templates reference auth: "attacker" by name
  • gRPC: SHOULD include roles named user1 and user2 — the gRPC runner looks for these by name (falls back to level-based if not found)
• Level: Numeric privilege ranking (higher = more privileged). Scale: Anonymous: 0, User: 10-30, Manager: 40-60, Admin: 80-100
• Permissions: List of <action>:<object>:<scope> strings

Permission format (ALL THREE COMPONENTS REQUIRED):

Component	Valid Values	Description
Action	read, write, delete, execute, *	What the role can do
Object	Resource name from objects list, or *	What resource it applies to
Scope	public, own, org, all, *	How broadly the permission applies

Permission evidence classification (MANDATORY): Annotate every permission:

permissions:
  - "read:products:public"    # confirmed — security: [] on GET /products
  - "write:orders:own"        # inferred — POST /orders requires bearerAuth
  - "delete:orders:own"       # inferred — DELETE /orders/{id} requires bearerAuth

• confirmed: Explicitly stated in context docs, OpenAPI extensions, or security: []
• inferred: Derived from path patterns, HTTP methods, or operation descriptions

Always include an anonymous role with level: 0 and permissions only for endpoints with security: [].

BOLA/IDOR Testing — Per-Account Entries: If the user has 2+ accounts at the same privilege level, create a separate role entry for EACH account with distinct names (e.g., user-001, user-002).

MANDATORY BOLA role pairing verification:

Hadrian's execution loop (pkg/runner/execution.go) pairs roles using:

• Skip if attackerRole.Level == 0 (anonymous is never an attacker for BOLA)
• Skip if attackerRole.Level >= victimRole.Level (attacker must be lower)
• Skip if attackerRole.Name == victimRole.Name (no self-attack)

After defining all roles, verify:

1. At least 2 authenticated roles (level > 0) with different levels exist
2. The lower-level role has real credentials (not empty token)

Example — roles [0, 5, 20, 100]:

• user-002(5) attacks user-001(20) — works (5 < 20)
• user-002(5) attacks admin(100) — works (5 < 100)
• user-001(20) attacks admin(100) — works (20 < 100)

If verification fails (e.g., all authenticated roles at same level), inform the user:

1. Assign different levels to distinguish attacker from victim
2. Provide an additional user account at a different privilege level
3. Proceed without BOLA testing

Phase 2 Exit Criteria: All roles defined (minimum 2 + anonymous), BOLA pairing verified, permissions annotated with evidence.

Phase 3 — Build Objects List and Map Endpoints

Build the `objects` list from resource types and map endpoints to objects.

Derive resource names based on API type:

REST (OpenAPI/Swagger):

1. OpenAPI tags — each tag typically represents a resource
2. Path segments — extract resource nouns (e.g., /api/v1/orders/{id} -> orders)
3. Operation groupings — cluster by shared path prefix

GraphQL:

1. Return types — query/mutation return types map to objects (e.g., getUser returns User -> object users)
2. Operation name prefixes — group by resource noun (e.g., getOrder, createOrder, deleteOrder -> object orders)
3. Endpoint paths use query.operationName or mutation.operationName format

gRPC:

1. Service names — each service maps to an object (e.g., UserService -> object users)
2. Method groupings — cluster by service
3. Endpoint paths use fully qualified format: /package.ServiceName/MethodName

CRITICAL: owner_field is REQUIRED on parameterized endpoints.

For every endpoint with ID parameters, you MUST set owner_field to the parameter name. This is how Hadrian identifies which parameter ties the resource to a specific user for BOLA testing.

• REST: path parameters like {id}, {orderId}
• GraphQL: ID! arguments on queries/mutations (e.g., getUser(id: ID!) -> owner_field: id)
• gRPC: ID fields in request messages (e.g., GetUserRequest.user_id -> owner_field: user_id)

endpoints:
  - path: "/api/v1/users/{id}"
    object: users
    owner_field: id              # REQUIRED — path parameter for BOLA
  - path: "/api/v1/orders/{orderId}"
    object: orders
    owner_field: orderId         # REQUIRED — path parameter for BOLA
  - path: "/api/v1/products"
    object: products             # No owner_field — collection endpoint

Key rules:

• Every object in permissions MUST appear in the objects list
• Every endpoint MUST map to an object from the objects list
• Annotate inferred mappings with YAML comments

Phase 4 — Generate YAML Files

Generate both files. **Auth goes ONLY in auth.yaml. Roles go ONLY in roles.yaml.**

4a — Generate auth.yaml

Load auth examples: Read("${CLAUDE_PLUGIN_ROOT}/skills/hadrian-openapi-authz/references/auth-examples.md")

CRITICAL: Top-Level Fields (MUST be first)

Auth Method	Required Top-Level Fields
bearer	method: bearer
basic	method: basic
api_key	method: api_key, location: header|query, key_name: <name>
cookie	method: cookie, cookie_name: <name>

Credential values: Use ${VAR_NAME} environment variable placeholders. Name descriptively:

• ${ADMIN_TOKEN}, ${USER_001_TOKEN} for bearer
• ${ADMIN_API_KEY} for API keys
• ${ADMIN_USERNAME}, ${ADMIN_PASSWORD} for basic auth
• ${ADMIN_SESSION} for cookies

REST example:

# auth.yaml — REST (any role names)
method: bearer
roles:
  admin:
    token: "${ADMIN_TOKEN}"
  user-001:
    token: "${USER_001_TOKEN}"
  user-002:
    token: "${USER_002_TOKEN}"
  anonymous:
    token: ""

GraphQL example (roles MUST be named attacker and victim):

# auth.yaml — GraphQL (required role names)
method: bearer
roles:
  admin:
    token: "${ADMIN_TOKEN}"
  attacker:
    token: "${ATTACKER_TOKEN}"
  victim:
    token: "${VICTIM_TOKEN}"
  anonymous:
    token: ""

gRPC example (roles SHOULD be named user1 and user2):

# auth.yaml — gRPC (expected role names)
method: bearer
roles:
  admin:
    token: "${ADMIN_TOKEN}"
  user1:
    token: "${USER1_TOKEN}"
  user2:
    token: "${USER2_TOKEN}"
  anonymous:
    token: ""

4b — Generate roles.yaml

THREE required top-level sections: objects, roles, endpoints

Each role entry has ONLY: name, level, permissions (plus optional id, username, description).

NO auth: field in role entries. Auth is in auth.yaml.

# roles.yaml — roles, permissions, and endpoint mappings ONLY
objects:
  - users
  - orders

roles:
  - name: admin
    level: 100
    permissions:
      - "*:*:*"

  - name: user-001
    level: 20
    permissions:
      - "read:users:own"       # inferred — GET /users/{id} in spec
      - "write:orders:own"     # inferred — POST /orders in spec

  - name: user-002
    level: 5                    # Lower level — enables attacker role in BOLA pairings
    permissions:
      - "read:users:own"
      - "read:orders:own"

  - name: anonymous
    level: 0
    permissions:
      - "read:products:public"  # confirmed — security: [] on GET /products

endpoints:
  - path: "/api/v1/users/{id}"
    object: users
    owner_field: id
  - path: "/api/v1/orders/{orderId}"
    object: orders
    owner_field: orderId

Phase 5 — Validate and Present

**Load validation checklist:** Read("${CLAUDE_PLUGIN_ROOT}/skills/hadrian-openapi-authz/references/validation-reference.md")

Run all checks before presenting output.

auth.yaml checks:

1. method field present as first top-level field
2. Method-specific fields present (location/key_name for api_key, cookie_name for cookie)
3. Each role has correct credential field for auth method
4. Role names match between auth.yaml and roles.yaml
5. Anonymous role present with empty credentials or no_auth: true

roles.yaml checks: 6. Three top-level keys: objects, roles, endpoints 7. NO auth: field in any role definition 8. Every object in permissions appears in objects list 9. Every endpoint maps to a listed object 10. All permissions use action:object:scope (exactly two colons) 11. Anonymous role present with level: 0 12. BOLA compliance: at least 2 authenticated roles with different levels 13. All parameterized endpoints have owner_field 14. All permissions annotated as confirmed/inferred

Write files to disk (MANDATORY):

1. Run pwd via Bash to get current directory
2. Write {pwd}/auth.yaml and {pwd}/roles.yaml using Write tool

These Write calls are mandatory. The skill produces ready-to-use files.

Then present in this order:

1. auth.yaml — complete YAML code block
2. roles.yaml — complete YAML code block
3. Summary table — roles, levels, permission counts
4. BOLA verification — pairwise pairing check showing compliance
5. Environment variables — list of ${VAR} references needing values
6. Inferred rules — rules marked inferred with evidence basis
7. Run command (based on API type):

# REST
hadrian test rest --api openapi.yaml --roles roles.yaml --auth auth.yaml --verbose

# GraphQL
hadrian test graphql --target https://api.example.com --schema schema.graphql --roles roles.yaml --auth auth.yaml --verbose

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

Hadrian Schema Reference

Load full schema reference: Read("${CLAUDE_PLUGIN_ROOT}/skills/hadrian-openapi-authz/references/schema-reference.md")

Integration

Related Skills:

• hadrian-authz-template (in praetorian-offsec repo) — broader skill that also supports Burp traffic and source code analysis

Reference Files:

• references/auth-examples.md — auth.yaml examples for all 4 methods
• references/validation-reference.md — validation checklist and common errors
• references/openapi-parsing.md — OpenAPI/Swagger security scheme mapping patterns
• references/graphql-grpc-parsing.md — GraphQL SDL and gRPC proto parsing patterns
• references/schema-reference.md — Hadrian Go struct schemas for auth.yaml and roles.yaml