v3 roadmap

[dwisiswant0]

The current action:

• mirrors multiple Nuclei flags as action inputs (More Flags #7, More feature additions #10, Workflow support #33, [DEV] adding parse flags function #38, Corrected mistake in available inputs #54, Switch -json to -jsonl #56, Add Omit-Raw Flag #62, feat: support template urls #73, Add options for json and jsonl ouputs #102)
• requires frequent updates as Nuclei evolves (Update docs to reflect the last udpate #36)
• makes it difficult to pin or reproduce scans across environments (Bump nuclei 2.4.2 #20, feat: bump nuclei 2.5.1 #22, Update action.yml #24, Use nuclei 2.5.4 #28, version update #30, Add new parameter nuclei-version to pin version #70)
• etc. (Add prefix to avoid reuse in github env #32, Fix regex for flags #80, fix undefined replace func errors #88)

v3 addresses this by:

• delegating configuration directly to Nuclei
• minimizing action-specific logic
• allowing explicit version pinning for reproducibility

Design Goals

• Preserve full access to all Nuclei features
• Avoid input sprawl and duplicated flag definitions
• Make configuration precedence obvious
• Enable reproducible CI via version pinning
• Keep workflows readable and GitHub-native

Inputs

Input	Description
version	Nuclei version to install (latest or vX.Y.Z)
args	Raw Nuclei CLI arguments
config	Inline Nuclei config YAML
config-file	Path to a Nuclei config file

Defaults

• version: latest

Input Rules

Mutual Exclusivity

• config and config-file must not be set together.
• If both are provided, the action fails fast.

---

Precedence Rules

• args always take precedence over config or config-file.
• config / config-file act as base configuration.
• Conflicts are resolved using native CLI semantics.

CLI flags override config values.

How Configuration Works

Nuclei uses a YAML config file so you can set options once and avoid repeating them every time you run a scan.

On first run, Nuclei creates a default config file. $XDG_CONFIG_HOME/nuclei/config.yaml or $HOME/.config/nuclei/config.yaml on Unix systems, $HOME/Library/Application Support/nuclei/config.yaml on Darwin (macOS), %AppData%\nuclei\config.yaml on Windows, and $home/lib/nuclei/config.yaml on Plan 9.

That file contains every supported CLI flag as a commented entry, including descriptions and default values. Uncommenting an option enables it globally for future runs.

The configuration format is a direct representation of CLI flags. There is no abstraction layer, mapping, or translation, so there's nothing new to learn.

Example:

# target URLs/hosts to scan
target:
  - http://scanme.sh

# templates to run based on severity
severity:
  - critical
  - high

# rate limit (requests per second)
rate-limit: 150

When this action uses config or config-file, it simply forwards the file to Nuclei as-is. This makes configs portable, predictable, and easy to version-control in CI.

Execution Model

1. Resolve Nuclei version:
   • latest: install latest stable release
   • vX.Y.Z: install specified version

   Like https://github.com/projectdiscovery/actions/tree/v1/setup/nuclei.

2. Validate inputs:
   • error if both config and config-file are set.
3. Resolve config source:
   • config: written to a temporary file.
   • config-file: used directly.
4. Construct execution command:
   • include -config <resolved-config> if provided.
   • append args last to enforce precedence.

No config merging or mutation is performed.

Usage Examples

1. Default setup (latest Nuclei)

- uses: projectdiscovery/nuclei-action@v3
  with:
    args: -u http://scanme.sh

2. Pin a specific Nuclei version

- uses: projectdiscovery/nuclei-action@v3
  with:
    version: v3.6.1
    args: -u http://scanme.sh

3. Inline configuration with SARIF output

- uses: projectdiscovery/nuclei-action@v3
  with:
    version: latest
    config: |
      target:
        - http://scanme.sh
      sarif-export: results.sarif
- uses: github/codeql-action/upload-sarif@v3
  if: success()
  with:
    sarif_file: results.sarif
    category: nuclei-results

4. Repo-managed config with targeted overrides

- uses: projectdiscovery/nuclei-action@v3
  with:
    args: -u http://scanme.sh -severity critical,high
    config-file: path/to/nuclei-config.yaml

5. Reporting via report-config

- uses: projectdiscovery/nuclei-action@v3
  with:
    args: -u http://scanme.sh
    config: |
      report-config: issue-tracker-config.yaml

Example issue-tracker-config.yaml (repository file):

github:
 # base-url is the optional self-hosted GitHub application url
 base-url: https://localhost:8443/github
 # username is the username of the GitHub user
 username: test-username
 # owner is the owner name of the repository for issues
 owner: test-owner
 # token is the token for GitHub account
 token: test-token
 # project-name is the name of the repository
 project-name: test-project
 # issue-label is the label of the created issue type
 issue-label: bug
 # allow-list sets a tracker level filter to only create issues for templates with
 # these severity labels or tags (does not affect exporters. set those globally)
 allow-list:
   severity: high, critical
   tags: network
 # deny-list sets a tracker level filter to never create issues for templates with
 # these severity labels or tags (does not affect exporters. set those globally)
 deny-list:
   severity: low
 # duplicate-issue-check flag to enable duplicate tracking issue check.
 duplicate-issue-check: false

Refer to https://github.com/projectdiscovery/nuclei/blob/dev/cmd/nuclei/issue-tracker-config.yaml.

How This Resolves Input Maintenance

Problem (Current Model)

• Action inputs duplicate Nuclei flags
• Each new Nuclei feature requires action updates
• Users are blocked until the action catches up

v3 Solution

• Expose only generic, stable inputs.
• All current and future Nuclei options are available immediately via:
  • args
  • config / config-file
• Action rarely needs updates unless setup logic changes.

This keeps the action aligned with Nuclei without chasing every release.

Versioning & Reproducibility

• Default behavior tracks latest
• Users can pin vX.Y.Z for:
  • reproducible scans.
  • regression testing.
  • controlled upgrades.

This matches best practices used by other GitHub Actions.

Compatibility & Migration

• Breaking change, intended for v3
• Existing workflows can migrate by:
  • moving flags into args, or
  • reusing existing config files.
• Migration is straightforward and mechanical.

Non-Goals

• No flag-to-input mapping.
• No config merging.
• No hidden defaults.
• No abstraction over Nuclei behavior.

Design Rationale

The v3 design is inspired by mature, widely adopted GitHub Actions such as golangci/golangci-lint-action, goreleaser/goreleaser-action, aquasecurity/trivy-action, and github/codeql-action. These actions follow a common pattern: they act as thin, versioned wrappers around their respective CLIs, delegate configuration to native config files or raw arguments, and rely on standard CLI precedence rules rather than introducing action-specific abstractions.

By avoiding per-flag inputs and instead exposing generic mechanisms (args, inline config, config files, and explicit version pinning), these actions remain easier to maintain, immediately compatible with new upstream features, and predictable for users already familiar with the underlying tools. The proposed nuclei-action v3 adopts the same philosophy to reduce input sprawl, improve long-term maintainability, and preserve full access to Nuclei’s feature set without coupling the action to Nuclei’s release cadence.

Conclusion

With explicit version control and a minimal input surface, nuclei-action v3 becomes:

• predictable
• reproducible
• low-maintenance
• future-proof

Feedback welcome.