dalfox-rs 0.5.1

//! Builder for orchestrating Dalfox process execution.
//!
//! The builder exposes every Dalfox CLI flag as a typed method,
//! separating the per-request timeout from the scan-level deadline
//! and providing validation before scan launch.

use crate::runner::DalfoxRunner;

/// Configuration for Dalfox scanning.
///
/// Constructed via [`super::Dalfox::builder()`]. All fields have sensible
/// defaults. Call [`.build()`](DalfoxBuilder::build) to finalize.
///
/// # Examples
///
/// ```rust
/// use dalfox_rs::Dalfox;
///
/// let runner = Dalfox::builder()
///     .request_timeout(10)
///     .scan_deadline(300)
///     .workers(50)
///     .waf_evasion(true)
///     .build();
/// ```
#[derive(Debug, Clone, Default)]
pub struct DalfoxBuilder {
    // --- Custom collections ---
    pub(crate) custom_headers: Vec<String>,
    pub(crate) payloads: Vec<String>,

    // --- Auth & Identity ---
    pub(crate) cookie: Option<String>,
    pub(crate) cookie_from_raw: Option<String>,
    pub(crate) user_agent: Option<String>,
    pub(crate) proxy: Option<String>,

    // --- Performance ---
    /// Per-request timeout passed to Dalfox's `--timeout` flag.
    pub(crate) request_timeout_secs: Option<u64>,
    /// Scan-level wall-clock deadline enforced by Tokio.
    pub(crate) scan_deadline_secs: Option<u64>,
    pub(crate) delay_ms: Option<u64>,
    pub(crate) workers: Option<u32>,

    // --- Engine Features ---
    #[allow(dead_code)]
    pub(crate) use_headless: bool,
    #[allow(dead_code)]
    pub(crate) deep_domxss: bool,
    #[allow(dead_code)]
    pub(crate) skip_headless: bool,
    #[allow(dead_code)]
    pub(crate) skip_bav: bool,
    pub(crate) skip_mining_all: bool,
    pub(crate) skip_mining_dom: bool,
    pub(crate) skip_mining_dict: bool,
    pub(crate) only_discovery: bool,
    pub(crate) only_custom_payload: bool,
    pub(crate) follow_redirects: bool,
    pub(crate) waf_evasion: bool,
    pub(crate) debug_mode: bool,
    pub(crate) silence: bool,

    // --- Parameters & Scopes ---
    pub(crate) params: Vec<String>,
    pub(crate) mining_dict: Option<String>,
    pub(crate) method: Option<String>,
    pub(crate) data: Option<String>,
    /// Comma-separated HTTP status codes to ignore (e.g. "302,403,404").
    pub(crate) ignore_return_codes: Option<String>,

    // --- Payloads & PoC ---
    pub(crate) blind_callback: Option<String>,
    pub(crate) remote_payloads: Option<String>,
    pub(crate) remote_wordlists: Option<String>,
    pub(crate) custom_alert_value: Option<String>,
    pub(crate) only_poc: Option<String>,
    pub(crate) poc_type: Option<String>,

    // --- Output ---
    #[allow(dead_code)]
    pub(crate) found_action: Option<String>,
    pub(crate) output_file: Option<String>,
    #[allow(dead_code)]
    pub(crate) output_all: bool,

    // --- System ---
    pub(crate) binary_path: Option<String>,
}

impl DalfoxBuilder {
    /// Creates a new builder with all defaults.
    pub fn new() -> Self {
        Self::default()
    }

    // ── Auth & Identity ──────────────────────────────────────────

    /// Sets the raw cookie header value.
    pub fn cookie(mut self, cookie: impl Into<String>) -> Self {
        self.cookie = Some(cookie.into());
        self
    }

    /// Loads cookies from a Burp Suite raw HTTP request file.
    pub fn cookie_from_raw(mut self, file_path: impl Into<String>) -> Self {
        self.cookie_from_raw = Some(file_path.into());
        self
    }

    /// Sets the User-Agent header.
    pub fn user_agent(mut self, user_agent: impl Into<String>) -> Self {
        self.user_agent = Some(user_agent.into());
        self
    }

    /// Routes all requests through an HTTP/HTTPS proxy.
    pub fn proxy(mut self, proxy_url: impl Into<String>) -> Self {
        self.proxy = Some(proxy_url.into());
        self
    }

    // ── Performance ──────────────────────────────────────────────

    /// Per-request timeout in seconds (Dalfox's `--timeout` flag).
    ///
    /// This controls how long each individual HTTP request can take.
    /// For the overall scan deadline, use [`scan_deadline`](Self::scan_deadline).
    pub fn request_timeout(mut self, seconds: u64) -> Self {
        self.request_timeout_secs = Some(seconds);
        self
    }

    /// Overall scan deadline in seconds, enforced by the Tokio runtime.
    ///
    /// If the entire scan (all URLs, all parameters) exceeds this duration,
    /// the process is killed and [`crate::DalfoxError::ScanDeadlineExceeded`] is returned.
    /// This is independent of Dalfox's per-request `--timeout`.
    pub fn scan_deadline(mut self, seconds: u64) -> Self {
        self.scan_deadline_secs = Some(seconds);
        self
    }

    /// Backwards-compatible alias: sets BOTH request timeout and scan deadline.
    ///
    /// Prefer [`request_timeout`](Self::request_timeout) and
    /// [`scan_deadline`](Self::scan_deadline) for precise control.
    pub fn timeout(mut self, seconds: u64) -> Self {
        self.request_timeout_secs = Some(seconds);
        self.scan_deadline_secs = Some(seconds);
        self
    }

    /// Delay in milliseconds between requests to the same host.
    pub fn delay(mut self, milliseconds: u64) -> Self {
        self.delay_ms = Some(milliseconds);
        self
    }

    /// Number of concurrent workers (default: Dalfox's default of 100).
    pub fn workers(mut self, count: u32) -> Self {
        self.workers = Some(count);
        self
    }

    // ── Engine Features ──────────────────────────────────────────

    /// Enable headless browser for DOM XSS detection.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --use-headless; this builder method is a no-op"
    )]
    pub fn headless(mut self, enable: bool) -> Self {
        self.use_headless = enable;
        self
    }

    /// Enable extended DOM XSS testing with additional payloads on headless browser.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --deep-domxss; this builder method is a no-op"
    )]
    pub fn deep_domxss(mut self, enable: bool) -> Self {
        self.deep_domxss = enable;
        self
    }

    /// Skip headless browser-based scanning entirely.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --skip-headless; this builder method is a no-op"
    )]
    pub fn skip_headless(mut self, skip: bool) -> Self {
        self.skip_headless = skip;
        self
    }

    /// Skip Basic Antivirus (BAV) analysis.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --skip-bav; this builder method is a no-op"
    )]
    pub fn skip_bav(mut self, skip: bool) -> Self {
        self.skip_bav = skip;
        self
    }

    /// Skip all parameter mining (dictionary + DOM).
    pub fn skip_mining_all(mut self, skip: bool) -> Self {
        self.skip_mining_all = skip;
        self
    }

    /// Skip DOM-based parameter mining.
    pub fn skip_mining_dom(mut self, skip: bool) -> Self {
        self.skip_mining_dom = skip;
        self
    }

    /// Skip dictionary-based parameter mining.
    pub fn skip_mining_dict(mut self, skip: bool) -> Self {
        self.skip_mining_dict = skip;
        self
    }

    /// Only perform parameter discovery without XSS scanning.
    ///
    /// Useful for reconnaissance phases where you want to map injectable
    /// parameters without sending attack payloads.
    pub fn only_discovery(mut self, enable: bool) -> Self {
        self.only_discovery = enable;
        self
    }

    /// Only test custom payloads (requires prior `.payload()` calls).
    pub fn only_custom_payload(mut self, enable: bool) -> Self {
        self.only_custom_payload = enable;
        self
    }

    /// Follow HTTP 3xx redirections during scanning.
    pub fn follow_redirects(mut self, enable: bool) -> Self {
        self.follow_redirects = enable;
        self
    }

    /// Enable WAF evasion techniques (adjusts request timing and encoding).
    pub fn waf_evasion(mut self, enable: bool) -> Self {
        self.waf_evasion = enable;
        self
    }

    /// Enable Dalfox debug mode (saves all internal logs).
    pub fn debug(mut self, enable: bool) -> Self {
        self.debug_mode = enable;
        self
    }

    /// Silence mode: only print PoC code and progress.
    pub fn silence(mut self, enable: bool) -> Self {
        self.silence = enable;
        self
    }

    // ── Parameters & Scopes ──────────────────────────────────────

    /// Test only specific parameters.
    ///
    /// Accepts a comma-separated list (e.g. `"id,q,lang"`) or a single name.
    /// Each name is emitted as a separate `--param` flag (Dalfox v3 grammar).
    /// Can be called multiple times.
    pub fn param(mut self, params: impl Into<String>) -> Self {
        for name in params.into().split(',') {
            let trimmed = name.trim();
            if !trimmed.is_empty() {
                self.params.push(trimmed.to_string());
            }
        }
        self
    }

    /// Custom mining dictionary wordlist file path.
    pub fn mining_dict(mut self, path: impl Into<String>) -> Self {
        self.mining_dict = Some(path.into());
        self
    }

    /// Force a specific HTTP method (e.g. "GET", "POST", "PUT").
    pub fn method(mut self, method: impl Into<String>) -> Self {
        self.method = Some(method.into());
        self
    }

    /// Raw POST/PUT body data.
    pub fn data(mut self, body: impl Into<String>) -> Self {
        self.data = Some(body.into());
        self
    }

    /// Ignore specific HTTP return codes during scanning.
    ///
    /// Accepts a comma-separated list of status codes (e.g. "302,403,404").
    pub fn ignore_return(mut self, codes: impl Into<String>) -> Self {
        self.ignore_return_codes = Some(codes.into());
        self
    }

    // ── Payloads & PoC ───────────────────────────────────────────

    /// Path to a custom payload file passed to Dalfox's `--custom-payload`.
    ///
    /// Dalfox reads payloads from the file (one per line), not inline strings.
    /// Can be called multiple times to pass multiple files.
    pub fn payload(mut self, file_path: impl Into<String>) -> Self {
        self.payloads.push(file_path.into());
        self
    }

    /// Add a custom HTTP header to all requests.
    ///
    /// Can be called multiple times. Format: "Header-Name: value".
    pub fn header(mut self, header: impl Into<String>) -> Self {
        self.custom_headers.push(header.into());
        self
    }

    /// Set the blind XSS callback URL (e.g. `https://xss.requestcatcher.com`).
    pub fn blind_callback(mut self, url: impl Into<String>) -> Self {
        self.blind_callback = Some(url.into());
        self
    }

    /// Remote payloads URL source.
    pub fn remote_payloads(mut self, source: impl Into<String>) -> Self {
        self.remote_payloads = Some(source.into());
        self
    }

    /// Remote wordlist for parameter mining.
    pub fn remote_wordlists(mut self, source: impl Into<String>) -> Self {
        self.remote_wordlists = Some(source.into());
        self
    }

    /// Change the alert value used in XSS payloads (default: "1").
    pub fn custom_alert_value(mut self, value: impl Into<String>) -> Self {
        self.custom_alert_value = Some(value.into());
        self
    }

    /// Filter which finding types Dalfox emits (e.g. `"v,r,a"` for verified, reflected, AST).
    pub fn only_poc(mut self, filter: impl Into<String>) -> Self {
        self.only_poc = Some(filter.into());
        self
    }

    /// Select PoC output format: "plain", "curl", "httpie", or "http-request".
    pub fn poc_type(mut self, poc_type: impl Into<String>) -> Self {
        self.poc_type = Some(poc_type.into());
        self
    }

    // ── Output ───────────────────────────────────────────────────

    /// Execute a shell command when a vulnerability is found.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --found-action; this builder method is a no-op"
    )]
    pub fn found_action(mut self, command: impl Into<String>) -> Self {
        self.found_action = Some(command.into());
        self
    }

    /// Write Dalfox's raw output to a file path.
    pub fn output_file(mut self, path: impl Into<String>) -> Self {
        self.output_file = Some(path.into());
        self
    }

    /// Write all logs (not just findings) to the output destination.
    ///
    /// **Deprecated:** Dalfox v3 removed this flag. The method is a no-op kept for API compatibility.
    #[deprecated(
        since = "0.3.0",
        note = "Dalfox v3 removed --output-all; this builder method is a no-op"
    )]
    pub fn output_all(mut self, enable: bool) -> Self {
        self.output_all = enable;
        self
    }

    // ── System ───────────────────────────────────────────────────

    /// Explicitly set the path to the `dalfox` binary.
    ///
    /// If not provided, the binary is resolved via the system `$PATH`.
    pub fn binary_path(mut self, path: impl Into<String>) -> Self {
        self.binary_path = Some(path.into());
        self
    }

    /// Finalizes the configuration and returns a runner ready to scan.
    pub fn build(self) -> DalfoxRunner {
        DalfoxRunner::new(self)
    }
}