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    #[arg(
212        long,
213        env = "DOMAIN_STATUS_STATUS_PORT",
214        hide_short_help = true,
215        help_heading = "Advanced"
216    )]
217    pub status_port: Option<u16>,
218
219    /// Shared cache root for fingerprints, GeoIP, WHOIS, and User-Agent data.
220    /// Defaults to `$DOMAIN_STATUS_CACHE_DIR` or the platform cache dir +
221    /// `domain_status/` (Linux `~/.cache/…`, macOS `~/Library/Caches/…`).
222    /// Database and log paths are separate.
223    #[arg(
224        long,
225        value_parser,
226        env = "DOMAIN_STATUS_CACHE_DIR",
227        hide_short_help = true,
228        help_heading = "Advanced"
229    )]
230    pub cache_dir: Option<PathBuf>,
231
232    /// Maximum time (seconds) to wait for in-flight tasks to finish after the
233    /// input queue is exhausted. Tasks still running after this window are
234    /// aborted and recorded in `url_failures` with the timeout reason.
235    /// Raise this for WHOIS-heavy small batches if scans report drain timeouts.
236    #[arg(
237        long,
238        default_value_t = 10,
239        env = "DOMAIN_STATUS_DRAIN_TIMEOUT_SECS",
240        hide_short_help = true,
241        help_heading = "Advanced"
242    )]
243    pub drain_timeout_secs: u64,
244
245    /// Enable WHOIS/RDAP (on by default). Prefer `--no-whois` to disable.
246    /// Kept for backward compatibility with scripts that pass `--enable-whois`.
247    #[arg(
248        long,
249        env = "DOMAIN_STATUS_ENABLE_WHOIS",
250        default_value_t = true,
251        hide = true
252    )]
253    pub enable_whois: bool,
254}
255
256/// Export command arguments.
257#[derive(Debug, Parser, Clone)]
258pub struct ExportCommand {
259    #[arg(
260        long,
261        value_parser,
262        default_value = "./domain_status.db",
263        env = "DOMAIN_STATUS_DB_PATH"
264    )]
265    pub db_path: PathBuf,
266
267    #[arg(long, value_enum, default_value = "csv")]
268    pub format: ExportFormat,
269
270    #[arg(long)]
271    pub output: Option<String>,
272
273    #[arg(long)]
274    pub run_id: Option<String>,
275
276    /// Exact match on `initial_domain` or `final_domain` (not a substring).
277    #[arg(long)]
278    pub domain: Option<String>,
279
280    #[arg(long)]
281    pub status: Option<u16>,
282
283    #[arg(long)]
284    pub since: Option<i64>,
285
286    /// Include fingerprint technologies with `is_implied = 1` in export output.
287    /// Default: only directly observed technologies.
288    #[arg(long, default_value_t = false)]
289    pub include_implied_tech: bool,
290}
291
292/// Summary command arguments.
293#[derive(Debug, Parser, Clone)]
294pub struct SummaryCommand {
295    #[arg(
296        long,
297        value_parser,
298        default_value = "./domain_status.db",
299        env = "DOMAIN_STATUS_DB_PATH"
300    )]
301    pub db_path: PathBuf,
302
303    /// Run id to summarize (default: most recent completed run).
304    #[arg(long)]
305    pub run_id: Option<String>,
306
307    /// How many top technologies to list (default: 15).
308    #[arg(long, default_value_t = 15)]
309    pub top: usize,
310}
311
312/// Exit code policy for handling failures.
313///
314/// Marked `#[non_exhaustive]` so adding new policies is not a breaking change.
315#[derive(Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
316#[non_exhaustive]
317pub enum FailOn {
318    /// Never exit with error code (always return 0).
319    #[default]
320    Never,
321    /// Exit with error if any URL failed.
322    #[value(name = "any-failure")]
323    AnyFailure,
324    /// Exit with error if failure percentage exceeds threshold (`pct>`).
325    #[value(name = "pct>")]
326    PctGreaterThan,
327}
328
329/// Logging level for the application.
330#[derive(Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
331pub enum LogLevel {
332    /// Only error messages.
333    Error,
334    /// Error and warning messages.
335    Warn,
336    /// Error, warning, and informational messages.
337    #[default]
338    Info,
339    /// All messages except trace.
340    Debug,
341    /// All messages including trace.
342    Trace,
343}
344
345/// Log output format.
346///
347/// Marked `#[non_exhaustive]` so adding new formats is not a breaking change.
348#[derive(Copy, Clone, Debug, Default, clap::ValueEnum, PartialEq, Eq)]
349#[non_exhaustive]
350pub enum LogFormat {
351    /// Human-readable. Scan `--log-file` is uncolored; export/summary stderr is colored.
352    #[default]
353    Plain,
354    /// Structured JSON format for machine parsing.
355    Json,
356}
357
358/// Export output format.
359#[derive(Debug, Clone, Default, clap::ValueEnum, PartialEq, Eq)]
360pub enum ExportFormat {
361    #[default]
362    Csv,
363    Jsonl,
364    Parquet,
365}
366
367/// Returns the full CLI `Command` for codegen (completions, man page) and for
368/// `--print-completions` / `--print-manpage`. Pass a static version string
369/// (e.g. `env!("DOMAIN_STATUS_VERSION")` or `env!("CARGO_PKG_VERSION")`).
370#[must_use]
371pub fn clap_command(version: &'static str) -> clap::Command {
372    CliCommand::command().version(version).long_version(version)
373}