Skip to main content
We appreciate your interest in contributing to ProjectDiscovery/Nuclei! This guide provides guidelines for contributors looking to help improve the project.

​
Ways to contribute

Submit templates

Create and share vulnerability detection templates

Report bugs

Help us identify and fix issues

Improve code

Contribute to the Nuclei engine

Update docs

Help improve documentation

​
Contributing templates

The nuclei-templates repository is the heart of the Nuclei project. Contributing templates helps the entire security community.

​
Community programs

ProjectDiscovery runs two programs for template contributors:
  • Pioneers: Recognition program for top contributors
  • Bounties: Monetary rewards for high-quality templates

​
Template submission process

1

Fork the repository

Fork the nuclei-templates repository to your GitHub account.
2

Create your template

Write your template following the template syntax. Use the online template editor with AI assistance.
3

Validate the template

nuclei -validate -t your-template.yaml
4

Test the template

nuclei -u https://target.com -t your-template.yaml -debug
5

Submit a pull request

Create a PR to the main branch of nuclei-templates with:
  • Clear description of what the template detects
  • References to CVE/advisories (if applicable)
  • Example of vulnerable target (if safe to share)

​
Template quality guidelines

  • Zero false positives: Templates must accurately detect the vulnerability
  • Proper matchers: Use multiple matchers with and condition when necessary
  • Version checking: Include version checks where applicable
  • Status code validation: Always validate HTTP status codes
Use appropriate severity levels:
  • Critical: Remote code execution, authentication bypass
  • High: SQL injection, privilege escalation, sensitive data exposure
  • Medium: XSS, CSRF, information disclosure
  • Low: Security misconfigurations, informational issues
  • Info: Technology detection, informational findings
Include complete metadata:
info:
  name: Clear, descriptive name
  author: your-github-username
  severity: appropriate-level
  description: Detailed description of the vulnerability
  reference:
    - https://relevant-reference.com
  classification:
    cve-id: CVE-XXXX-XXXXX
    cwe-id: CWE-XXX
  tags: relevant,tags,here
  • Minimize HTTP requests where possible
  • Use request clustering when testing multiple endpoints
  • Avoid unnecessary payloads or brute force attempts
  • Use stop-at-first-match for multi-request templates

​
Template best practices

Do not include:
  • Templates that cause denial of service
  • Templates with excessive requests (brute force)
  • Templates that exploit vulnerabilities for destructive purposes
  • Personally identifiable information or credentials
Do include:
  • Clear, descriptive template IDs
  • Comprehensive references
  • Example vulnerable code/configuration (when safe)
  • Remediation guidance in description

​
Contributing code

Contributions to the Nuclei engine are welcome!

​
Getting started

1

Clone the repository

git clone https://github.com/projectdiscovery/nuclei.git
cd nuclei
2

Create a feature branch

# Always base your work from the dev branch
git checkout dev
git checkout -b feature/your-feature-name
3

Make your changes

Write your code following the existing style and conventions.
4

Run tests

# Run tests
make test

# Run linters
make vet

# Build the project
make build

​
Pull request guidelines

When creating a PR, please follow these guidelines:
  • Base from dev branch: Always work from the dev branch
  • Link to issue: Reference the related issue number
  • Clear description: Explain what changes you made and why
  • Testing evidence: Provide before/after examples if applicable
  • Functional testing: Include steps to test the changes
  • Unit tests: Add unit tests for new features
Example PR description: 
## Description
Adds support for custom DNS resolvers in network protocol

Fixes #1234

## Changes
- Added resolver configuration to network protocol
- Updated documentation for new flag
- Added unit tests for resolver logic

## Testing
Before:
```bash
nuclei -u example.com -t network/dns-test.yaml
# Uses system DNS
After: 
nuclei -u example.com -t network/dns-test.yaml -r resolvers.txt
# Uses custom resolvers

​
Checklist

  • Tests pass (make test)
  • Code is linted (make vet)
  • Documentation updated
  • Unit tests added

### Code style

Please adhere to the existing coding style for consistency:

- Follow Go best practices and idioms
- Use meaningful variable and function names
- Add comments for complex logic
- Keep functions focused and concise
- Format code with `go fmt`

## Development workflow

### Build and test locally

```bash
# Build the project
make build

# Run tests
make test

# Run linters/vet
make vet

# Run integration tests
make integration

​
Validate templates

# Validate template syntax
make template-validate

​
Update dependencies

# Tidy go modules
make tidy

​
Reporting issues

Found a bug or have a feature request?
1

Check existing issues

Search existing issues to avoid duplicates.
2

Create detailed report

Include:
  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Nuclei version (nuclei -version)
  • Operating system and architecture
  • Relevant logs or error messages
3

Provide examples

Include command-line examples, template snippets, or screenshots when helpful.

​
Documentation contributions

Help improve the documentation:
  • Fix typos or unclear explanations
  • Add examples and use cases
  • Improve navigation and organization
  • Translate documentation
Documentation PRs are submitted to the docs repository.

​
Community guidelines

  • Be respectful: Treat everyone with respect and professionalism
  • Be constructive: Provide helpful feedback and suggestions
  • Be patient: Maintainers are volunteers; reviews take time
  • Be collaborative: Work together to solve problems

​
Getting help

Discord community

Join our Discord for questions and discussions

GitHub discussions

Start a discussion on GitHub

Documentation

Browse the full documentation

Video tutorials

Watch tutorial videos

​
Recognition

Thank you to all the amazing community contributors who help make Nuclei better! Your contributions are valued and appreciated. Top contributors are recognized through:

Build docs developers (and LLMs) love

Get started for freeTalk to us