DOCSEARCHbyAlgolia
Submit Docs

dalfox

repository·main·Indexed 26 days ago

https://github.com/hahwul/dalfox

An open-source XSS scanner and automation tool written in Rust for scanning XSS flaws and analyzing web parameters. Dalfox provides advanced testing engines for reflected, stored, and DOM-based XSS, featuring WAF fingerprinting, AST-based vulnerability verification, and support for multiple output formats including JSON, Markdown, and SARIF. It includes a REST API and MCP server for integration into CI/CD pipelines and AI agent workflows.

Tokens
58.4K
Snippets
165
Records
392
Agent score
77%

What's inside dalfox

  1. Overview of Dalfox Agent Skill capabilities

    main

    The Dalfox SKILL.md provides instructions to AI agents on how to operate Dalfox correctly. It covers:

    • Triggers: Activated when a user scans for XSS in a URL, enumerates reflected parameters, or explicitly mentions "dalfox".
    • Authorization Gate: The skill prevents scanning until the user confirms they have permission to send payloads to the target.
    • Mode Detection: Prioritizes MCP (Model Context Protocol) tools if available, falling back to the dalfox CLI, or providing installation guidance if neither is found.
    • MCP Playbook: Follows a sequence: preflight_dalfox $\rightarrow$ scan_with_dalfox $\rightarrow$ polling get_results_dalfox (respecting suggested_poll_interval_ms) $\rightarrow$ delete_scan_dalfox upon completion.
    • CLI Scenarios: Supports POST bodies, authenticated sessions, Burp proxying, Blind/Stored XSS with callback URLs, pipe input, smoke tests, and machine-readable output.
    • Result Interpretation: Uses a three-axis model (type, detection_method, confidence) to prioritize findings. The type hierarchy is V (Exploitable) > A (AST Detection) > R (Reflected) > I (Informational).
    • Failure Modes: Handles reachable: false, scans that stall, and invalid_params responses.

  2. Overview of Dalfox XSS Scanner

    main

    Dalfox is an open-source XSS scanner and automation tool designed for parameter discovery, context analysis, payload injection, and vulnerability verification. It can process a single URL, a list of URLs, or crawled results passed via a pipe.

    Core Capabilities:

    • Parameter Discovery: Finds parameters in query strings, bodies, headers, cookies, and the DOM.
    • Context Analysis: Identifies where parameters are placed (e.g., HTML, JavaScript, attributes, or CSS).
    • Payload Injection: Injects context-aware payloads and utilizes WAF bypass encoders if necessary.
    • Vulnerability Verification: Uses an AST-based parser to verify vulnerabilities at the DOM level rather than relying on simple string matching.
    • Reporting: Supports multiple output formats including plain, JSON, JSONL, Markdown, SARIF, and TOML.

  3. Overview of Dalfox features

    main

    Dalfox is an automated XSS scanning and parameter analysis tool. Key capabilities include:

    • Subcommands: scan (supports URL, file, pipe, or raw-HTTP), server, payload, and mcp.
    • Discovery: Parameter analysis, static analysis, BAV testing, and parameter mining.
    • XSS Scanning: Reflected, Stored (SXSS), and DOM-based scanning with DOM/AST verification.
    • WAF Detection: Fingerprinting with confidence scoring and bypass tracking (tunable via --waf-min-confidence).
    • HTTP Customization: Support for custom headers, cookies, methods, and proxies.
    • Output Formats: JSON, JSONL, Plain, Markdown, SARIF, and TOML.
    • Extensibility: REST API, MCP stdio server, custom payloads, and remote wordlists.

  4. Understand the Dalfox Scanning Pipeline

    main

    Dalfox uses a multi-stage pipeline to identify and verify XSS vulnerabilities:

    1. Discovery: Extracts parameters from URLs, bodies, headers, cookies, paths, fragments, and form fields.
    2. Mining: Expands parameter discovery using DOM analysis (JS-embedded names), wordlists, and framework-specific patterns.
    3. Active Probing: Sends probes to each parameter to see which special characters survive.
    4. Fast Probe: Sends sandwich marker requests. If no partial or full reflection is detected, heavy payload loops for that parameter are skipped.
    5. Payload Generation: Creates context-aware payloads (HTML, JS, attributes, CSS).
    6. Reflection Check: Verifies if the payload is returned in the response.
    7. DOM Verification: Parses the response to see if the payload forms actual elements. AST-based DOM-XSS analysis runs in parallel using responses captured during the fast probe stage.

  5. Access Dalfox Reference Documentation

    main

    Dalfox provides comprehensive reference documentation for its CLI, configuration files, and environment variables. Use these resources to find specific technical details for integration and automation:

    • CLI Reference: Detailed documentation for all subcommands and flags.
    • Configuration File Reference: A complete list of all keys available in config.toml.
    • Environment Variables Reference: A list of all environment variables recognized by Dalfox.
    • XSSMaze Scoring: Information regarding how Dalfox detects XSSMaze labs.

  6. Understand Dalfox Detection Results (Type, Method, Severity)

    main

    Dalfox results are categorized into three independent axes to avoid misunderstanding the output:

    1. Confidence (type): Answers "Can this be called a vulnerability?" (e.g., V for Vulnerable, R for Reflected).
    2. Method (detection_method): Answers "How was it found?" (e.g., reflection, dom-verification, ast, oob).
    3. Impact (severity): Answers "How bad is it if exploited?" (e.g., High, Medium, Info).

    Note on Severity: In current XSS results, severity is largely a mapping of the type field (V → High, A → Medium, R → Info). It does not yet provide independent impact assessment beyond this mapping.

  7. Explore Dalfox scanning modes and core concepts

    main

    Dalfox supports multiple scanning modes to suit different testing requirements:

    • Single URL: Scan a specific target URL.
    • File batch: Scan multiple targets provided in a file.
    • Pipe: Use standard input to feed targets into Dalfox.
    • Stored-XSS: Specialized mode for detecting XSS that requires injection on one URL and verification on another.
    • Server: Run Dalfox in a server-based mode.
    • MCP: Model Context Protocol support.

    Other core areas of study include parameter discovery, payload encoding, WAF bypass techniques, and various output formats.

  8. Understand XSSMaze scoring for Dalfox

    main
    XSSMaze is a laboratory environment intentionally designed with vulnerabilities to measure the detection capabilities of XSS scanning tools. This documentation tracks how effectively Dalfox detects vulnerabilities within the XSSMaze main image (ghcr.io/hahwul/xssmaze:main). The scores presented in this section are automatically generated using the just xssmaze-score command and represent Dalfox's performance against this specific lab.

  9. Choose a Dalfox integration method

    main

    Dalfox can be integrated into various environments beyond the standard CLI. Depending on your use case, you can choose from the following integration methods:

    • REST API Server: A long-running HTTP service used to submit scans, poll status, and cancel tasks. Ideal for integration with Slack, dashboards, CI/CD pipelines, or custom tools.
    • MCP Server: A Model Context Protocol stdio server that exposes Dalfox as a tool for Claude, Cursor, and other MCP-compatible clients.
    • Agent Skill: A ready-to-use SKILL.md file that instructs skill-aware agents (like Claude Code, Cursor, OpenCode, or Codex) on how to run Dalfox safely.
    • Caido Workflow: Integration with Caido Active Workflows and Findings to perform real-time automated XSS testing within a proxy session.

  10. Understand the Dalfox Detection Model

    main

    Dalfox findings are defined by three independent axes. Understanding the distinction between these fields is critical for accurate triage:

    AxisFieldQuestion
    Confidencetype (V / R)Can Dalfox claim this is a vulnerability?
    Methoddetection_methodHow was it found?
    ImpactseverityHow bad is it if exploited?

    Note on severity: For XSS findings, severity currently restates the type tier (V → High, A → Medium, R → Info). It only provides independent information for I (Informational) findings, such as outdated libraries.

  11. Dalfox CLI Subcommands

    main

    Dalfox is organized into four primary subcommands. The scan subcommand is the default behavior when a target is provided without a specific command.

    SubcommandPurpose
    scanScan targets for XSS (default)
    serverRun a REST API server
    payloadList or fetch built-in/remote payloads
    mcpRun a Model Context Protocol stdio server
    helpPrint help for any subcommand
    dalfox [SUBCOMMAND] [TARGET] [FLAGS]

  12. Understand XSSMAZE Detection Score and Coverage

    main

    XSSMAZE provides a detection score that measures Dalfox's ability to detect XSS across various endpoints and categories. The score represents the percentage of catalogued endpoints successfully detected.

    Key metrics include:

    • Detection Score: The overall percentage of detected endpoints.
    • Endpoints: Total number of catalogued endpoints.
    • Categories: Total number of test groups.
    • Fully detected: Number of categories where 100% of endpoints were detected.
    • With gaps: Number of categories with detection rates below 100%.