Contributing templates

Contributing templates to the Nuclei project helps the security community detect vulnerabilities across all environments. This guide covers the process for submitting high-quality templates.

Before you contribute

Check existing templates

Search the nuclei-templates repository to avoid duplicates:

# Clone the repository
git clone https://github.com/projectdiscovery/nuclei-templates.git

# Search for similar templates
grep -r "your-vulnerability-name" nuclei-templates/

Verify detection accuracy

Test your template against:

Known vulnerable targets (true positives)
Safe targets (no false positives)
Edge cases (redirects, errors, etc.)

Review contribution guidelines

Read the project’s CONTRIBUTING.md:

# View contributing guidelines
curl https://raw.githubusercontent.com/projectdiscovery/nuclei/main/CONTRIBUTING.md

Contribution requirements

Mandatory elements

All contributed templates must include:

Template metadata
References
Classification
Metadata

Complete info section with all required fields:

id: descriptive-template-id

info:
  name: Clear Descriptive Name
  author: your-github-username
  severity: medium  # appropriate severity level
  description: |
    Detailed description of what the template detects,
    why it matters, and what constitutes a match.
  tags: technology,vulnerability-type,category

Include relevant references:

info:
  reference:
    - https://nvd.nist.gov/vuln/detail/CVE-XXXX-XXXXX
    - https://vendor.com/security-advisory
    - https://github.com/project/security/advisories/GHSA-xxxx

Add security classification when applicable:

info:
  classification:
    cvss-metrics: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H
    cvss-score: 9.8
    cwe-id: CWE-89
    cve-id: CVE-2021-12345

Document resource usage:

info:
  metadata:
    max-request: 2
    verified: true  # If you've verified against real targets

Quality standards

✓ Template validates successfully (nuclei -validate -t template.yaml)✓ Follows best practices for accuracy✓ Uses multiple matchers to reduce false positives✓ Includes negative matchers for common error patterns✓ Has descriptive template ID and name✓ Contains comprehensive description✓ Uses appropriate severity level✓ Minimizes number of requests (documented in max-request)✓ Includes relevant tags for categorization✓ Has been tested against real targets

Contribution workflow

1. Fork and clone

Fork repository

Fork the nuclei-templates repository on GitHub

Clone your fork

git clone https://github.com/YOUR-USERNAME/nuclei-templates.git
cd nuclei-templates

Add upstream remote

git remote add upstream https://github.com/projectdiscovery/nuclei-templates.git

2. Create a branch

As noted in CONTRIBUTING.md, always work from the main branch:

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b add-new-template

For Nuclei core contributions (not templates), use the dev branch as the base.

3. Add your template

Place templates in the appropriate directory:

nuclei-templates/
├── cves/
│   ├── 2021/
│   │   └── CVE-2021-12345.yaml
├── vulnerabilities/
│   ├── vendor/
│   │   └── product-vulnerability.yaml
├── exposures/
│   └── configs/
│       └── git-config-exposure.yaml
├── misconfiguration/
├── exposed-panels/
└── takeovers/

CVE templates
Generic vulnerabilities
Exposures
Misconfigurations

Place in cves/YEAR/CVE-YEAR-NUMBER.yaml:

# For CVE-2021-44228
nuclei-templates/cves/2021/CVE-2021-44228.yaml

Place in vulnerabilities/vendor/:

nuclei-templates/vulnerabilities/wordpress/wordpress-sqli.yaml

Place in appropriate exposures/ subdirectory:

nuclei-templates/exposures/configs/exposed-database.yaml

Place in misconfiguration/:

nuclei-templates/misconfiguration/cors-misconfiguration.yaml

4. Validate template

Before committing, validate your template:

# Validate syntax
nuclei -validate -t path/to/your-template.yaml

# Test against target
nuclei -t path/to/your-template.yaml -u https://test-target.com

# Run with debug for detailed output
nuclei -t path/to/your-template.yaml -u https://test-target.com -debug

Ensure your template produces no false positives by testing against safe targets.

5. Commit changes

Follow good commit message practices:

# Add template
git add path/to/your-template.yaml

# Commit with descriptive message
git commit -m "Add template for CVE-2021-12345 detection

Detects SQL injection vulnerability in Product XYZ versions < 2.0.
Tested against vulnerable lab environment."

As specified in CONTRIBUTING.md, provide context in commit messages to help reviewers understand the changes.

6. Push and create pull request

# Push to your fork
git push origin add-new-template

Then create a pull request on GitHub:

Navigate to repository

Go to https://github.com/projectdiscovery/nuclei-templates

Click 'New Pull Request'

Select your fork and branch

Fill PR template

Provide detailed information about your template

Pull request guidelines

PR description template

Your pull request should include:

## Description
[Brief description of the vulnerability or exposure being detected]

## Template Details
- **Type**: CVE / Vulnerability / Exposure / Misconfiguration
- **Severity**: Info / Low / Medium / High / Critical
- **Affected Product**: [Product name and versions]
- **Max Requests**: [Number of HTTP requests]

## Testing
- [x] Template validates successfully
- [x] Tested against vulnerable target (true positive)
- [x] Tested against safe target (no false positive)
- [x] Follows template best practices

## References
- [Link to CVE/advisory/documentation]
- [Link to vendor security bulletin]

## Additional Context
[Any additional information about the detection logic, special considerations, or testing methodology]

Required PR elements

From CONTRIBUTING.md:

✓ Link to corresponding issue (create one if it doesn’t exist)✓ Context in PR description for reviewers✓ Example of running the template (before/after if applicable)✓ Steps for functional testing or replication✓ Unit tests for new features (if contributing code)

Example PR description

## Description
This template detects CVE-2021-44228 (Log4Shell) by identifying Apache Log4j 
vulnerable to JNDI injection through various vectors.

## Template Details
- **Type**: CVE
- **Severity**: Critical
- **Affected Product**: Apache Log4j 2.0-beta9 through 2.15.0 (excluding 2.12.2)
- **Max Requests**: 3

## Testing
- [x] Template validates successfully
- [x] Tested against intentionally vulnerable Log4j application
- [x] Tested against patched version (no match)
- [x] Includes OOB interaction for verification

## References
- https://nvd.nist.gov/vuln/detail/CVE-2021-44228
- https://logging.apache.org/log4j/2.x/security.html
- https://www.lunasec.io/docs/blog/log4j-zero-day/

## Testing Command
```bash
nuclei -t cves/2021/CVE-2021-44228.yaml -u https://vulnerable-app.com -debug

Additional Context

Uses interactsh for OOB verification to confirm exploitation rather than just detecting vulnerable versions.

## Special considerations

### Code protocol templates

<Warning>
  Templates using the code protocol must be [signed](/templates/signing) before submission.
</Warning>

```bash
# Sign code protocol template
nuclei -sign -t code-template.yaml

# Verify signature
nuclei -verify -t code-template.yaml

From pkg/templates/template_sign.go:59-88:

Code templates are parsed with file imports resolved
Signatures include content of referenced files
Re-signing requires original signer’s certificate

Sensitive information

Never include sensitive data in templates:

API keys or credentials
Internal IP addresses or domains
Proprietary information
Personal data

Use variables and extractors appropriately:

# Bad - Hardcoded credential
headers:
  Authorization: "Bearer sk-1234567890abcdef"

# Good - Uses extracted token
extractors:
  - type: regex
    name: token
    internal: true  # Not shown in output
    regex:
      - 'token":"([^"]+)"'

Rate limiting and ethics

Templates should respect target systems and follow responsible disclosure principles.

Minimize number of requests
Use appropriate delays for sensitive systems
Don’t perform destructive operations
Follow responsible disclosure timelines

Code style and standards

From CONTRIBUTING.md:

YAML formatting

Use 2-space indentation (no tabs)
Use lowercase for template IDs
Use hyphens in multi-word IDs
Keep lines under 120 characters when possible

Naming conventions

id: CVE-2021-12345

info:
  name: Product Name - Vulnerability Type
  # Example: Apache Log4j - Remote Code Execution

Tag conventions

Use consistent tags for categorization:

Technology: apache, nginx, wordpress, jenkins
Vulnerability type: sqli, xss, rce, lfi, ssrf
Category: exposure, misconfiguration, takeover
Impact: disclosure, injection, auth-bypass

tags: apache,log4j,rce,oast,critical

Development workflow

Running tests

Before submitting, run validation checks:

# Validate template syntax
make template-validate

# Or using nuclei directly
nuclei -validate -t your-template.yaml

For core Nuclei contributions (from CONTRIBUTING.md):

# Run unit tests
make test

# Run linters
make vet

# Build project
make build

Integration testing

Test templates in realistic scenarios:

# Test against local target
nuclei -t template.yaml -u http://localhost:8080

# Test with interactsh
nuclei -t template.yaml -u https://example.com -interactsh-url https://oast.me

# Test with rate limiting
nuclei -t template.yaml -l targets.txt -rate-limit 10

Review process

What reviewers look for

Accuracy

No false positives on safe targets
Correctly identifies vulnerable instances
Matchers are specific and accurate

Completeness

All required metadata present
Proper references and classification
Clear description of detection logic

Quality

Follows best practices
Minimal requests required
Proper error handling

Security

No destructive operations
Respects responsible disclosure
No sensitive data exposed

Style

Consistent formatting
Follows naming conventions
Proper indentation and syntax

Responding to feedback

When reviewers request changes:

# Make requested changes
edit your-template.yaml

# Commit changes
git add your-template.yaml
git commit -m "Address review feedback: improve matchers specificity"

# Push updates
git push origin add-new-template

Respond to review comments promptly and professionally. Explain your reasoning for design decisions.

After merge

Once your template is merged:

Update local repository

git checkout main
git pull upstream main

Delete feature branch

git branch -d add-new-template
git push origin --delete add-new-template

Verify in release

Check that your template appears in the next release

Getting help

If you need assistance:

Discord community

Join the ProjectDiscovery Discord for real-time help

GitHub discussions

Ask questions in GitHub Discussions

Template examples

Browse existing templates for reference

Documentation

Review comprehensive template documentation

Recognition

Contributors are recognized in:

Template author field
GitHub contribution graphs
ProjectDiscovery Hall of Fame
Community acknowledgments

Your contributions help secure thousands of applications and infrastructure worldwide.

Next steps

Best practices

Master template writing best practices

Template signing

Learn about signing code protocol templates

Validation

Understand template validation

Protocol reference

Explore protocol-specific features

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

​Before you contribute

​Contribution requirements

​Mandatory elements

​Quality standards

​Contribution workflow

​1. Fork and clone

​2. Create a branch

​3. Add your template

​4. Validate template

​5. Commit changes

​6. Push and create pull request

​Pull request guidelines

​PR description template

​Required PR elements

​Example PR description

​Additional Context

​Sensitive information

​Rate limiting and ethics

​Code style and standards

​YAML formatting

​Naming conventions

​Tag conventions

​Development workflow

​Running tests

​Integration testing

​Review process

​What reviewers look for

​Responding to feedback

​After merge

​Getting help

Discord community

GitHub discussions

Template examples

Documentation

​Recognition

​Next steps

Best practices

Template signing

Validation

Protocol reference

Build docs developers (and LLMs) love

Before you contribute

Contribution requirements

Mandatory elements

Quality standards

Contribution workflow

1. Fork and clone

2. Create a branch

3. Add your template

4. Validate template

5. Commit changes

6. Push and create pull request

Pull request guidelines

PR description template

Required PR elements

Example PR description

Additional Context

Sensitive information

Rate limiting and ethics

Code style and standards

YAML formatting

Naming conventions

Tag conventions

Development workflow

Running tests

Integration testing

Review process

What reviewers look for

Responding to feedback

After merge

Getting help

Recognition

Next steps