Developing Custom Nuclei Templates for API Endpoint Authentication Bypass Detection

Developing custom Nuclei templates is critical for accurately detecting authentication bypass vulnerabilities in API endpoints. Relying solely on generic scanners often falls short, as API authentication mechanisms are highly application-specific, frequently involving unique token formats, header expectations, and endpoint logic. Custom templates allow pentesters to encode precise bypass techniques, moving beyond surface-level checks to identify genuine security flaws that might otherwise go unnoticed.

Understanding Nuclei Template Anatomy

A Nuclei template is a YAML-based definition that describes an attack or a check. For API authentication bypass detection, we primarily leverage the http protocol definitions. Understanding the core components is essential for crafting effective custom checks.

The info Section

The info section provides metadata about the template, including its unique ID, name, author, severity, and a brief description. This helps in organizing and understanding the purpose of each template.


id: api-auth-bypass-missing-header
info:
  name: API Authentication Bypass - Missing Authorization Header
  author: your-name
  tags: api, auth-bypass, security
  severity: high
  description: Checks for API endpoints that expose sensitive information when the Authorization header is omitted.

The http Section: Requests and Matchers

This is where the magic happens. The http section defines the actual HTTP requests to be sent and the conditions (matchers) to determine if a vulnerability exists.

  • method: The HTTP method (e.g., GET, POST, PUT, DELETE).

  • path: The URL path relative to the target host. This is where you'll inject your bypass logic.

  • headers: Custom HTTP headers to be sent with the request. This is crucial for manipulating authentication tokens or session identifiers.

  • body: The request body for POST/PUT requests, often used for sending JSON or form data payloads.

  • matchers: The conditions that must be met in the response to flag a vulnerability. Common matchers include:

    • status: Matches against the HTTP status code (e.g., 200, 401).

    • word: Matches specific keywords or phrases in the response body or headers.

    • regex: Uses regular expressions for more complex pattern matching.

    • dsl: Allows for powerful, complex logical conditions using Nuclei's Domain Specific Language.

    • type: Specifies whether to match against the status code, word, or regex.

    • part: Defines which part of the response to apply the matcher to (e.g., body, header, all).

Crafting Bypass Templates: Common Scenarios

API authentication bypasses often stem from developers making assumptions about client-side behavior or failing to validate server-side. Here are common scenarios we can codify into Nuclei templates:

Null/Empty Authentication Headers

Many APIs expect an Authorization header. Sometimes, if this header is entirely omitted or sent with a null/empty value, the server might process the request as if authenticated, or reveal sensitive information intended for authenticated users. This is a common flaw in relaxed security configurations.

Bypassing with Malformed Tokens

APIs that rely on JWTs or other token-based authentication might incorrectly handle malformed tokens. Sending a garbage string, an expired token, or a token with an invalid signature might, in some cases, result in an authentication bypass, especially if the validation logic is flawed or incomplete.

IDOR via API Endpoint Manipulation

While not strictly an authentication bypass, Insecure Direct Object Reference (IDOR) often works in tandem with weak authentication or authorization. If an API endpoint like /api/v1/users/{id} allows access to any user's data by simply changing the {id} parameter without proper authorization checks, a custom Nuclei template can automate the detection of such flaws. Finding such endpoints can be aided by initial reconnaissance using tools like Zondex, which helps discover exposed services and API structures, providing a strong foundation for targeted Nuclei template development.

HTTP Method Tampering

Some API endpoints might enforce authentication for certain HTTP methods (e.g., POST, DELETE) but not for others (e.g., GET). Attempting to access sensitive resources using a different, less restricted HTTP method can sometimes bypass authorization checks. For instance, changing a POST request to a GET request might expose data that was intended for creation or update operations.

Practical Template Development Examples

Example 1: Missing Authorization Header

This template attempts to access a protected API endpoint (e.g., /api/v1/admin/dashboard) without sending an Authorization header. It looks for a 200 OK status code and specific keywords that indicate successful access to administrative content, rather than an expected 401 Unauthorized or 403 Forbidden.


id: api-auth-bypass-missing-auth
info:
  name: API Authentication Bypass - Missing Authorization Header
  author: your-name
  tags: api, auth-bypass, critical
  severity: high
  description: Checks for API endpoints that expose sensitive administrative information when the Authorization header is omitted.
  reference: https://owasp.org/API_Security/API_Security_Top_10/A2_Broken_Authentication

http:
  - raw:
      - |
        GET /api/v1/admin/dashboard HTTP/1.1
        Host: {{Hostname}}
        User-Agent: Nuclei/v2.9.0
        Accept: */*

    matchers:
      - type: status
        status:
          - 200
      - type: word
        words:
          - "adminPanel"
          - "userManagement"
          - "dashboard"
        condition: or
        part: body

Example 2: Invalid JWT Bypass

Here, we send a malformed JWT to an endpoint. The template expects a 200 OK response along with keywords indicating successful (but unauthorized) access to user data, suggesting the server failed to properly validate the token's integrity or signature.


id: api-auth-bypass-invalid-jwt
info:
  name: API Authentication Bypass - Invalid JWT Token
  author: your-name
  tags: api, auth-bypass, jwt, medium
  severity: high
  description: Attempts to bypass authentication by sending a malformed or invalid JWT token.

http:
  - raw:
      - |
        GET /api/v1/user/profile HTTP/1.1
        Host: {{Hostname}}
        User-Agent: Nuclei/v2.9.0
        Accept: */*
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.INVALID_SIGNATURE_HERE

    matchers:
      - type: status
        status:
          - 200
      - type: word
        words:
          - "userEmail"
          - "userId"
          - "profileData"
        condition: or
        part: body

Example 3: Path Traversal Bypass

This template checks for a common API vulnerability where path traversal (`../`) can lead to unauthorized access to other user's data or configuration by manipulating the URL path. This could reveal sensitive information about other users. When routing such reconnaissance and scanning traffic, especially across different environments, using a tool like GProxy can be beneficial for managing proxy chains and ensuring requests originate from expected IP ranges, maintaining operational security during an engagement.


id: api-auth-bypass-path-traversal
info:
  name: API Authentication Bypass - Path Traversal (IDOR)
  author: your-name
  tags: api, auth-bypass, idor, path-traversal, high
  severity: high
  description: Checks if manipulating an API endpoint path with ../ allows access to other user's data.

http:
  - raw:
      - |
        GET /api/v1/users/self/profile HTTP/1.1
        Host: {{Hostname}}
        User-Agent: Nuclei/v2.9.0
        Accept: */*
        Authorization: Bearer VALID_USER_TOKEN_HERE

      - |
        GET /api/v1/users/../anotheruser/profile HTTP/1.1
        Host: {{Hostname}}
        User-Agent: Nuclei/v2.9.0
        Accept: */*
        Authorization: Bearer VALID_USER_TOKEN_HERE

    matchers:
      - type: status
        status:
          - 200
      - type: word
        words:
          - "anotheruserEmail" # Assuming this would appear if 'anotheruser' profile is accessed
          - "anotheruserId"
        condition: and # Both words must be present to confirm bypass
        part: body
    stop-at-first-match: true

Note: For the path traversal example, `VALID_USER_TOKEN_HERE` would need to be replaced with a real, valid token for an authenticated user to test if their authentication can be leveraged to access *other* users' data via path manipulation.

Running Custom Templates and Interpreting Results

Running with Target List

Once your custom templates are ready, you can point Nuclei to your template directory and a list of target API endpoints. If you're performing extensive automated web security testing, services like Secably can help manage and orchestrate the broader scanning efforts, including the results from specialized tools like Nuclei.


nuclei -t /path/to/your/custom-templates/ -l targets.txt -o nuclei_api_bypass_results.txt

Where targets.txt contains a list of API base URLs or specific endpoints:


https://api.example.com
https://dev.api.anotherservice.com/v2

Interpreting Output

Nuclei's output will highlight any matches found by your custom templates. A successful match indicates that your crafted bypass conditions were met, signifying a potential authentication bypass vulnerability. Review the full HTTP request and response in the output for context.


[FTL] [api-auth-bypass-missing-auth] [high] https://api.example.com/api/v1/admin/dashboard

This output indicates that the `api-auth-bypass-missing-auth` template found a `high` severity vulnerability on `https://api.example.com/api/v1/admin/dashboard`. Further manual verification is always recommended after an automated scan.

Beyond Basic Detection: Advanced Techniques

Moving beyond simple header omission or malformed tokens, custom Nuclei templates can incorporate more sophisticated logic. This includes:

  • Chaining Requests: Performing a login request first to obtain a valid token, then using that token in subsequent requests to test authorization bypasses for other users or roles.

  • Dynamic Value Extraction: Using `extractors` to pull dynamic values (e.g., CSRF tokens, session IDs) from initial responses and injecting them into subsequent requests.

  • Fuzzing Parameters: Integrating basic fuzzing of query parameters or JSON body fields to discover unexpected behavior that could lead to bypasses.