Add Option -vR, -virustotal-res For Virustotal Source

[Bundy01]

Hi,

Add the -vR/-virustotal-res option to limit the results. Without adding the option or -vR 0, the current behaviour is preferred (for testing a host or for premium users).

Since the API limitation, it is no longer possible to scan a file with Virustotal.
This PR fixes this by limiting the number of results and corrects the API's 429 error.

Close #1718. See also #1562 and #1705.

I would have liked to add the commented option #virustotal-res with a short description in the config.yaml file automatically, but I did not understand the “goflags” repository.

Regards.

Summary by CodeRabbit

• New Features
  • Added -vR / --virustotal-res command-line flag for configuring VirusTotal result limits during passive subdomain enumeration. Accepts a value of 0 for default behavior, or any multiple of 40. Can be configured via YAML configuration files as well as command-line arguments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a CLI flag to limit VirusTotal API results per request. The limit is validated (must be non-negative and a multiple of 40), passed through execution context, and used by the VirusTotal source to stop processing when the limit is reached.

Changes

Cohort / File(s)	Summary
Documentation & Configuration README.md, pkg/runner/options.go	Added -vR, -virustotal-res CLI flag and configuration field to Options struct with YAML tag for limiting VirusTotal results.
Validation pkg/runner/validate.go	Added validation to ensure VirusTotalResults is non-negative and, if positive, must be a multiple of 40.
Context Propagation pkg/runner/enumerate.go, pkg/subscraping/types.go	Propagates VirusTotalResults through execution context via new key VirustotalResultsCtxKey to passive enumeration stages.
Source Implementation pkg/subscraping/sources/virustotal/virustotal.go	Reads result limit from context and terminates early when the limit is reached during subdomain enumeration.

Sequence Diagram

sequenceDiagram
    participant User
    participant Runner as Runner (options)
    participant Validator
    participant Enumerator as Enumerator (context)
    participant VT as VirusTotal Source

    User->>Runner: CLI flag: -virustotal-res 40
    Runner->>Runner: Parse & store VirusTotalResults
    Runner->>Validator: Validate options
    Validator->>Validator: Check non-negative & multiple of 40
    Validator-->>Runner: Validation passed
    Runner->>Enumerator: EnumerateSubdomainsWithCtx(ctx with virustotal-res)
    Enumerator->>VT: Query subdomains with context
    VT->>VT: Read maxResults from context
    loop For each found subdomain
        VT->>VT: Emit subdomain
        VT->>VT: Check if results >= maxResults
        alt Limit reached
            VT-->>Enumerator: Return early
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A limit most wise, forty at a time,
To spare the free quota from climbing so high,
With context we pass it, through enumeration's flight,
The VirusTotal source now knows when to stop right,
No more 429 errors to dampen our sight! 🔍

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly and specifically describes the main change: adding a new CLI option (-vR, -virustotal-res) for the VirusTotal source to limit results.
Linked Issues check	✅ Passed	The PR fully implements the requested feature from issue #1718: a CLI option to limit VirusTotal results, with validation ensuring values are multiples of 40 or 0 for default behavior.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the VirusTotal result limit feature. No unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}