v3 roadmap #103

New issue

Closed

opened 2025-12-18 17:44:13 -05:00 by dwisiswant0 · 0 comments

dwisiswant0 commented 2025-12-18 17:44:13 -05:00 (Migrated from github.com)

Copy link

The current action:

• mirrors multiple Nuclei flags as action inputs (#7, #10, #33, #38, #54, #56, #62, #73, #102)
• requires frequent updates as Nuclei evolves (#36)
• makes it difficult to pin or reproduce scans across environments (#20, #22, #24, #28, #30, #70)
• etc. (#32, #80, #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-based configuration system powered by the github.com/projectdiscovery/goflags library. On first run, Nuclei auto-generates a default config file at ~/.config/nuclei/config.yaml containing all available CLI flags as commented entries with their descriptions and default values. Users can uncomment and customize any option to set persistent defaults.

The config file format mirrors CLI flags directly. For example:

# target URLs/hosts to scan
target:
  - http://example.com

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

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

When using config or config-file in this action, the same YAML format applies. This means any Nuclei CLI flag can be expressed in config form, and the action simply passes the config to Nuclei without transformation.

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.

The current action: * mirrors multiple Nuclei flags as action inputs (#7, #10, #33, #38, #54, #56, #62, #73, #102) * requires frequent updates as Nuclei evolves (#36) * makes it difficult to pin or reproduce scans across environments (#20, #22, #24, #28, #30, #70) * etc. (#32, #80, #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-based configuration system powered by the [github.com/projectdiscovery/goflags](https://github.com/projectdiscovery/goflags) library. On first run, Nuclei auto-generates a default config file at `~/.config/nuclei/config.yaml` containing all available CLI flags as **commented entries** with their descriptions and default values. Users can uncomment and customize any option to set persistent defaults. The config file format mirrors CLI flags directly. For example: ```yaml # target URLs/hosts to scan target: - http://example.com # templates to run based on severity severity: - critical - high # rate limit (requests per second) rate-limit: 150 ``` When using `config` or `config-file` in this action, the same YAML format applies. This means any Nuclei CLI flag can be expressed in config form, and the action simply passes the config to Nuclei without transformation. ### 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) ```yaml - uses: projectdiscovery/nuclei-action@v3 with: args: -u http://scanme.sh ``` #### 2. Pin a specific Nuclei version ```yaml - uses: projectdiscovery/nuclei-action@v3 with: version: v3.6.1 args: -u http://scanme.sh ``` #### 3. Inline configuration with SARIF output ```yaml - 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 ```yaml - 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` ```yaml - 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): ```yaml 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.

This discussion has been locked. Commenting is limited to contributors.

No Branch/Tag specified

Branches Tags

main

dependabot/npm_and_yarn/actions/core-2.0.1

dependabot/npm_and_yarn/actions/exec-2.0.0

dependabot/npm_and_yarn/js-yaml-4.1.1

dependabot/npm_and_yarn/vercel/ncc-0.38.4

dependabot/npm_and_yarn/actions/tool-cache-2.0.2

v2.0.2

v2.0.1

v2.0.0

v1.0.7

v1.0.6

v1.0.5

v1.0.4

v1.0.3

v1.0.1

v1.0.2

v1.0.0

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

projectdiscovery/nuclei-action#103

No description provided.