hadrian-openapi-authz

Category: Development & Coding | Uploader: praetorian-inc | Downloads: 0 | Version: v1.0（Latest）
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.
Changelog: Source: GitHub https://github.com/praetorian-inc/hadrian
Directory Structure

Current level: tree/main/skills/hadrian-openapi-authz/
📁 .history/
- 📄 CHANGELOG 1.1 KB
📁 references/
- 📄 auth-examples.md 4.1 KB
- 📄 graphql-grpc-parsing.md 5.4 KB
- 📄 openapi-parsing.md 4.2 KB
- 📄 schema-reference.md 1.6 KB
- 📄 validation-reference.md 7.5 KB
📄 SKILL.md 20.2 KB
SKILL.md

---
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:

```bash
# 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

<EXTREMELY-IMPORTANT>
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.
</EXTREMELY-IMPORTANT>

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

<step>
**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.
</step>

### Phase 1 — Analyze API Specification

<step>
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).
</step>

### Phase 2 — Define Roles

<step>
**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:

```yaml
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.
</step>

### Phase 3 — Build Objects List and Map Endpoints

<step>
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`)

```yaml
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
</step>

### Phase 4 — Generate YAML Files

<step>
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:**
```yaml
# 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`):
```yaml
# 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`):
```yaml
# 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.**

```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
```
</step>

### Phase 5 — Validate and Present

<step>
**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):

```bash
# 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
```
</step>

## 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
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
hadrian-openapi-authz

Directory Structure

SKILL.md

Report

Notice
