Skip to main content

Want to Practice These Techniques?

Try Hackviser's interactive cyber security upskilling platform - Learn by doing!

Start Practicing Now

Dalfox

What is the purpose of Dalfox?​

Dalfox is an open-source command-line XSS scanner and automation utility. It is designed to find, verify, and report Cross-Site Scripting issues across URL parameters, request bodies, headers, discovered parameters, DOM-derived inputs, stored XSS flows, and large URL pipelines.

Dalfox is useful because it focuses deeply on XSS workflows instead of acting as a general web scanner. It supports single-target scans, file-based scans, stdin pipelines, raw HTTP request testing, stored XSS verification, payload generation, report generation, REST API server mode, and MCP server mode.

Use Dalfox only on applications you own or have explicit permission to test. XSS scanners send active payloads and can trigger application behavior, logs, alerts, state changes, and callback traffic.

Here are the primary uses of Dalfox:

  • Reflected XSS Testing: Dalfox injects payloads into parameters and analyzes responses to identify reflected and verified XSS behavior.

  • DOM-Based XSS Testing: The tool can mine DOM sources and run deeper browser-assisted checks for JavaScript-heavy applications.

  • Stored XSS Testing: Dalfox sxss mode sends a payload to one URL and verifies execution or reflection on a separate trigger URL.

  • Blind XSS Testing: The tool supports blind callback URLs so delayed or out-of-band payload execution can be detected.

  • Parameter Discovery: Dalfox can mine parameters from dictionaries, DOM analysis, remote wordlists, and explicit -p parameter lists.

  • Pipeline Scanning: The pipe and file modes make it practical to scan URL lists from crawlers, archives, proxies, and bug bounty recon tools.

  • Raw Request Testing: Dalfox can read raw HTTP request files exported from tools such as Burp Suite or ZAP and test the captured request structure.

  • Payload and Report Automation: The tool can generate payloads, use custom payload files, pull remote payload sources, produce JSON/JSONL output, and run as a service for automation.

Core Features​

  • Reflected, DOM, stored, and blind XSS testing
  • URL, file, pipe, raw request, and HAR input modes
  • Parameter mining from dictionaries, DOM, and remote wordlists
  • Custom, remote, and generated payload support
  • Headers, cookies, POST data, proxy, worker, and delay controls
  • JSON, JSONL, report, HAR, request, and response output options
  • REST API, MCP server, and CI automation support

Data sources​

  • Single URLs and URL lists
  • Raw HTTP requests and HAR files
  • Headers, cookies, query strings, and request bodies
  • DOM-discovered and dictionary-discovered parameters
  • Custom and remote XSS payload lists
  • Blind XSS callback endpoints
  • Dalfox JSON configuration files and API requests

Common Dalfox Commands​

1. Install Dalfox with Homebrew​

  • This command installs Dalfox on macOS or Linux systems with Homebrew.
brew install dalfox

2. Install Dalfox from Source​

  • This command installs the latest Dalfox v2 module with Go.
go install github.com/hahwul/dalfox/v2@latest

3. Pull the Docker Image​

  • This command pulls the official Dalfox image from GitHub Container Registry.
docker pull ghcr.io/hahwul/dalfox:latest

4. Check Dalfox Version​

  • This command prints the installed Dalfox version.
dalfox --version

5. Show Global Help​

  • This command displays Dalfox modes and global flags.
dalfox help

6. Show URL Mode Help​

  • This command displays help for single URL scanning.
dalfox url --help

7. Scan a Single URL​

  • This command scans a single target URL for XSS.
dalfox url "https://example.com/search?q=test"

8. Scan a URL Without Existing Parameters​

  • This command lets Dalfox perform parameter discovery before XSS testing.
dalfox url "https://example.com/search"

9. Scan Only Specific Parameters​

  • This command tests only selected parameters.
dalfox url "https://example.com/search?q=test&page=1" -p q -p page

10. Ignore Noisy Parameters​

  • This command skips parameters that should not be tested.
dalfox url "https://example.com/form?csrf_token=abc&q=test" --ignore-param csrf_token

11. Ignore Specific HTTP Return Codes​

  • This command ignores selected status codes during scanning.
dalfox url "https://example.com/search?q=test" --ignore-return "403,404,500"

12. Add a Custom Header​

  • This command adds an HTTP header to each request.
dalfox url "https://example.com/search?q=test" -H "Authorization: Bearer <token>"

13. Add Cookies​

  • This command sends cookies with the scan requests.
dalfox url "https://example.com/account?q=test" -C "sessionid=abc123; role=user"

14. Load Cookies from a Raw Request​

  • This command loads cookies from a captured raw HTTP request file.
dalfox url "https://example.com/account?q=test" --cookie-from-raw request.txt

15. Use a Custom User-Agent​

  • This command sets the User-Agent header.
dalfox url "https://example.com/search?q=test" --user-agent "Mozilla/5.0 Dalfox-Test"

16. Send a POST Request​

  • This command tests a form-style POST body.
dalfox url "https://example.com/search" -X POST -d "q=test&category=docs"

17. Send a JSON Request Body​

  • This command tests a JSON API request body.
dalfox url "https://example.com/api/search" -X POST -H "Content-Type: application/json" -d '{"q":"test"}'

18. Follow Redirects​

  • This command follows HTTP redirects during scanning.
dalfox url "https://example.com/redirect?q=test" -F

19. Send Traffic Through a Proxy​

  • This command routes Dalfox requests through a local proxy for inspection.
dalfox url "https://example.com/search?q=test" --proxy "http://127.0.0.1:8080"

20. Set Timeout​

  • This command sets request timeout in seconds.
dalfox url "https://example.com/search?q=test" --timeout 20

21. Tune Worker Count​

  • This command controls concurrent workers.
dalfox url "https://example.com/search?q=test" -w 50

22. Add Request Delay​

  • This command adds delay between requests in milliseconds.
dalfox url "https://example.com/search?q=test" --delay 500

23. Limit CPU Usage​

  • This command limits the maximum number of CPUs Dalfox uses.
dalfox url "https://example.com/search?q=test" --max-cpu 1

24. Enable WAF Evasion Mode​

  • This command enables adaptive WAF evasion behavior.
dalfox url "https://example.com/search?q=test" --waf-evasion

25. Use Blind XSS Callback​

  • This command adds a blind XSS callback endpoint.
dalfox url "https://example.com/search?q=test" -b "https://callback.example/xss"

26. Run Parameter Discovery Only​

  • This command discovers possible injection points without running full XSS scanning.
dalfox url "https://example.com" --only-discovery

27. Skip Discovery and Test Known Parameters​

  • This command skips discovery and tests only the provided parameter.
dalfox url "https://example.com/search?q=test" --skip-discovery -p q

28. Disable DOM Parameter Mining​

  • This command skips DOM-based parameter mining.
dalfox url "https://example.com/search" --skip-mining-dom

29. Disable Dictionary Parameter Mining​

  • This command skips dictionary-based parameter mining.
dalfox url "https://example.com/search" --skip-mining-dict

30. Disable All Parameter Mining​

  • This command tests only parameters already present or explicitly provided.
dalfox url "https://example.com/search?q=test" --skip-mining-all

31. Use a Custom Parameter Wordlist​

  • This command uses a local parameter wordlist for dictionary mining.
dalfox url "https://example.com" -W params.txt

32. Use Remote Parameter Wordlists​

  • This command pulls remote wordlists for parameter discovery.
dalfox url "https://example.com" --remote-wordlists "burp,assetnote"

33. Enable Deep DOM XSS Testing​

  • This command uses deeper DOM XSS testing with more payload coverage.
dalfox url "https://example.com/search?q=test" --deep-domxss

34. Force Headless Verification​

  • This command forces browser-based verification for findings.
dalfox url "https://example.com/search?q=test" --force-headless-verification

35. Skip Headless Checks​

  • This command skips headless browser-based scanning.
dalfox url "https://example.com/search?q=test" --skip-headless

36. Skip BAV Checks​

  • This command skips Basic Another Vulnerability checks and focuses on XSS workflow.
dalfox url "https://example.com/search?q=test" --skip-bav

37. Skip Built-In Grepping​

  • This command disables built-in grepping checks.
dalfox url "https://example.com/search?q=test" --skip-grepping

38. Skip XSS Scanning​

  • This command runs discovery and analysis without XSS payload scanning.
dalfox url "https://example.com/search?q=test" --skip-xss-scanning

39. Use a Custom Payload File​

  • This command adds custom XSS payloads from a local file.
dalfox url "https://example.com/search?q=test" --custom-payload payloads.txt

40. Use Only Custom Payloads​

  • This command tests only payloads from the custom payload file.
dalfox url "https://example.com/search?q=test" --custom-payload payloads.txt --only-custom-payload

41. Use Remote Payload Sources​

  • This command adds remote XSS payload sources to the scan.
dalfox url "https://example.com/search?q=test" --remote-payloads "portswigger,payloadbox"

42. Change the Alert Value​

  • This command changes the alert value used in payload verification.
dalfox url "https://example.com/search?q=test" --custom-alert-value "document.domain"

43. Change the Alert Type​

  • This command wraps the custom alert value as a string.
dalfox url "https://example.com/search?q=test" --custom-alert-value "Dalfox" --custom-alert-type str

44. Scan Multiple URLs from a File​

  • This command scans URLs listed in a text file.
dalfox file urls.txt

45. Scan a Raw HTTP Request File​

  • This command tests a captured Burp Suite or ZAP raw request.
dalfox file request.raw --rawdata

46. Force HTTP Raw Data Mode​

  • This command forces HTTP handling when using raw request data.
dalfox file request.raw --rawdata --http

47. Scan a HAR File​

  • This command reads a HAR file as input for file mode.
dalfox file traffic.har --har

48. Scan URLs from Standard Input​

  • This command reads target URLs from stdin.
cat urls.txt | dalfox pipe

49. Pipe Recon Output into Dalfox​

  • This command scans URLs produced by other recon tools when they are installed.
waybackurls example.com | gf xss | dalfox pipe

50. Use Mass Mode for File Scans​

  • This command enables parallel N-host scanning for a URL file.
dalfox file urls.txt --mass --mass-worker 20

51. Limit File Mode Results​

  • This command limits the number of results displayed from a file scan.
dalfox file urls.txt --limit 50

52. Run Pipe Mode with Silence Force​

  • This command prints only PoC output in pipeline scans.
cat urls.txt | dalfox pipe --silence-force

53. Save Plain Output​

  • This command writes scan output to a text file.
dalfox url "https://example.com/search?q=test" -o dalfox-results.txt

54. Save JSON Output​

  • This command writes machine-readable JSON output.
dalfox url "https://example.com/search?q=test" --format json -o dalfox-results.json

55. Save JSONL Output​

  • This command writes newline-delimited JSON output.
dalfox file urls.txt --format jsonl -o dalfox-results.jsonl

56. Generate a Detailed JSON Report​

  • This command writes a detailed report in JSON format.
dalfox url "https://example.com/search?q=test" --report --report-format json -o dalfox-report.json

57. Show Only Verified and Grep-Based PoCs​

  • This command filters output to selected PoC types.
dalfox url "https://example.com/search?q=test" --only-poc "g,v"

58. Output PoC as curl​

  • This command formats PoCs as curl commands.
dalfox url "https://example.com/search?q=test" --poc-type curl

59. Output PoC as HTTP Request​

  • This command formats PoCs as raw HTTP requests.
dalfox url "https://example.com/search?q=test" --poc-type http-request

60. Include Raw HTTP Requests in Output​

  • This command includes raw requests in scan output.
dalfox url "https://example.com/search?q=test" --output-request

61. Include Raw HTTP Responses in Output​

  • This command includes raw responses in scan output.
dalfox url "https://example.com/search?q=test" --output-response

62. Include All Logs in Output​

  • This command enables full log write mode.
dalfox url "https://example.com/search?q=test" --output-all -o full-dalfox.log

63. Write a HAR File​

  • This command writes scan traffic to a HAR file for later analysis.
dalfox url "https://example.com/search?q=test" --har-file-path scan.har

64. Run a Stored XSS Test​

  • This command submits a payload to one URL and verifies it from another URL.
dalfox sxss "https://example.com/profile/update" -X POST -d "nickname=test" --trigger "https://example.com/profile"

65. Run Stored XSS with a Separate Trigger Method​

  • This command uses POST for injection and GET for verification.
dalfox sxss "https://example.com/profile/update" -X POST -d "nickname=test" --trigger "https://example.com/profile" --request-method GET

66. Start Dalfox REST API Server​

  • This command starts the default REST API server.
dalfox server --host 127.0.0.1 --port 8090

67. Start Server with an API Key​

  • This command protects REST API calls with an API key.
dalfox server --host 127.0.0.1 --port 8090 --api-key "change-me"

68. Start Server with CORS Restrictions​

  • This command restricts allowed origins for the REST API server.
dalfox server --host 127.0.0.1 --port 8090 --allowed-origins "https://security.example.com"

69. Start MCP Server Mode​

  • This command starts Dalfox as an MCP server.
dalfox server --type mcp

70. Submit a REST API Scan​

  • This command submits a scan to a running Dalfox REST API server.
curl -X POST "http://127.0.0.1:8090/scan" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: change-me" \
  -d '{"url":"https://example.com/search?q=test","options":{"format":"json","worker":20}}'

71. Generate Common XSS Payloads​

  • This command prints common XSS payloads.
dalfox payload --enum-common

72. Generate In-HTML Payloads​

  • This command enumerates payloads for HTML context testing.
dalfox payload --enum-html

73. Generate In-JavaScript Payloads​

  • This command enumerates payloads for JavaScript context testing.
dalfox payload --enum-injs

74. Generate Attribute Context Payloads​

  • This command enumerates payloads for HTML attribute contexts.
dalfox payload --enum-attr

75. Enumerate Event Handlers​

  • This command prints event handler entities useful for XSS payload construction.
dalfox payload --entity-event-handler

76. Generate Bulk Stored XSS Payloads​

  • This command generates many sequence-based payloads for stored XSS testing.
dalfox payload --make-bulk

77. URL Encode Generated Payloads​

  • This command URL-encodes generated payload output.
dalfox payload --enum-common --encoder-url

78. Use PortSwigger Payloads in Payload Mode​

  • This command enumerates payloads from PortSwigger's XSS cheat sheet source.
dalfox payload --remote-portswigger

79. Use Payloadbox Payloads in Payload Mode​

  • This command enumerates payloads from Payloadbox's XSS payload source.
dalfox payload --remote-payloadbox

80. Use a Configuration File​

  • This command loads reusable scan settings from a JSON config file.
dalfox url "https://example.com/search?q=test" --config config.json

81. Override Configuration Values​

  • This command overrides selected config values from the command line.
dalfox url "https://example.com/search?q=test" --config config.json --worker 25 --timeout 15

82. Run Dalfox with Docker​

  • This command scans a URL from the official container image.
docker run --rm ghcr.io/hahwul/dalfox:latest /app/dalfox url "https://example.com/search?q=test"

83. Run File Mode with Docker​

  • This command mounts the current directory and scans a local URL list from the container.
docker run --rm -v "$(pwd)":/data ghcr.io/hahwul/dalfox:latest /app/dalfox file /data/urls.txt

84. Run a Finding Action​

  • This command appends PoC URLs to a local file when Dalfox finds a result.
dalfox url "https://example.com/search?q=test" --found-action "printf '%s\n' '@@query@@' >> dalfox-findings.txt"

Output Examples of Dalfox Commands​

CommandExample UsageFunctionOutput Example
Single URLdalfox url "https://example.com/search?q=test"Scans one URL.[*] Target URL: https://example.com/search?q=test
[I] Found reflected parameter: q
Verified XSSdalfox url "https://example.com/search?q=test"Shows confirmed XSS findings.[V] Triggered XSS Payload: q=&lt;svg/onload=alert(1)&gt;
[POC][V][GET] https://example.com/search?q=...
Parameter Discoverydalfox url https://example.com --only-discoveryDiscovers testable parameters.[I] Found testing point by dictionary mining: q
[I] Found testing point in DOM: callback
File Modedalfox file urls.txtScans many URLs from a file.[*] Loaded targets from urls.txt
[POC][R][GET] https://example.com/?q=...
Pipe Modecat urls.txt | dalfox pipeReads URLs from stdin.[*] Using pipeline mode
[I] Valid target [code:200]
Raw Requestdalfox file request.raw --rawdataTests captured HTTP request data.[*] Raw request mode
[I] Found parameter in body: search
JSON Outputdalfox url ... --format json -o results.jsonWrites structured output.{"type":"v","poc":"https://example.com/search?q=..."}
Reportdalfox url ... --report --report-format jsonGenerates detailed report data."target":"https://example.com/search?q=test"
"poc_type":"verified"
Stored XSSdalfox sxss ... --trigger ...Sends and verifies stored payloads.[*] Send payload to store URL
[V] Stored XSS payload triggered
Server Modedalfox server --port 8090Starts API service.Target REST API Mode
Listen Address 127.0.0.1:8090

Practical Tips​

  • Start with --only-discovery or --skip-xss-scanning when testing large or fragile applications.
  • Use -p and --skip-discovery for focused validation of known parameters.
  • Use --proxy during manual review so you can inspect generated requests in a proxy.
  • Use --delay, --timeout, and lower -w values when scanning rate-sensitive applications.
  • Use --format json, --format jsonl, and --report when integrating Dalfox into CI or recon pipelines.
  • Use --remote-payloads and --deep-domxss for deeper testing, but expect slower scans.
  • Treat --found-action as code execution on your own machine. Keep it simple, reviewed, and non-destructive.
  • Validate important findings manually before reporting them, especially reflected or grep-based findings.