[PROPOSAL] Deprecate `-duc`/`-disable-update-check` and Introduce Cached Update Check Interval

[dwisiswant0]

Summary

Tip

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

Proposing to deprecate -duc / -disable-update-check and replace the current "check for updates every run" behavior with a cached, periodic update-check flow backed by Otter pkg. Basically: don't check every single time, just cache it for N days and reuse the persistent metadata store.

This makes update checks more efficient, less noisy, and more in line with modern CLI best practices.

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.

The current update-check runs every single damn time Nuclei executes, which wastes network calls, adds latency, and pushes many users to disable it entirely. Since we already have Otter pkg to implement persistent (templates) metadata cache (#6630), we can use that pkg too to store the last update check timestamp and avoid doing this on every run.

This also follows what most modern CLI tools do. They do NOT check for updates on each run; instead they cache the last check and only refresh occasionally. Some common examples:

• GitHub CLI (gh): checks roughly every 24 hours, stores data in cache, never on every run
• Terraform: caches last update check and only refreshes daily
• npm / yarn / pnpm: use update-notifier, checking every 1–3 days, storing timestamps in user's home directory
• Homebrew: avoids checking on every command; uses timed intervals to prevent unnecessary GitHub API hits
• Rustup: checks occasionally, not per-run; allows manual forcing

Across the board, the rule is: avoid update checks on every run; instead, check occasionally and remember the last result. Nuclei's current approach (checking every run) is more aggressive than almost all of these tools, which is why deprecating -duc and moving to a smarter, cached mechanism makes more sense.

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.

Mechanism

• Deprecate -duc / -disable-update-check.
• Use Otter to persist a gob-encoded struct:

  type UpdateState struct {
  	LastUpdateCheck              time.Time `gob:"last_update_check"`
  	LatestNucleiVersion          string    `gob:"latest_nuclei_version"`
  	LatestNucleiTemplatesVersion string    `gob:"latest_nuclei_templates_version"`
  }

• Stored in ~/.cache/nuclei/update-state.gob.
• On startup:
  1. Read gob metadata from Otter.
  2. If LastUpdateCheck is within $$N$$ days => skip.
  3. Else: call update API, refresh metadata.

Flags

• Add:
  • -force-update-check
• Keep compatibility with old flag for a limited time.

Defaults

Suggested default interval: 1 day.

Impacts / Unresolved Questions

Tip

List key impacts, open questions, and trade-offs of the design. Include potential negative or controversial impacts, security implications, alternatives, and core concepts. Highlight pros and cons of important decisions. This info can be reused to update project docs, guides, and FAQs. Reviewers are also welcome to add their questions in this section.

Impact

• encoding/gob is fast and efficient, serializing a small struct like UpdateState is negligible overhead.
• Since metadata is small, storage footprint is minimal; no impact on performance/memory.
• The update-check path is only triggered rarely (once per interval), so there is no significant runtime overhead for typical users.

Unresolved Questions

• How many days should be the default interval? (1-7 days)
• Should binary + template update checks share the same schedule?

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.

TBD.

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.

• Use Otter as the on-disk key/value metadata store.
• Define a struct to hold update-check state, see detailed design above.
• On startup (or first run), attempt to load the state:
• When performing an update check (because cache expired or forced), after success, save back.
• Since Otter persistently serializes values (using encoding/gob under the hood), we get binary-encoded, efficient disk storage with minimal dependencies. This matches how Otter is already used elsewhere, such in (templates) metadata caching. encoding/gob is native, efficient, and can encode Go-specific types reliably.
• Using Otter's existing API keeps code clean and avoids ad-hoc file system hacks. YKWIM.

Integration steps & flag deprecation plan

1. Deprecation of -duc/-disable-update-check:

   • On first release with this change: when the flag is provided, print a warning:
     "[WRN] -disable-update-check is deprecated and will be removed in the future release"
   • Keep it functionally equivalent (i.e. skip update check) for backward compatibility.

2. New flags:

   • -force-update-check: always run update check regardless of cache.

3. Default behavior:

   • If no flags: read metadata, if last check is older than interval then check; otherwise skip quietly.
   • If metadata not found or corrupted: treat as "never checked", do check, write metadata.

4. Failure resilience:

   • If Otter read fails (e.g. corrupted file): log a warning, but proceed with update check (fail-open), then reset metadata.
   • If Otter write fails (e.g. disk full): log error, but don't block execution. Future runs will attempt again.

5. Testing & Validation:

   • Unit tests covering:
     • Empty/missing metadata => first-run behavior.
     • Fresh metadata (< interval) => skip update check.
     • Expired metadata (> interval) => trigger update check.
     • Forced update check via -force-update-check.
     • Behavior when metadata file is corrupted or unreadable (simulate read error).
   • Round-trip encode/decode tests: ensure UpdateState serializes via Otter/gob and deserializes correctly. encoding/gob is stable: adding new fields later is possible without breaking older data (gob ignores unknown fields)

6. Migration and backward compatibility:

   • No migration needed for users who used -duc, because behavior remains identical for a transitional period.
   • In release notes, clearly state that -disable-update-check is deprecated and will be removed after two releases (per deprecation timeline).

Deprecation Timeline

Version	Change
v3.7.0	Mark -duc / -disable-update-check as deprecated. Add deprecation warnings in CLI help and runtime logs.
v4.0.0	Fully remove the flag and all related code paths. Update documentation and migration guides accordingly.

Error Handling & Safety

• Ensure Otter operations (Get/Set) are thread-safe and safe in concurrent runs (e.g. multiple Nuclei invocations). If Otter already supports concurrency (as used by template cache), rely on that; otherwise, guard with locking.
• For encoding/gob decoding: decode into pointer, check for error. If decode fails, treat as "no valid metadata", re-check updates, and overwrite metadata. encoding/gob's design is tolerant of missing or extra fields between versions, which helps for future compatibility.
• No need for complex index or chunking, since we only store a single struct, keeping all state in one key-value entry avoids multi-chunk encoding/gob issues. (Storing multiple Encode calls into the same encoding/gob file can lead to problems, encoding/gob expects a single stream per session.

References

Normative:

• [PERF] Template Metadata Index with Persistent Caching #6626
• feat(loader): implement persistent metadata cache #6630

Informative:

• https://maypok86.github.io/otter/user-guide/v2/features/persistence/
• https://go.dev/blog/gob
• https://pkg.go.dev/encoding/gob
• https://groups.google.com/g/golang-nuts/c/bn6vjC5Abd8

Reviewer approval:

• @Mzack9999
• @Ice3man543
• @ehsandeep

[eriknhn]

-duc is useful for running one-time nuclei scans in docker using custom templates from disk and the latest docker image (latest nuclei version) + automatic container deletion (docker --rm flag).

Would removing -duc mean that there is no way to disable updates for such containers?