<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-template-testing
description: >-
  Implement testing and validation workflows for Nuclei templates. Covers
  syntax validation, functional testing against known targets, regression
  testing, CI/CD integration, false positive analysis, and template linting.
domain: cybersecurity
subdomain: nuclei-templating
tags:
  - nuclei
  - testing
  - validation
  - ci-cd
  - linting
  - quality-assurance
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
---

# Implementing Template Testing

## Overview

Template testing ensures detection accuracy before deployment. A comprehensive
testing pipeline validates syntax, confirms true positive detection, verifies
false positive absence, and runs regression checks. Untested templates
generate noise that erodes SOC trust in the scanning pipeline.

Mode: `[MODE: BLUE]` — Detection quality assurance and validation.

## Prerequisites

| Requirement | Details |
|---|---|
| Nuclei v3+ with validation and debug support | Required |
| Known-vulnerable test targets (DVWA, WebGoat, or custom) | Required |
| CI/CD pipeline (GitHub Actions, GitLab CI) | Required |
| Patched target for false positive testing | Required |

## Key Concepts

### Template Syntax Validation

```bash
# Validate single template
nuclei -t template.yaml -validate

# Validate directory of templates
nuclei -t templates/ -validate

# Verbose validation with details
nuclei -t template.yaml -validate -v

# Validate and show template stats
nuclei -t templates/ -validate -stats
```

### Functional Testing Against Known Target

```yaml
# test-config.yaml — define test expectations
id: template-test-config

tests:
  - template: cves/CVE-2021-44228.yaml
    target: http://vulnerable-log4j:8080
    expected:
      match: true
      severity: critical
      matcher_name: "log4j-rce"

  - template: cves/CVE-2021-44228.yaml
    target: http://patched-app:8080
    expected:
      match: false
```

### Debug Mode Testing

```bash
# Full debug output showing request/response
nuclei -t template.yaml -u http://target -debug

# Debug with request dump
nuclei -t template.yaml -u http://target -debug -dreq

# Debug with response dump
nuclei -t template.yaml -u http://target -debug -dresp

# Proxy through Burp for manual inspection
nuclei -t template.yaml -u http://target -proxy http://127.0.0.1:8080
```

### GitHub Actions CI Pipeline

```yaml
name: Template Validation
on:
  pull_request:
    paths:
      - 'templates/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Nuclei
        run: |
          go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
          echo "$HOME/go/bin" >> $GITHUB_PATH

      - name: Validate Templates
        run: nuclei -t templates/ -validate -v

      - name: Lint Templates
        run: |
          for f in $(find templates/ -name '*.yaml'); do
            # Check required fields
            if ! grep -q '^  name:' "$f"; then
              echo "FAIL: $f missing info.name"
              exit 1
            fi
            if ! grep -q '^  severity:' "$f"; then
              echo "FAIL: $f missing info.severity"
              exit 1
            fi
            if ! grep -q '^  author:' "$f"; then
              echo "FAIL: $f missing info.author"
              exit 1
            fi
          done
          echo "All templates pass lint checks"

      - name: Test Against Known Targets
        run: |
          docker-compose -f tests/docker-compose.yaml up -d
          sleep 10
          nuclei -t templates/ -u http://localhost:8080 -json -o test-results.json
          docker-compose -f tests/docker-compose.yaml down
```

### Template Linting Rules

```python
# lint-rules.py — custom linting for template quality
REQUIRED_INFO_FIELDS = ["name", "author", "severity", "description", "tags"]
VALID_SEVERITIES = ["critical", "high", "medium", "low", "info"]
MAX_REQUESTS_WARN = 10

def lint_template(content: dict) -> list[str]:
    """Return list of lint warnings for a template."""
    warnings = []
    info = content.get("info", {})

    for field in REQUIRED_INFO_FIELDS:
        if field not in info:
            warnings.append(f"Missing required field: info.{field}")

    severity = info.get("severity", "")
    if severity not in VALID_SEVERITIES:
        warnings.append(f"Invalid severity: {severity}")

    if "metadata" in info:
        max_req = info["metadata"].get("max-request", 0)
        if max_req > MAX_REQUESTS_WARN:
            warnings.append(f"High request count: {max_req}")

    return warnings
```

### Regression Testing

```bash
# Save baseline results
nuclei -t templates/ -u http://target -json -o baseline.json

# After changes, compare
nuclei -t templates/ -u http://target -json -o current.json

# Diff results
node scripts/agent.js --action regression \
  --baseline baseline.json --current current.json \
  --output /tmp/regression-report.json
```

### False Positive Validation

```bash
# Run against known-clean targets
nuclei -t template.yaml -l clean-targets.txt -json -o fp-check.json

# Any finding = false positive
if [ -s fp-check.json ]; then
  echo "FALSE POSITIVE DETECTED"
  cat fp-check.json
  exit 1
fi
echo "No false positives"
```

## Workflow

### Step 1: Validate Syntax

```bash
node scripts/agent.js --action validate --template-dir templates/ \
  --output /tmp/validation.json
```

### Step 2: Run Functional Tests

```bash
node scripts/agent.js --action test --template template.yaml \
  --target http://vulnerable-app --output /tmp/test-results.json
```

### Step 3: Check for Regressions

```bash
node scripts/agent.js --action regression --baseline baseline.json \
  --current current.json --output /tmp/regression.json
```

## Verification

- [ ] All templates pass `nuclei -validate`
- [ ] Templates tested against known-vulnerable targets (true positive)
- [ ] Templates tested against patched targets (false positive check)
- [ ] CI pipeline blocks merge on validation failure
- [ ] Template lint checks enforce required fields
- [ ] Regression tests run on every PR
- [ ] Debug output reviewed for unexpected behavior

## References

- [Nuclei Template Validation](https://docs.projectdiscovery.io/tools/nuclei/running#template-validation)
- [Nuclei Debug Mode](https://docs.projectdiscovery.io/tools/nuclei/running#debug)
