Skip to main content

domain_status_cli/
lib.rs

1#![allow(clippy::doc_markdown)] // CLI doc comments appear in --help; backticks look wrong there.
2//! CLI definition for domain-status (single source of truth).
3//!
4//! Used by the main crate for parsing and by build.rs for shell completions and man page.
5
6use std::path::PathBuf;
7
8use clap::CommandFactory;
9use clap::Parser;
10
11/// Default User-Agent for HTTP requests when the caller does not override `--user-agent`.
12///
13/// The main crate may auto-refresh Chrome's version at startup when this default is still in use.
14pub const DEFAULT_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
15
16/// Shown on `--help` so the default scan path stays authorized-use only.
17pub const ACCEPTABLE_USE_HELP: &str = "Scan only hosts you are authorized to scan.";
18
19/// Root CLI command (subcommand required).
20#[derive(Debug, Parser, Clone)]
21#[command(
22    name = "domain-status",
23    about = "Concurrent URL scanner; results in SQLite.",
24    after_help = ACCEPTABLE_USE_HELP,
25    version = "0.0.0", // placeholder — overridden by clap_command() with DOMAIN_STATUS_VERSION
26    long_version = "0.0.0", // placeholder — overridden by clap_command() with DOMAIN_STATUS_VERSION
27    subcommand_required = true,
28    arg_required_else_help = true
29)]
30pub enum CliCommand {
31    /// Scan URLs and store results in SQLite database.
32    #[command(name = "scan")]
33    Scan(ScanCommand),
34
35    /// Export data from SQLite database to various formats.
36    #[command(name = "export")]
37    Export(ExportCommand),
38
39    /// Print a summary of the last (or a selected) scan run.
40    #[command(name = "summary")]
41    Summary(SummaryCommand),
42}
43
44/// Scan command arguments.
45///
46/// Everyday flags are on `-h`. All flags (except the legacy `--enable-whois` alias)
47/// are on `--help`.
48#[derive(Debug, Parser, Clone)]
49#[command(after_help = concat!(
50    "Everyday flags: -h. All flags: --help. Docs: docs/CLI.md\n\n",
51    "Scan only hosts you are authorized to scan."
52))]
53pub struct ScanCommand {
54    /// URL list (one URL per line). Use `-` for stdin.
55    #[arg(value_parser, help_heading = "Scan")]
56    pub file: PathBuf,
57
58    #[arg(
59        long,
60        value_parser,
61        default_value = "./domain_status.db",
62        env = "DOMAIN_STATUS_DB_PATH",
63        help_heading = "Scan"
64    )]
65    pub db_path: PathBuf,
66
67    #[arg(
68        long,
69        default_value_t = 10,
70        env = "DOMAIN_STATUS_TIMEOUT_SECONDS",
71        help_heading = "Scan"
72    )]
73    pub timeout_seconds: u64,
74
75    #[arg(
76        long,
77        default_value_t = 30,
78        env = "DOMAIN_STATUS_MAX_CONCURRENCY",
79        help_heading = "Scan"
80    )]
81    pub max_concurrency: usize,
82
83    /// URL admission rate (tokens per input URL per second). `0` disables
84    /// both the global cap and the 2/sec per-host cap.
85    ///
86    /// Not per-HTTP-request RPS: redirects, favicon, TLS, and WHOIS share one token
87    /// per input URL. When enabled, each host is also limited to 2 URL tokens/sec.
88    #[arg(
89        long,
90        default_value_t = 15,
91        env = "DOMAIN_STATUS_RATE_LIMIT_RPS",
92        help_heading = "Scan"
93    )]
94    pub rate_limit_rps: u32,
95
96    /// Disable WHOIS/RDAP (on by default).
97    ///
98    /// Overrides TOML/env `enable_whois = true`.
99    #[arg(long, conflicts_with = "enable_whois", help_heading = "Enrichments")]
100    pub no_whois: bool,
101
102    /// GeoIP MMDB path or URL. Or set MAXMIND_LICENSE_KEY for GeoLite2 download.
103    #[arg(long, env = "DOMAIN_STATUS_GEOIP", help_heading = "Enrichments")]
104    pub geoip: Option<String>,
105
106    /// Fetch first-party external script bodies (secrets + static tech). Off by default.
107    ///
108    /// Only scripts on the same registrable domain as the page are fetched (known
109    /// third-party CDNs are skipped). Fetches are capped at 10 scripts per page,
110    /// size/timeout limited, and SSRF-validated like the primary URL. Off by default
111    /// because it expands the threat surface and adds per-URL latency.
112    #[arg(
113        long,
114        env = "DOMAIN_STATUS_SCAN_EXTERNAL_SCRIPTS",
115        help_heading = "Enrichments"
116    )]
117    pub scan_external_scripts: bool,
118
119    /// CI exit policy when some URLs fail (`never`, `any-failure`, `pct>`).
120    #[arg(
121        long,
122        value_enum,
123        default_value_t = FailOn::Never,
124        env = "DOMAIN_STATUS_FAIL_ON",
125        help_heading = "CI / logging"
126    )]
127    pub fail_on: FailOn,
128
129    #[command(flatten, next_help_heading = "CI / logging")]
130    pub verbosity: clap_verbosity_flag::Verbosity<clap_verbosity_flag::InfoLevel>,
131
132    /// Baseline log level; overridden by `-v` / `-q` (preferred for quick changes).
133    #[arg(
134        long,
135        value_enum,
136        default_value_t = LogLevel::Info,
137        env = "DOMAIN_STATUS_LOG_LEVEL",
138        hide_short_help = true,
139        help_heading = "CI / logging"
140    )]
141    pub log_level: LogLevel,
142
143    /// Format for scan `--log-file` and for export/summary stderr.
144    ///
145    /// `plain` in the scan file is uncolored; export/summary stderr `plain` uses colors.
146    #[arg(
147        long,
148        value_enum,
149        default_value_t = LogFormat::Plain,
150        env = "DOMAIN_STATUS_LOG_FORMAT",
151        hide_short_help = true,
152        help_heading = "CI / logging"
153    )]
154    pub log_format: LogFormat,
155
156    #[arg(
157        long,
158        default_value = "domain_status.log",
159        env = "DOMAIN_STATUS_LOG_FILE",
160        hide_short_help = true,
161        help_heading = "CI / logging"
162    )]
163    pub log_file: PathBuf,
164
165    /// Hide the terminal progress bar (still logs progress to `--log-file`).
166    #[arg(
167        long,
168        env = "DOMAIN_STATUS_NO_PROGRESS",
169        hide_short_help = true,
170        help_heading = "CI / logging"
171    )]
172    pub no_progress: bool,
173
174    #[arg(
175        long,
176        default_value_t = 10,
177        value_parser = clap::value_parser!(u8).range(0..=100),
178        requires_if("pct>", "fail_on"),
179        env = "DOMAIN_STATUS_FAIL_ON_PCT_THRESHOLD",
180        hide_short_help = true,
181        help_heading = "CI / logging"
182    )]
183    pub fail_on_pct_threshold: u8,
184
185    #[arg(
186        long,
187        value_parser,
188        env = "DOMAIN_STATUS_CONFIG_FILE",
189        hide_short_help = true,
190        help_heading = "Advanced"
191    )]
192    pub config: Option<PathBuf>,
193
194    #[arg(
195        long,
196        default_value = DEFAULT_USER_AGENT,
197        env = "DOMAIN_STATUS_USER_AGENT",
198        hide_short_help = true,
199        help_heading = "Advanced"
200    )]
201    pub user_agent: String,
202
203    #[arg(
204        long,
205        env = "DOMAIN_STATUS_FINGERPRINTS",
206        hide_short_help = true,
207        help_heading = "Advanced"
208    )]
209    pub fingerprints: Option<String>,
210
211    /// Start the scan even if the full Enthec + `HTTPArchive` catalog cannot be loaded.
212    /// Default is to abort so technology detection is not silently thin.
213    #[arg(
214        long,
215        env = "DOMAIN_STATUS_ALLOW_DEGRADED_FINGERPRINTS",
216        hide_short_help = true,
217        help_heading = "Advanced"
218    )]
219    pub allow_degraded_fingerprints: bool,
220
221    #[arg(
222        long,
223        env = "DOMAIN_STATUS_STATUS_PORT",
224        hide_short_help = true,
225        help_heading = "Advanced"
226    )]
227    pub status_port: Option<u16>,
228
229    /// Shared cache root for fingerprints, GeoIP, WHOIS, and User-Agent data.
230    /// Defaults to `$DOMAIN_STATUS_CACHE_DIR` or the platform cache dir +
231    /// `domain_status/` (Linux `~/.cache/…`, macOS `~/Library/Caches/…`).
232    /// Database and log paths are separate.
233    #[arg(
234        long,
235        value_parser,
236        env = "DOMAIN_STATUS_CACHE_DIR",
237        hide_short_help = true,
238        help_heading = "Advanced"
239    )]
240    pub cache_dir: Option<PathBuf>,
241
242    /// Maximum time (seconds) to wait for in-flight tasks to finish after the
243    /// input queue is exhausted. Tasks still running after this window are
244    /// aborted and recorded in `url_failures` with the timeout reason.
245    /// Raise this for WHOIS-heavy small batches if scans report drain timeouts.
246    #[arg(
247        long,
248        default_value_t = 10,
249        env = "DOMAIN_STATUS_DRAIN_TIMEOUT_SECS",
250        hide_short_help = true,
251        help_heading = "Advanced"
252    )]
253    pub drain_timeout_secs: u64,
254
255    /// Enable WHOIS/RDAP (on by default). Prefer `--no-whois` to disable.
256    /// Kept for backward compatibility with scripts that pass `--enable-whois`.
257    #[arg(
258        long,
259        env = "DOMAIN_STATUS_ENABLE_WHOIS",
260        default_value_t = true,
261        hide = true
262    )]
263    pub enable_whois: bool,
264}
265
266/// Export command arguments.
267#[derive(Debug, Parser, Clone)]
268pub struct ExportCommand {
269    #[arg(
270        long,
271        value_parser,
272        default_value = "./domain_status.db",
273        env = "DOMAIN_STATUS_DB_PATH"
274    )]
275    pub db_path: PathBuf,
276
277    #[arg(long, value_enum, default_value = "csv")]
278    pub format: ExportFormat,
279
280    #[arg(long)]
281    pub output: Option<String>,
282
283    #[arg(long)]
284    pub run_id: Option<String>,
285
286    /// Exact match on `initial_domain` or `final_domain` (not a substring).
287    #[arg(long)]
288    pub domain: Option<String>,
289
290    #[arg(long)]
291    pub status: Option<u16>,
292
293    #[arg(long)]
294    pub since: Option<i64>,
295
296    /// Include fingerprint technologies with `is_implied = 1` in export output.
297    /// Default: only directly observed technologies.
298    #[arg(long, default_value_t = false)]
299    pub include_implied_tech: bool,
300}
301
302/// Summary command arguments.
303#[derive(Debug, Parser, Clone)]
304pub struct SummaryCommand {
305    #[arg(
306        long,
307        value_parser,
308        default_value = "./domain_status.db",
309        env = "DOMAIN_STATUS_DB_PATH"
310    )]
311    pub db_path: PathBuf,
312
313    /// Run id to summarize (default: most recent completed run).
314    #[arg(long)]
315    pub run_id: Option<String>,
316
317    /// How many top technologies to list (default: 15).
318    #[arg(long, default_value_t = 15)]
319    pub top: usize,
320}
321
322/// Exit code policy for handling failures.
323///
324/// Marked `#[non_exhaustive]` so adding new policies is not a breaking change.
325#[derive(Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
326#[non_exhaustive]
327pub enum FailOn {
328    /// Never exit with error code (always return 0).
329    #[default]
330    Never,
331    /// Exit with error if any URL failed.
332    #[value(name = "any-failure")]
333    AnyFailure,
334    /// Exit with error if failure percentage exceeds threshold (`pct>`).
335    #[value(name = "pct>")]
336    PctGreaterThan,
337}
338
339/// Logging level for the application.
340#[derive(Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
341pub enum LogLevel {
342    /// Only error messages.
343    Error,
344    /// Error and warning messages.
345    Warn,
346    /// Error, warning, and informational messages.
347    #[default]
348    Info,
349    /// All messages except trace.
350    Debug,
351    /// All messages including trace.
352    Trace,
353}
354
355/// Log output format.
356///
357/// Marked `#[non_exhaustive]` so adding new formats is not a breaking change.
358#[derive(Copy, Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
359#[non_exhaustive]
360pub enum LogFormat {
361    /// Human-readable. Scan `--log-file` is uncolored; export/summary stderr is colored.
362    #[default]
363    Plain,
364    /// Structured JSON format for machine parsing.
365    Json,
366}
367
368/// Export output format.
369#[derive(Debug, Clone, Default, clap::ValueEnum, PartialEq, Eq)]
370pub enum ExportFormat {
371    #[default]
372    Csv,
373    Jsonl,
374    Parquet,
375}
376
377/// Returns the full CLI `Command` for codegen (completions, man page) and for
378/// `--print-completions` / `--print-manpage`. Pass a static version string
379/// (e.g. `env!("DOMAIN_STATUS_VERSION")` or `env!("CARGO_PKG_VERSION")`).
380#[must_use]
381pub fn clap_command(version: &'static str) -> clap::Command {
382    CliCommand::command().version(version).long_version(version)
383}