<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: writing-http-detection-templates
description: >-
  Write Nuclei HTTP request templates for detecting web vulnerabilities.
  Covers GET/POST methods, raw requests, path fuzzing, header injection,
  redirects, and authenticated endpoint scanning with proper matcher chains.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - http
  - detection
  - web-security
  - templates
  - vulnerability-scanning
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190"]
---

# Writing HTTP Detection Templates

## Overview

HTTP detection templates are the foundation of Nuclei scanning. They send crafted
HTTP requests to targets and analyze responses to identify vulnerabilities,
misconfigurations, and information disclosures. Well-written HTTP templates use
multi-layer matching to minimize false positives while catching real issues.

Mode: `[MODE: RED]` — Vulnerability detection via HTTP request crafting.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ (`nuclei -version`) | Required |
| Familiarity with HTTP protocol and common web vulnerabilities | Required |
| Target application in a controlled test environment | Required |

## Key Concepts

### Basic GET Template

```yaml
id: example-config-exposure

info:
  name: Example Application Config Exposure
  author: nerf
  severity: high
  description: |
    Detects exposed configuration files that leak database credentials,
    API keys, and internal service endpoints.
  reference:
    - https://owasp.org/www-project-web-security-testing-guide/
  classification:
    cwe-id: CWE-200
  tags: exposure,config,misconfig
  metadata:
    max-request: 1

http:
  - method: GET
    path:
      - "{{BaseURL}}/.env"
    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - "DB_PASSWORD"
          - "APP_KEY"
        condition: or
      - type: status
        status:
          - 200
      - type: word
        part: header
        words:
          - "text/plain"
        negative: false
```

### Raw HTTP Request Template

```yaml
id: api-auth-bypass

info:
  name: API Authentication Bypass via Method Override
  author: nerf
  severity: critical
  description: |
    Tests for authentication bypass using HTTP method override headers.
    Some frameworks honor X-HTTP-Method-Override to change the effective
    HTTP method, bypassing access controls on specific methods.
  classification:
    cwe-id: CWE-287
  tags: auth-bypass,api,misconfig
  metadata:
    max-request: 2

http:
  - raw:
      - |
        GET {{BaseURL}}/api/admin/users HTTP/1.1
        Host: {{Hostname}}
        X-HTTP-Method-Override: PUT
        Content-Type: application/json
      - |
        POST {{BaseURL}}/api/admin/users HTTP/1.1
        Host: {{Hostname}}
        X-Method-Override: GET
        Content-Type: application/json

    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - '"users"'
          - '"email"'
        condition: and
      - type: status
        status:
          - 200
      - type: word
        part: body
        words:
          - "unauthorized"
          - "forbidden"
        negative: true
```

### POST Request with Body

```yaml
id: graphql-introspection-enabled

info:
  name: GraphQL Introspection Enabled
  author: nerf
  severity: medium
  description: |
    GraphQL introspection is enabled, allowing attackers to enumerate
    the entire API schema including types, queries, and mutations.
  reference:
    - https://graphql.org/learn/introspection/
  classification:
    cwe-id: CWE-200
  tags: graphql,introspection,exposure,api
  metadata:
    max-request: 1

http:
  - method: POST
    path:
      - "{{BaseURL}}/graphql"
    headers:
      Content-Type: application/json
    body: '{"query":"{__schema{types{name,fields{name}}}}"}'
    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - '"__schema"'
          - '"types"'
        condition: and
      - type: status
        status:
          - 200
    extractors:
      - type: json
        part: body
        json:
          - '.data.__schema.types[].name'
```

### Multiple Path Scanning

```yaml
id: backup-file-exposure

info:
  name: Backup File Exposure
  author: nerf
  severity: medium
  description: Detects exposed backup files in common locations.
  tags: exposure,backup,misconfig
  metadata:
    max-request: 5

http:
  - method: GET
    path:
      - "{{BaseURL}}/backup.sql"
      - "{{BaseURL}}/backup.zip"
      - "{{BaseURL}}/db.sql.gz"
      - "{{BaseURL}}/dump.sql"
      - "{{BaseURL}}/database.sql.bak"
    stop-at-first-match: true
    matchers-condition: and
    matchers:
      - type: word
        part: body
        words:
          - "CREATE TABLE"
          - "INSERT INTO"
          - "PK"
        condition: or
      - type: status
        status:
          - 200
      - type: dsl
        dsl:
          - 'len(body) > 1024'
```

### Redirect-Aware Template

```yaml
id: open-redirect-detection

info:
  name: Open Redirect Detection
  author: nerf
  severity: medium
  classification:
    cwe-id: CWE-601
  tags: redirect,owasp,vulnerability
  metadata:
    max-request: 3

http:
  - method: GET
    path:
      - "{{BaseURL}}/redirect?url=https://evil.com"
      - "{{BaseURL}}/login?next=https://evil.com"
      - "{{BaseURL}}/goto?target=https://evil.com"
    redirects: true
    max-redirects: 3
    matchers:
      - type: regex
        part: header
        regex:
          - '(?i)location:\s*https?://evil\.com'
```

## Workflow

### Step 1: Validate Template Syntax

```bash
nuclei -t template.yaml -validate
```

### Step 2: Test Against Target

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

### Step 3: Verify Against Patched Target

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

## Verification

- [ ] Template uses unique descriptive `id` with lowercase hyphens
- [ ] `info` block includes name, author, severity, description, tags
- [ ] `max-request` metadata matches actual request count
- [ ] Multi-layer matchers reduce false positives
- [ ] Raw requests include Host header with `{{Hostname}}`
- [ ] Tested against vulnerable AND patched targets
- [ ] No hardcoded IPs, credentials, or internal URLs
- [ ] `stop-at-first-match` used for multi-path templates where appropriate

## References

- [Nuclei HTTP Protocol](https://docs.projectdiscovery.io/templates/protocols/http/basic-http)
- [OWASP Testing Guide — Web](https://owasp.org/www-project-web-security-testing-guide/)
- [Nuclei Template Guide](https://docs.projectdiscovery.io/templates/introduction)
