<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-template-rate-limiting
description: >-
  Implement rate limiting controls in Nuclei templates and scan configurations.
  Covers per-template throttling, concurrent request limits, delay injection,
  adaptive backoff, and target-aware rate control to avoid detection and
  denial-of-service during security assessments.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - rate-limiting
  - throttling
  - performance
  - templates
  - scanning
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
---

# Implementing Template Rate Limiting

## Overview

Rate limiting in Nuclei templates prevents overwhelming targets, evading WAF
detection, and avoiding IP bans during security assessments. Proper throttling
balances scan speed against stealth and target stability. Templates can control
request timing, concurrency, and adaptive backoff behavior at both the template
and scanner level.

Mode: `[MODE: RED]` — Scan evasion and operational stealth through rate control.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ (`nuclei -version`) | Required |
| Understanding of network rate limiting and WAF behavior | Required |
| Test targets with known rate-limiting thresholds | Required |

## Key Concepts

### Template-Level Rate Control

```yaml
id: rate-limited-directory-brute

info:
  name: Rate-Limited Directory Bruteforce
  author: nerf
  severity: info
  description: |
    Directory bruteforce with built-in rate limiting to avoid WAF
    detection and IP bans. Uses deliberate pacing between requests.
  tags: brute,directory,rate-limit,stealth
  metadata:
    max-request: 10

http:
  - method: GET
    path:
      - "{{BaseURL}}/{{path}}"
    payloads:
      path:
        - admin
        - backup
        - config
        - dashboard
        - debug
        - internal
        - management
        - monitor
        - staging
        - status
    threads: 1
    stop-at-first-match: false

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
          - 301
          - 302
          - 403
      - type: dsl
        dsl:
          - 'len(body) > 0'
```

### Bulk Scan with Global Rate Limits

```yaml
id: api-endpoint-enumeration

info:
  name: API Endpoint Enumeration — Rate Controlled
  author: nerf
  severity: info
  description: |
    Enumerates common API endpoints with single-threaded execution
    to stay under typical API rate limits of 60 requests per minute.
  tags: api,enumeration,rate-limit
  metadata:
    max-request: 8

http:
  - method: GET
    path:
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v1/admin"
      - "{{BaseURL}}/api/v2/users"
      - "{{BaseURL}}/api/v2/admin"
      - "{{BaseURL}}/api/health"
      - "{{BaseURL}}/api/status"
      - "{{BaseURL}}/api/docs"
      - "{{BaseURL}}/api/swagger.json"
    threads: 1

    matchers-condition: and
    matchers:
      - type: status
        status:
          - 200
      - type: word
        part: body
        words:
          - "rate limit"
          - "too many requests"
          - "throttled"
        negative: true
    extractors:
      - type: dsl
        dsl:
          - '"Endpoint: " + path + " Status: " + status_code'
```

### Detecting Rate Limit Enforcement

```yaml
id: rate-limit-detection

info:
  name: Rate Limit Enforcement Detection
  author: nerf
  severity: info
  description: |
    Detects how a target enforces rate limiting by sending rapid
    requests and analyzing response patterns for 429 status codes,
    Retry-After headers, and rate limit response headers.
  tags: rate-limit,recon,detection
  metadata:
    max-request: 5

http:
  - method: GET
    path:
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v1/users"
      - "{{BaseURL}}/api/v1/users"
    threads: 5

    matchers-condition: or
    matchers:
      - type: status
        status:
          - 429
      - type: word
        part: header
        words:
          - "retry-after"
          - "x-ratelimit-remaining"
          - "x-rate-limit"
        condition: or
    extractors:
      - type: kval
        kval:
          - x-ratelimit-limit
          - x-ratelimit-remaining
          - retry-after
```

## Workflow

### Step 1: Profile Target Rate Limits

```bash
node scripts/agent.js --action profile --target https://api.example.com \
  --output /tmp/rate-profile.json
```

### Step 2: Scan with Rate Controls

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

### Step 3: Validate No Rate Violations

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

## CLI Rate Limit Flags

```bash
# Requests per second limit
nuclei -u https://target.com -t templates/ -rate-limit 10

# Maximum concurrent requests
nuclei -u https://target.com -t templates/ -concurrency 5

# Bulk operations per second
nuclei -u https://target.com -t templates/ -bulk-size 5

# Combined stealth scan
nuclei -l targets.txt -t templates/ -rate-limit 5 -concurrency 2 \
  -bulk-size 3 -json -o results.json
```

## Verification

- [ ] Templates use `threads: 1` for rate-sensitive targets
- [ ] Negative matchers detect rate-limiting responses (429, Retry-After)
- [ ] `max-request` metadata accurately reflects request count
- [ ] Payload-based templates control concurrency with threads
- [ ] CLI rate-limit flags documented for each template use case
- [ ] Tested against rate-limited endpoints to confirm compliance

## References

- [Nuclei Rate Limiting](https://docs.projectdiscovery.io/tools/nuclei/running#rate-limits)
- [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)
- [OWASP Rate Limiting](https://cheatsheetseries.owasp.org/cheatsheets/Denial_of_Service_Cheat_Sheet.html)
