[PROPOSAL] Cascading Configuration Hierarchy (user config vs. system-wide vs. `-config`)

[dwisiswant0]

Summary

Tip

Provide a high-level summary of the proposed change. Keep it short.

Transition Nuclei from a single-source config model (where only one file is loaded) to a cascading/merged model. This allows for system-wide defaults that are gracefully overridden by user-specific settings or immediate CLI needs.

Motivation

Tip

Describe the need, problem, and motivation for the proposed feature or change. Provide any context necessary to understand the motivation. This may include links to previous related GitHub Issues/Discussions and Discord chats, if applicable.

Currently, Nuclei relies on a single configuration file located via os.UserConfigDir. This creates significant friction for Linux distro maintainers who need to provide global defaults, such as pre-packaged template paths in /usr/share/.

To achieve that, maintainers often resort to dirty shell wrappers that force the -config flag. This effectively breaks the UX, as a forced flag prevents users from maintaining their own persistent local config.

Detailed Design

Tip

Explain the design solution in detail for those familiar with the language to understand and for those familiar with the compiler to implement. Include examples of how the feature is used, such as new command-line flags or interface changes. This may include design assumptions, conventions, API specs (though not always required), code snippets, data flow or sequence diagrams, etc.

Nuclei should adopt a deep merge strategy for config loading/resolution. Instead of selecting the first file found, it should load all available configuration layers and merge them into a single state.

Precedence Rules

Following the industry standard used by tools like kubectl, git, etc., Nuclei should resolve configuration values in the following order (highest specificity wins):

1. CLI flag (-config or individual flags): any setting provided here overrides everything else for that specific run. (highest)
2. User config (via os.UserConfigDir+ /nuclei/config.yaml): personalized settings that stay persistent for the user.
3. System-wide config: /etc/nuclei/config.yaml. Global defaults provided by a distro maintainer or a system administrator. (lowest)

That is the same logic used by kubectl when merging multiple Kubeconfig entries btw.

Example scenario:

1. /etc/nuclei/config.yaml (global): Sets update-template-dir: /usr/share/nuclei-templates.
2. ~/.config/nuclei/config.yaml (user): Sets interactsh-server: self.hosted.

Resulting state: Nuclei uses the global template path and the user's specific Interactsh server.

Unresolved Questions

• When a user runs a command that modifies the configuration (e.g., updating a provider or template path), which file should be the target? (Standard practice suggests always writing to the user config layer to avoid EPERM errors on /etc/).
• Should slice-based settings (like severity or exclude-tags) be appended/concatenated across layers, or should the higher-priority layer completely overwrite the slice?
• Should we implement an environment variable (e.g., NUCLEI_CONFIG_PATH) to sit between CLI flags and user config? (Like KUBECONFIG)

Future Milestones (Optional)

Tip

List things that the design will enable but that are out of scope for now. This can help understand the greater impact of a proposal without requiring to extend the scope of a proposal unnecessarily.

• The ability to use the config from a remote URL or S3 bucket for enterprise fleet management.

Implementation Details (Optional)

Tip

This section may include implementation details such as testing plans, update/rollback compatibility, scalability considerations, API impacts, resource usage, SLI/SLO effects, and implementation phases. It can help track major milestones and correlate them with project issues, PRs, and releases.

TBD.

References

Normative:

1. https://github.com/orgs/projectdiscovery/discussions/6658

Informative:

1. https://github.com/BlackArch/blackarch/commits/master/packages/nuclei/PKGBUILD
2. https://github.com/BlackArch/blackarch/blob/master/packages/nuclei/config.yaml
3. nuclei-templates not used by nuclei package BlackArch/blackarch#3382
4. nuclei: add nuclei-template support BlackArch/blackarch#4357
5. nuclei: remove forced -config flag. BlackArch/blackarch#4723
6. nuclei: revert s7x change BlackArch/blackarch#4726

Reviewer approval:

• @Mzack9999
• @Ice3man543
• @ehsandeep

[noraj]

Sounds pretty ok to me.

• When a user runs a command that modifies the configuration (e.g., updating a provider or template path), which file should be the target? (Standard practice suggests always writing to the user config layer to avoid EPERM errors on /etc/).

Tough question. Maybe follows the target designed in the config, so for example if there is just /etc/nuclei/config.yaml that specify nuclei-templates-directory to /usr/share/nuclei-template, a stand user will get a write error, but the error message could suggest the user to create a config to os.UserConfigDir+ /nuclei/config.yaml with nuclei-templates-directory that have nuclei-templates-directory value of $XDG_DATA_HOME/nuclei/templates (so $HOME/.local/share/nuclei/template on linux, by the way I don't see a go os.UserDataDir, only for config and cache). That way the user can let the distro update templates too if he doesn't overwrite nuclei-templates-directory. However, if you plan to always write to user dir and not follow the nuclei-templates-directory, it's weird, because in the case I mentionned where nuclei-templates-directory points to /usr/share/nuclei-template, you would update let's say $XDG_DATA_HOME/nuclei/templates but as the config uses /usr/share/nuclei-template the updated location would be ignore, else you would also need to create user config with nuclei-templates-directory to force using the user location, be it feel intrusive for an implicit behavior. If there are several users on one machine, you also want to keep templates on one location and not having each user have their own directory to avoid data duplication.

• Should slice-based settings (like severity or exclude-tags) be appended/concatenated across layers, or should the higher-priority layer completely overwrite the slice?

Merging slice-based may be a good idea, but we have to think about how to overwrite default then, because if system config already have value and the user doesn't want to append but instead overwrite and define other value, which syntax should allow that?

For example on JSON, "key": null is used to remove it from the result, effectively overriding the inherited value but it also prevents from setting a new value.
YAML use <<: *anchor or <<: {} to prevent merging but allow you to define a new value. Or in Kubernetes, key: null or key: {} explicitly replaces the whole map instead of merging list item if you have defined patchStrategy: replace.

TL;DR: merging would be more powerful but is harder to implement.

• Should we implement an environment variable (e.g., NUCLEI_CONFIG_PATH) to sit between CLI flags and user config? (Like KUBECONFIG)

I guess having an env. var. is still nice for CI/CD usage.