<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: building-api-security-templates
description: >-
  Build Nuclei templates for API security testing including REST and GraphQL
  endpoint enumeration, broken object-level authorization, mass assignment,
  excessive data exposure, rate limiting gaps, and improper inventory
  management across API versions.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - api
  - security
  - rest
  - graphql
  - owasp-api
  - templates
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190"]
---

# Building API Security Templates

## Overview

API security templates target the OWASP API Security Top 10 vulnerabilities
across REST and GraphQL interfaces. They detect broken authentication,
excessive data exposure, mass assignment, injection, and improper asset
management. API templates require careful handling of JSON payloads,
authentication headers, and response schema validation to avoid false
positives from error responses.

Mode: `[MODE: RED]` — API attack surface enumeration and vulnerability detection.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ (`nuclei -version`) | Required |
| Understanding of REST and GraphQL API patterns | Required |
| API documentation or endpoint discovery results | Required |

## Key Concepts

### GraphQL Introspection Exposure

```yaml
id: graphql-introspection-enabled

info:
  name: GraphQL Introspection Enabled
  author: nerf
  severity: medium
  description: |
    GraphQL introspection is enabled, allowing attackers to enumerate
    the full API schema including queries, mutations, types, and field
    names. This information aids in crafting targeted attacks.
  classification:
    cwe-id: CWE-200
  tags: api,graphql,introspection,exposure
  metadata:
    max-request: 1

http:
  - method: POST
    path:
      - "{{BaseURL}}/graphql"
    headers:
      Content-Type: application/json
    body: '{"query":"{__schema{queryType{name}mutationType{name}types{name kind fields{name}}}}"}'

    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - '"__schema"'
          - '"queryType"'
        condition: and
      - type: status
        status:
          - 200
    extractors:
      - type: json
        part: body
        json:
          - '.data.__schema.types[] | select(.kind=="OBJECT") | .name'
```

### Excessive Data Exposure

```yaml
id: api-excessive-data-exposure

info:
  name: API Excessive Data Exposure
  author: nerf
  severity: high
  description: |
    API endpoint returns sensitive fields that should be filtered
    server-side. Responses include internal identifiers, password
    hashes, email addresses, or role information beyond what the
    client requires.
  classification:
    cwe-id: CWE-213
  tags: api,exposure,data-leak,owasp-api
  metadata:
    max-request: 1

http:
  - method: GET
    path:
      - "{{BaseURL}}/api/v1/users/me"
    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - '"password"'
          - '"password_hash"'
          - '"secret"'
          - '"internal_id"'
          - '"ssn"'
        condition: or
      - type: status
        status:
          - 200
      - type: word
        part: header
        words:
          - "application/json"
    extractors:
      - type: regex
        part: body
        regex:
          - '"(password|password_hash|secret|ssn|internal_id)"\s*:'
```

### Mass Assignment Detection

```yaml
id: api-mass-assignment

info:
  name: API Mass Assignment Vulnerability
  author: nerf
  severity: high
  description: |
    API endpoint accepts and processes fields that should not be
    user-controllable, such as role, admin status, or account balance.
    Attackers can elevate privileges by including these fields in
    update requests.
  classification:
    cwe-id: CWE-915
  tags: api,mass-assignment,privilege-escalation,owasp-api
  metadata:
    max-request: 1

http:
  - raw:
      - |
        PUT {{BaseURL}}/api/v1/users/me HTTP/1.1
        Host: {{Hostname}}
        Content-Type: application/json
        Authorization: Bearer {{token}}

        {"role":"admin","is_admin":true,"balance":999999}

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: word
        part: body
        words:
          - '"role":"admin"'
          - '"is_admin":true'
        condition: or
      - type: word
        part: body
        words:
          - "forbidden"
          - "not allowed"
          - "unauthorized"
        negative: true
```

### API Version Enumeration

```yaml
id: api-version-enumeration

info:
  name: API Version Enumeration — Deprecated Endpoints
  author: nerf
  severity: medium
  description: |
    Enumerates API versions to discover deprecated and potentially
    unpatched endpoints. Older API versions often lack security
    controls applied to current versions.
  classification:
    cwe-id: CWE-1059
  tags: api,version,enumeration,deprecated
  metadata:
    max-request: 6

http:
  - method: GET
    path:
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v2/users"
      - "{{BaseURL}}/api/v3/users"
      - "{{BaseURL}}/v1/users"
      - "{{BaseURL}}/v2/users"
      - "{{BaseURL}}/v3/users"

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: word
        part: header
        words:
          - "application/json"
    extractors:
      - type: dsl
        dsl:
          - '"Endpoint: " + path + " Status: " + status_code'
```

## Workflow

### Step 1: Validate Template

```bash
nuclei -t api-security.yaml -validate
```

### Step 2: Scan API Endpoints

```bash
node scripts/agent.js --action scan --target https://api.example.com \
  --template api-security.yaml --output /tmp/api-scan.json
```

### Step 3: Authenticated API Scan

```bash
node scripts/agent.js --action scan --target https://api.example.com \
  --template api-security.yaml --auth-header "Bearer tok_abc123" \
  --output /tmp/api-auth-scan.json
```

## Verification

- [ ] Templates set `Content-Type: application/json` for JSON APIs
- [ ] GraphQL templates use POST with proper query body
- [ ] Mass assignment tests include role/admin/privilege fields
- [ ] Negative matchers exclude error responses from matches
- [ ] API version templates cover `/api/vN/` and `/vN/` patterns
- [ ] Authenticated templates support `{{token}}` variable
- [ ] `max-request` metadata matches actual request count

## References

- [OWASP API Security Top 10](https://owasp.org/API-Security/)
- [Nuclei HTTP Protocol](https://docs.projectdiscovery.io/templates/protocols/http/basic-http)
- [GraphQL Security Best Practices](https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html)
