dalfox-rs 0.5.5

Type-safe asynchronous wrapper for the Dalfox XSS scanner (Dalfox ≥3) with JSON findings, stored XSS support, and multi-format result formatting
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

//! Error types for the Dalfox wrapper.
//!
//! Every error variant carries actionable context so callers can diagnose
//! failures without needing to inspect raw process output manually.

use thiserror::Error;

/// Core error type representing failures inside dalfox-rs.
///
/// All variants are `#[non_exhaustive]` so future Dalfox versions can
/// introduce new failure modes without breaking downstream callers.
#[derive(Error, Debug)]
#[non_exhaustive]
pub enum DalfoxError {
    /// Failed to spawn or communicate with the `dalfox` binary.
    #[error("failed to execute dalfox binary: {0}")]
    ExecutionFailed(#[from] std::io::Error),

    /// The Dalfox process exited with a non-zero status code, or emitted structured
    /// error JSON (`{"error":true,...}`) on stdout or stderr.
    ///
    /// `stderr` contains the captured diagnostic output from Dalfox,
    /// which typically includes the root cause of the failure. When findings
    /// were parsed before a non-zero exit, the message notes the partial count.
    #[error("dalfox process exited with status {status}: {stderr}")]
    ProcessFailed {
        /// OS exit status code.
        status: i32,
        /// Captured stderr output from the process.
        stderr: String,
    },

    /// Reserved: JSON parse failures from Dalfox stdout are **not** surfaced here.
    ///
    /// Batch scans (`--format json`) and streaming scans (`--format jsonl`) accumulate
    /// unparseable **line** output in [`DalfoxResult::parse_errors`](crate::types::DalfoxResult::parse_errors).
    /// Total batch envelope parse failure (non-empty stdout, zero findings) returns
    /// [`ProcessFailed`](Self::ProcessFailed) instead of soft `Ok`. Use
    /// [`DalfoxResult::has_parse_errors`](crate::types::DalfoxResult::has_parse_errors) for
    /// per-line JSONL issues instead of matching on this variant.
    ///
    /// The runner does not construct `ParseError` today; the variant remains for forward
    /// compatibility and manual `serde_json::Error` conversion via `?`.
    #[error("failed to parse dalfox JSON output: {0}")]
    ParseError(#[from] serde_json::Error),

    /// The scan exceeded the configured deadline.
    ///
    /// This is distinct from Dalfox's per-request `--timeout` flag.
    /// The scan deadline is the maximum wall-clock time for the entire
    /// scan operation, enforced by the Tokio runtime.
    #[error("dalfox scan exceeded deadline of {deadline_secs} seconds")]
    ScanDeadlineExceeded {
        /// The configured deadline in seconds.
        deadline_secs: u64,
    },

    /// The `dalfox` binary could not be found at the configured path.
    #[error("dalfox binary not found at '{path}': ensure dalfox is installed and in PATH")]
    BinaryNotFound {
        /// The path that was searched.
        path: String,
    },
}