dalfox-rs 0.3.0

//! Strictly-typed structures for Dalfox scan results.
//!
//! Every field from Dalfox's JSON output is mapped to a concrete Rust type,
//! with enums for known-finite value sets and `Other`/`Unknown` fallbacks
//! for forward compatibility with newer Dalfox versions.

use serde::{Deserialize, Serialize};
use std::fmt;

/// The classification of a finding event.
///
/// Dalfox emits different event types depending on the confidence
/// and nature of the detection.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum EventType {
    /// Verified XSS vulnerability with confirmed execution.
    #[serde(rename = "V")]
    Verified,
    /// Grep-based match (information disclosure, sensitive patterns).
    #[serde(rename = "G")]
    Grep,
    /// Informational finding (no direct vulnerability).
    #[serde(rename = "I")]
    Information,
    /// Reflected parameter detected but unverified.
    #[serde(rename = "R")]
    Reflected,
    /// AST-based DOM XSS detection.
    #[serde(rename = "A")]
    Ast,
    /// Unknown event type from a newer Dalfox version.
    #[serde(untagged)]
    Other(String),
}

impl fmt::Display for EventType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Verified => write!(f, "Verified"),
            Self::Grep => write!(f, "Grep"),
            Self::Information => write!(f, "Info"),
            Self::Reflected => write!(f, "Reflected"),
            Self::Ast => write!(f, "AST"),
            Self::Other(s) => write!(f, "{s}"),
        }
    }
}

/// Vulnerability severity as reported by Dalfox.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Severity {
    /// High severity (critical/high impact XSS).
    #[serde(rename = "High")]
    High,
    /// Medium severity.
    #[serde(rename = "Medium")]
    Medium,
    /// Low severity.
    #[serde(rename = "Low")]
    Low,
    /// Informational severity.
    #[serde(rename = "Information", alias = "Info")]
    Information,
    /// Unknown severity from a newer Dalfox version.
    #[serde(untagged)]
    Unknown(String),
}

impl fmt::Display for Severity {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::High => write!(f, "High"),
            Self::Medium => write!(f, "Medium"),
            Self::Low => write!(f, "Low"),
            Self::Information => write!(f, "Info"),
            Self::Unknown(s) => write!(f, "{s}"),
        }
    }
}

/// HTTP method used in the finding.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Method {
    /// HTTP GET.
    #[serde(rename = "GET")]
    Get,
    /// HTTP POST.
    #[serde(rename = "POST")]
    Post,
    /// HTTP PUT.
    #[serde(rename = "PUT")]
    Put,
    /// HTTP DELETE.
    #[serde(rename = "DELETE")]
    Delete,
    /// HTTP HEAD.
    #[serde(rename = "HEAD")]
    Head,
    /// HTTP OPTIONS.
    #[serde(rename = "OPTIONS")]
    Options,
    /// HTTP PATCH.
    #[serde(rename = "PATCH")]
    Patch,
    /// Other or custom HTTP method.
    #[serde(untagged)]
    Other(String),
}

impl fmt::Display for Method {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Get => write!(f, "GET"),
            Self::Post => write!(f, "POST"),
            Self::Put => write!(f, "PUT"),
            Self::Delete => write!(f, "DELETE"),
            Self::Head => write!(f, "HEAD"),
            Self::Options => write!(f, "OPTIONS"),
            Self::Patch => write!(f, "PATCH"),
            Self::Other(s) => write!(f, "{s}"),
        }
    }
}

/// A structured finding reported by Dalfox via its JSON output.
///
/// Each finding represents a single detected XSS vector with full
/// contextual information about the injection point, payload, and evidence.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct DalfoxFinding {
    /// The classification of this finding (verified, grep, info, reflected).
    #[serde(rename = "type")]
    pub event_type: EventType,

    /// The proof-of-concept URL demonstrating the vulnerability.
    pub poc: String,

    /// HTTP method used for the scan request.
    pub method: Method,

    /// Request body data (populated for POST, PUT, etc).
    #[serde(default)]
    pub data: String,

    /// The specific parameter that was injected.
    pub param: String,

    /// The actual XSS payload used.
    pub payload: String,

    /// The response snippet verifying payload reflection or execution.
    #[serde(default)]
    pub evidence: String,

    /// CWE classification identifier (e.g. "CWE-79").
    pub cwe: String,

    /// The vulnerability severity rating.
    pub severity: Severity,
}

impl fmt::Display for DalfoxFinding {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "[{sev}][{evt}] {cwe} on param '{param}' via {method} — {poc}",
            sev = self.severity,
            evt = self.event_type,
            cwe = self.cwe,
            param = self.param,
            method = self.method,
            poc = self.poc,
        )
    }
}

/// Top-level JSON document emitted by Dalfox v3 with `--format json`.
#[derive(Debug, Clone, Deserialize)]
pub(crate) struct DalfoxJsonEnvelope {
    /// Parsed XSS findings from the scan.
    #[serde(default)]
    pub findings: Vec<DalfoxFinding>,
    /// Scan metadata (version, timing, counts). Ignored if absent or unparseable.
    #[serde(default)]
    pub meta: Option<serde_json::Value>,
}

/// Aggregate results from a Dalfox scan execution.
///
/// Contains the parsed findings, diagnostic metadata, and any parse errors
/// encountered while processing Dalfox's output stream.
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct DalfoxResult {
    /// The detected XSS findings from the scan.
    pub findings: Vec<DalfoxFinding>,

    /// Lines from Dalfox output that failed to parse as valid findings.
    ///
    /// Non-empty values indicate a potential Dalfox schema change or
    /// corrupted output. Each entry contains `"parse_error: raw_line"`.
    pub parse_errors: Vec<String>,

    /// Captured stderr output from the Dalfox process.
    ///
    /// Contains warnings, progress information, and diagnostic messages
    /// emitted by the Dalfox binary during execution.
    pub stderr_output: String,

    /// The exit code of the Dalfox process, if available.
    pub exit_code: Option<i32>,

    /// Wall-clock duration of the scan.
    pub scan_duration: Option<std::time::Duration>,

    /// Optional metadata from Dalfox's JSON envelope (`meta` field).
    pub meta: Option<serde_json::Value>,
}

/// Supported output formats for scan results.
///
/// Use with [`DalfoxResult::format_as`] to convert findings into
/// the desired output representation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum OutputFormat {
    /// Compact single-line JSON array.
    Json,
    /// Pretty-printed JSON array.
    JsonPretty,
    /// Comma-separated values with header row.
    Csv,
    /// GitHub-flavored Markdown table.
    Markdown,
    /// Human-readable plain text report.
    Plain,
}

impl DalfoxResult {
    /// Format the scan results in the specified output format.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use dalfox_rs::types::{DalfoxResult, OutputFormat};
    /// let result = DalfoxResult::default();
    /// let csv = result.format_as(OutputFormat::Csv);
    /// assert!(csv.starts_with("severity,"));
    /// ```
    pub fn format_as(&self, format: OutputFormat) -> String {
        match format {
            OutputFormat::Json => self.format_json(false),
            OutputFormat::JsonPretty => self.format_json(true),
            OutputFormat::Csv => self.format_csv(),
            OutputFormat::Markdown => self.format_markdown(),
            OutputFormat::Plain => self.format_plain(),
        }
    }

    fn format_json(&self, pretty: bool) -> String {
        let result = if pretty {
            serde_json::to_string_pretty(&self.findings)
        } else {
            serde_json::to_string(&self.findings)
        };
        // Vec<DalfoxFinding> serialization is infallible for well-formed types,
        // but we handle the impossible case gracefully.
        match result {
            Ok(json) => json,
            Err(err) => format!("{{\"error\": \"serialization failed: {err}\"}}"),
        }
    }

    fn format_csv(&self) -> String {
        let mut buf = String::from("severity,type,method,param,cwe,poc,payload,evidence\n");
        for finding in &self.findings {
            buf.push_str(&format!(
                "{},{},{},{},{},{},{},{}\n",
                csv_escape(&finding.severity.to_string()),
                csv_escape(&finding.event_type.to_string()),
                csv_escape(&finding.method.to_string()),
                csv_escape(&finding.param),
                csv_escape(&finding.cwe),
                csv_escape(&finding.poc),
                csv_escape(&finding.payload),
                csv_escape(&finding.evidence),
            ));
        }
        buf
    }

    fn format_markdown(&self) -> String {
        if self.findings.is_empty() {
            return "No findings.\n".to_string();
        }
        let mut buf =
            String::from("| Severity | Type | Method | Param | CWE | PoC | Payload |\n");
        buf.push_str("|----------|------|--------|-------|-----|-----|----------|\n");
        for finding in &self.findings {
            buf.push_str(&format!(
                "| {} | {} | {} | `{}` | {} | [link]({}) | `{}` |\n",
                finding.severity,
                finding.event_type,
                finding.method,
                finding.param,
                finding.cwe,
                finding.poc,
                md_escape(&finding.payload),
            ));
        }
        buf
    }

    fn format_plain(&self) -> String {
        if self.findings.is_empty() {
            return "No XSS findings detected.\n".to_string();
        }
        let mut buf = format!("=== {} Finding(s) ===\n\n", self.findings.len());
        for (i, finding) in self.findings.iter().enumerate() {
            let evidence_display = if finding.evidence.is_empty() {
                "(none)"
            } else {
                &finding.evidence
            };
            buf.push_str(&format!(
                "#{} [{}] {} ({})\n  Parameter: {}\n  Method:    {}\n  PoC:       {}\n  Payload:   {}\n  Evidence:  {}\n\n",
                i + 1,
                finding.severity,
                finding.cwe,
                finding.event_type,
                finding.param,
                finding.method,
                finding.poc,
                finding.payload,
                evidence_display,
            ));
        }
        if !self.parse_errors.is_empty() {
            buf.push_str(&format!(
                "--- {} Parse Error(s) ---\n",
                self.parse_errors.len()
            ));
            for err in &self.parse_errors {
                buf.push_str(&format!("  • {err}\n"));
            }
        }
        buf
    }
}

/// Escape a value for CSV output.
fn csv_escape(value: &str) -> String {
    if value.contains(',') || value.contains('"') || value.contains('\n') {
        format!("\"{}\"", value.replace('"', "\"\""))
    } else {
        value.to_string()
    }
}

/// Escape pipe and backtick characters for Markdown table cells.
fn md_escape(value: &str) -> String {
    value.replace('|', "\\|").replace('`', "\\`")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn finding_deserialize() {
        let json = r#"{"type":"V","poc":"http://example.com?q=%3Cscript%3Ealert(1)%3C/script%3E","method":"GET","data":"","param":"q","payload":"<script>alert(1)</script>","evidence":"<script>alert(1)</script>","cwe":"CWE-79","severity":"High"}"#;
        let finding: DalfoxFinding = serde_json::from_str(json).expect("valid finding JSON");
        assert_eq!(finding.event_type, EventType::Verified);
        assert_eq!(finding.param, "q");
        assert_eq!(finding.severity, Severity::High);
        assert_eq!(finding.cwe, "CWE-79");
        assert_eq!(finding.method, Method::Get);
    }

    #[test]
    fn event_type_variants() {
        assert_eq!(
            serde_json::from_str::<EventType>("\"V\"").expect("verified"),
            EventType::Verified
        );
        assert_eq!(
            serde_json::from_str::<EventType>("\"G\"").expect("grep"),
            EventType::Grep
        );
        assert_eq!(
            serde_json::from_str::<EventType>("\"I\"").expect("info"),
            EventType::Information
        );
        assert_eq!(
            serde_json::from_str::<EventType>("\"R\"").expect("reflected"),
            EventType::Reflected
        );
        assert_eq!(
            serde_json::from_str::<EventType>("\"XNEW\"").expect("unknown"),
            EventType::Other("XNEW".to_string())
        );
    }

    #[test]
    fn severity_aliases() {
        assert_eq!(
            serde_json::from_str::<Severity>("\"Info\"").expect("info alias"),
            Severity::Information
        );
        assert_eq!(
            serde_json::from_str::<Severity>("\"Information\"").expect("info full"),
            Severity::Information
        );
        assert_eq!(
            serde_json::from_str::<Severity>("\"POTENTIAL\"").expect("unknown"),
            Severity::Unknown("POTENTIAL".to_string())
        );
    }

    #[test]
    fn method_patch_variant() {
        assert_eq!(
            serde_json::from_str::<Method>("\"PATCH\"").expect("patch"),
            Method::Patch
        );
        assert_eq!(
            serde_json::from_str::<Method>("\"CUSTOM\"").expect("custom"),
            Method::Other("CUSTOM".to_string())
        );
    }

    #[test]
    fn result_default_is_empty() {
        let result = DalfoxResult::default();
        assert!(result.findings.is_empty());
        assert!(result.parse_errors.is_empty());
        assert!(result.stderr_output.is_empty());
        assert!(result.exit_code.is_none());
        assert!(result.scan_duration.is_none());
        assert!(result.meta.is_none());
    }

    #[test]
    fn json_envelope_deserialize_with_meta() {
        let json = r#"{"findings":[],"meta":{"dalfox_version":"3.1.2","targets_input":1}}"#;
        let envelope: DalfoxJsonEnvelope =
            serde_json::from_str(json).expect("valid v3 JSON envelope");
        assert!(envelope.findings.is_empty());
        let meta = envelope.meta.expect("meta present");
        assert_eq!(meta["dalfox_version"], "3.1.2");
    }

    #[test]
    fn json_envelope_deserialize_findings_and_meta() {
        let json = r#"{
            "findings":[{"type":"V","poc":"http://example.com","method":"GET","param":"q","payload":"x","cwe":"CWE-79","severity":"High"}],
            "meta":{"dalfox_version":"3.1.2"}
        }"#;
        let envelope: DalfoxJsonEnvelope =
            serde_json::from_str(json).expect("valid envelope with findings");
        assert_eq!(envelope.findings.len(), 1);
        assert_eq!(envelope.findings[0].event_type, EventType::Verified);
    }

    #[test]
    fn event_type_ast_variant() {
        assert_eq!(
            serde_json::from_str::<EventType>("\"A\"").expect("ast"),
            EventType::Ast
        );
        assert_eq!(EventType::Ast.to_string(), "AST");
    }

    #[test]
    fn format_csv_header() {
        let result = DalfoxResult::default();
        let csv = result.format_as(OutputFormat::Csv);
        assert!(csv.starts_with("severity,type,method,param,cwe,poc,payload,evidence\n"));
    }

    #[test]
    fn format_plain_empty() {
        let result = DalfoxResult::default();
        let plain = result.format_as(OutputFormat::Plain);
        assert_eq!(plain, "No XSS findings detected.\n");
    }

    #[test]
    fn format_markdown_empty() {
        let result = DalfoxResult::default();
        let md = result.format_as(OutputFormat::Markdown);
        assert_eq!(md, "No findings.\n");
    }

    #[test]
    fn csv_escape_handles_commas_and_quotes() {
        assert_eq!(csv_escape("hello,world"), "\"hello,world\"");
        assert_eq!(csv_escape("say \"hi\""), "\"say \"\"hi\"\"\"");
        assert_eq!(csv_escape("simple"), "simple");
    }

    #[test]
    fn display_impls_are_readable() {
        assert_eq!(EventType::Verified.to_string(), "Verified");
        assert_eq!(Severity::High.to_string(), "High");
        assert_eq!(Method::Get.to_string(), "GET");
    }
}