dalfox-rs

Available on Crates.io: https://crates.io/crates/dalfox-rs

A strictly-typed, asynchronous Rust binding for the Dalfox XSS Scanner (v3+).

dalfox-rs wraps the Dalfox binary, parses its JSON output into typed Rust structs, and makes XSS scanning composable inside fuzzers, proxies, or CI/CD pipelines.

Features

• Dalfox v3 CLI — scan, file, and pipe modes with typed builder flags
• Dalfox v3 finding shape — parses v3 JSON without legacy poc; use finding.poc_url() or finding.data
• Streaming callbacks — *_streaming methods use --format jsonl and emit findings as lines when present
• Stored XSS — --sxss / --sxss-url on dalfox scan
• Multi-format output — JSON, CSV, Markdown, and plain text via format_as()
• Diagnostic capture — stderr, parse errors, exit codes all preserved
• Result filtering — query by severity, event type, or verified status

Installation

[dependencies]
dalfox-rs = "0.5.1"
tokio = { version = "1", features = ["full"] }

Prerequisite: Dalfox v3 (^3.1) must be in your system $PATH or specified via .binary_path().

Setup (one-command)

Option A: Setup script (auto-detects Go/Homebrew or downloads binary)

./setup.sh

Option B: Go install

go install github.com/hahwul/dalfox/v3@latest

Option C: Homebrew

brew install dalfox

Option D: Pre-built binary

./setup.sh --binary
# installs to ~/.local/bin/dalfox

Quick Start

use dalfox_rs::{Dalfox, DalfoxResult, OutputFormat};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runner = Dalfox::builder()
        .request_timeout(10)   // per-request timeout (seconds)
        .scan_deadline(300)    // overall scan deadline (seconds)
        .workers(100)
        .build();

    let result: DalfoxResult = runner.scan_url("http://example.com?q=test").await?;

    for finding in &result.findings {
        println!("{}", finding); // Display impl gives readable output
    }

    // Output as CSV for spreadsheet import
    println!("{}", result.format_as(OutputFormat::Csv));

    Ok(())
}

Streaming Output

*_streaming methods pass --format jsonl to Dalfox. Each verified finding line is parsed and forwarded to your callback as it arrives (meta-only lines are ignored):

let result = runner.scan_url_streaming("http://example.com?q=test", |finding| {
    eprintln!("LIVE: {}", finding);
}).await?;

Stored XSS (sxss mode)

Detect persistent XSS via separate injection and trigger URLs:

let result = runner.scan_sxss(
    "http://example.com/comment?body=test",  // inject here
    "http://example.com/view-comments",       // check here
).await?;

Advanced Configuration

let runner = Dalfox::builder()
    .waf_evasion(true)
    .cookie("session_id=12345")
    .header("Authorization: Bearer my_token")
    .delay(500)
    .param("id,q,lang")   // repeated --param id --param q --param lang
    .payload("payloads.txt")  // file path for --custom-payload
    .blind_callback("https://my.callback.domain.com")
    .follow_redirects(true)
    .ignore_return("302,403,404")
    .binary_path("/usr/local/bin/dalfox")
    .build();

Result Filtering

let verified = result.verified_findings();
let critical = result.high_severity_findings();

if result.has_parse_errors() {
    eprintln!("Warning: {} output lines failed to parse", result.parse_errors.len());
}

Execution Modes

All modes have _streaming variants for jsonl finding callbacks.

License

MIT License