Where the file lives

Dalfox looks in this order:

1. $XDG_CONFIG_HOME/dalfox/config.toml
2. $HOME/.config/dalfox/config.toml

You can point anywhere else with --config:

dalfox --config ./dalfox.toml scan https://target.app

If no file exists, Dalfox creates a template at the default path the first time you run it.

A minimal config

[scan]
format = "json"
output = "results.json"
timeout = 15
workers = 100
encoders = ["url", "html"]

Run a scan and those flags apply automatically:

dalfox https://target.app?q=test
# → writes JSON results to results.json with workers=100

Precedence

CLI flag  >  Config file  >  Built-in defaults

Anything on the command line wins. This lets you keep sensible defaults in the config, then override per-scan:

# Config sets workers=100, but for this quick scan use 20
dalfox --workers 20 https://target.app

Formats

Dalfox supports both TOML and JSON. TOML is the default; JSON is handy if you generate the file from a tool or UI.

# ~/.config/dalfox/config.toml
[scan]
format = "sarif"
silence = true

{
  "scan": {
    "format": "sarif",
    "silence": true
  }
}

What can I configure?

Anything that has a CLI flag under dalfox scan can live in the [scan] table. Common examples:

See the Config File reference for every key.

Secrets

Keep API keys, bearer tokens, and blind-XSS callback hostnames out of the config file if you commit it. Prefer environment variables:

# .env or your shell profile
export DALFOX_API_KEY="..."

Or pass them at the command line and never persist them.

Next steps

• Run your first scan
• Explore scanning modes
• See the full CLI reference

Homebrew (macOS & Linux)

brew install dalfox

The Homebrew formula tracks the latest stable release. Source: formulae.brew.sh/formula/dalfox.

Snap (Ubuntu / Linux)

sudo snap install dalfox

Arch Linux (AUR)

Using an AUR helper (recommended):

yay -S dalfox
# or
paru -S dalfox

Manual build from the AUR package:

git clone https://aur.archlinux.org/dalfox.git
cd dalfox
makepkg -si

Nix & NixOS

# Run once without installing
nix-shell -p dalfox

# Nix flakes: run the latest from GitHub
nix run github:hahwul/dalfox -- scan https://example.com

# Install into your profile
nix profile install github:hahwul/dalfox

# Drop into a dev shell with Dalfox available
nix develop github:hahwul/dalfox

Dalfox lives in nixpkgs. The newest releases land in unstable first.

Cargo (from crates.io)

cargo install dalfox

Requires a recent Rust toolchain (stable is fine). Builds into ~/.cargo/bin/dalfox.

Prebuilt binaries

Grab a release archive for your OS/arch from github.com/hahwul/dalfox/releases, extract it, and drop the binary somewhere on your PATH (/usr/local/bin, ~/.local/bin, etc.).

We publish the following Linux variants per release:

• linux-x86_64 (glibc)
• linux-x86_64-musl (statically linked, recommended for Alpine, Docker, and CI)
• linux-aarch64 (glibc)
• linux-aarch64-musl (statically linked)

Build from source

git clone https://github.com/hahwul/dalfox
cd dalfox
cargo build --release
# Binary at ./target/release/dalfox

You'll need Rust (2024 edition). Install with rustup if you don't have it.

Verify

dalfox --version

You should see something like dalfox 3.0.0 along with the Dalfox banner.

Update shell completions (optional)

Dalfox uses clap, so help is always accessible:

dalfox --help
dalfox scan --help

Next steps

Run your first scan in the Quick Start. If you want to tune defaults before scanning, jump to Configuration.

1. Scan a single URL

dalfox https://xss-game.appspot.com/level1/frame?query=test

The first argument is the target. Dalfox auto-detects that it's a URL and runs the scan subcommand implicitly. You'll see:

• A banner with the version.
• INFO lines as Dalfox discovers parameters and probes contexts.
• [V] (verified) and [R] (reflected) lines for each finding, with the exact payload that worked.

2. Scan from a file

Feed a list of URLs from your crawler:

# urls.txt, one target per line
dalfox scan urls.txt

Each URL runs through the same pipeline. Results stream as they're found.

3. Scan from a pipeline

Dalfox reads from stdin when you pipe:

cat urls.txt | dalfox
# or combined with your recon tools:
waybackurls example.com | gf xss | dalfox

4. Get JSON output

Pair Dalfox with jq, a dashboard, or CI:

dalfox https://target.app/search?q=test -f json -o report.json

Machine-readable formats (json, jsonl, sarif, toml) auto-suppress the banner so the file stays clean.

5. Authenticated scans

Pass cookies, headers, or a custom method:

dalfox https://api.target.app/v1/users \
  -X POST \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"test"}' \
  --cookies "session=abc123"

Or point Dalfox at a raw HTTP request file you captured from your proxy:

dalfox scan --input-type raw-http request.txt

6. Catch Blind XSS

Use an out-of-band callback (Interactsh, Burp Collaborator, XSS Hunter, etc.):

dalfox https://target.app \
  -b https://your-callback.interact.sh

Dalfox sends blind-XSS payloads across every discovered parameter; if the payload fires later in an admin panel, your callback server records it.

7. Dry-run first

Use --dry-run to preview what Dalfox would scan:

dalfox https://target.app --dry-run

It discovers parameters and estimates request volume without firing any payloads.

Reading the output

Each finding is tagged:

V and A findings are actionable. R findings are worth a look but may be filtered further downstream.

Next steps

• Learn the different scanning modes.
• Understand how parameters are discovered.
• Tune payloads and encoders for harder targets.
• Save your favorite flags in a config file.

Choosing a format

dalfox https://target.app -f json -o report.json

Writing to a file

dalfox https://target.app -f jsonl -o findings.jsonl

Without -o, output goes to stdout.

Result fields

Every finding includes:

Optionally include the full request/response:

dalfox https://target.app -f json --include-all -o report.json
# or granularly:
dalfox ... --include-request
dalfox ... --include-response

Silence mode

Emit only findings on stdout, no logs:

dalfox https://target.app --silence
# Pipe findings into another tool:
cat urls.txt | dalfox --silence -f jsonl | jq 'select(.severity=="High")'

Useful in shell pipelines and cron jobs.

Streaming findings during long scans

By default the plain renderer prints each finding block (POC + Issue / Payload / Line) after the end-of-scan WRN XSS found N XSS summary, so the log reads in natural order: start → progress → summary → details.

For long scans against large targets, you can flip to mid-scan emission with --stream-findings. Each finding is printed the moment it is verified, above the progress bars:

dalfox https://target.app --stream-findings

--stream-findings only affects the plain format and is auto-disabled when the end-of-scan path needs to apply filters the streamer can't mirror cleanly (--output, --limit, --only-poc).

POC styles

Re-render the proof-of-concept in different client shapes:

dalfox https://target.app --poc-type curl      # curl command
dalfox https://target.app --poc-type httpie    # HTTPie
dalfox https://target.app --poc-type http-request  # raw HTTP

Default is plain. Good for filing tickets.

Filtering

Show only certain result types:

dalfox https://target.app --only-poc v     # only verified
dalfox https://target.app --only-poc v,a   # verified + AST

Cap the number of results:

dalfox https://target.app --limit 50
dalfox https://target.app --limit 10 --limit-result-type v

Colour & TTY behaviour

dalfox https://target.app --no-color
# or
NO_COLOR=1 dalfox https://target.app

Dalfox also auto-disables colour when output is redirected to a file or a non-TTY.

TOML

Same data shape as JSON, written as TOML, which is easier to skim by eye while still parsing cleanly. Findings render as a [[results]] array of tables:

[[results]]
type = "V"
type_description = "Verified"
inject_type = "inHTML"
method = "GET"
data = "https://target.app/search?q=%3Csvg%2Fonload%3Dalert%281%29%3E"
param = "q"
payload = "<svg/onload=alert(1)>"
evidence = "payload reflected and DOM element verified"
location = "Query"
cwe = "CWE-79"
severity = "High"
message_id = 606
message_str = "XSS found"

dalfox https://target.app -f toml -o report.toml

SARIF → GitHub code scanning

dalfox scan urls.txt -f sarif -o dalfox.sarif

Upload dalfox.sarif through GitHub's upload-sarif action, and findings appear in the repository's Security → Code scanning tab.

CI example

# .github/workflows/xss-scan.yml
- name: Dalfox scan
  run: dalfox scan scope.txt -f sarif -o dalfox.sarif --silence --waf-evasion

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: dalfox.sarif

Exit codes

Dalfox returns:

Use 1 as a CI gate only if you're comfortable failing the build on any finding. Most teams gate on severity >= High using jq on JSON output.

Next

• Automate scans via the REST API Server.
• Let an AI driver handle it with the MCP Server.

The pipeline, briefly

1. Discovery: Extract parameters from the URL, body, headers, cookies, path, fragment, and form fields.
2. Mining: Extend with DOM analysis (parameter names embedded in JS), dictionary wordlists, and framework-specific patterns.
3. Active probing: Fire a probe for each parameter to learn which special characters survive.
4. Fast probe: A single sandwich-marker request per discovered parameter. If neither a partial nor a full reflection shows up, the heavy payload loops are skipped for that parameter.
5. Payload generation: Build context-aware payloads (HTML, JS, attribute, CSS).
6. Reflection check: Send the payload, then see whether it comes back.
7. DOM verification: Parse the response and confirm the payload forms a real element. AST-based DOM-XSS analysis runs in parallel using the response captured during the fast probe.

Targeting specific parameters

Tell Dalfox exactly which parameters to test:

dalfox https://target.app/api \
  -p q \
  -p id:query \
  -p auth:header \
  -p token:cookie

Locations: query, body, json, cookie, header. Without a hint, Dalfox places the parameter wherever the target already exposes it.

Mining with wordlists

Even if a parameter isn't in the URL, Dalfox can try common names:

# Local wordlist
dalfox https://target.app -W ./params.txt

# Remote wordlists (cached after first fetch)
dalfox https://target.app --remote-wordlists burp,assetnote

Auto-collapse

Highly reflective sites (e.g., a search page that echoes everything) can cause wordlist mining to explode. Dalfox protects against this two ways:

• Sentinel pre-probe: Before iterating the wordlist, three random parameter names that should never collide with real fields are tested. If every one reflects, the page is a mirror; mining is skipped and a single synthetic any Query parameter takes its place. Cost ceiling: 3 requests, regardless of wordlist size. Runs only when the wordlist is large enough (>15 entries) for the pre-probe to pay off.
• EWMA collapse: While iterating, Dalfox watches the rolling reflection ratio. Once it stays ≥85% after at least 15 attempts, mining stops and any Query params already collected are folded into the same any placeholder.

Both routes produce identical downstream state: Stage 5–7 sees one Query injection point regardless of which trigger fired.

Pruning the noise

Ignore specific parameters:

dalfox https://target.app --ignore-param csrf --ignore-param __RequestVerificationToken

Scope by URL pattern:

dalfox scan urls.txt \
  --include-url '^https://api\.target\.app/' \
  --exclude-url '/static/|/health'

Out-of-scope domain list:

dalfox scan urls.txt --out-of-scope-file scope-block.txt
# or inline, with wildcards
dalfox scan urls.txt --out-of-scope '*.google.com,*.cdn.cloudflare.net'

Only discover, don't attack

Dry-run mode discovers and prints the attack plan without sending payloads:

dalfox https://target.app --dry-run

Discovery-only mode is similar but completes the probing stage:

dalfox https://target.app --only-discovery

Both help with scoping and CI pre-checks.

Skipping stages

To move faster or work around a fragile target, skip parts of the pipeline:

Injection markers

Some endpoints need the payload in a specific location (e.g., inside a JWT). Use --inject-marker:

dalfox https://target.app/api \
  --inject-marker FUZZ \
  -d '{"filter":"FUZZ"}'

Dalfox replaces every FUZZ with each payload and sends the request.

Auto pre-encoding

Some endpoints don't accept a payload as raw text. They expect it wrapped in some structural encoding (base64, JSON, JWT, and so on). Dalfox inspects each parameter's existing value during discovery and, when it recognises a structure, builds a transparent encoding pipeline so payloads round-trip through the same wrapping. There's nothing to configure: look for pre_encoding or pre_encoding_pipeline in debug output.

Single-step encodings are detected on the existing parameter value:

Composable pipelines turn the value's structure into a chain of transformations. When the existing value decodes as a structured wrapper, Dalfox enumerates every leaf string field as its own virtual sub-parameter:

Each leaf is registered as a separate Param using bracket-style display naming. A payload at the move_url field of qs shows up as qs[move_url], and an array element appears as qs[items][0]. The wire-level substitution still targets the original parent param (qs), so the request looks normal to the server.

For JWTs the original header and signature segments are preserved verbatim. The signature won't match the modified payload, so this only fires on endpoints that don't verify the token. Properly-signed JWTs return no findings. That's expected behaviour, not a miss.

If your target uses a wrapping that Dalfox doesn't auto-detect, you can still force the injection point with --inject-marker (see below).

Reflection probe shape

Every discovery and mining probe sends a sandwich marker (OPEN + INNER + CLOSE) instead of a single token. The response is then classified into one of four cases:

All four are treated as "reflected": discovery records the parameter and the scan proceeds. A naive single-token check would have missed every case except Full, leaving prefix-/suffix-stripping endpoints undetected. The marker tokens are scan-unique (dlx/dlxmid/xld prefixes plus 8 hex chars per scan), so accidental collisions in HTML are negligible.

What makes a finding "verified"

V and A are the signals. R is a hint.

Safe contexts

Dalfox ignores reflections inside <textarea>, <title>, <noscript>, <style>, <xmp>, and <plaintext>. Content there doesn't execute, so it would only produce false positives.

Next

• See how payloads are built in Payloads & Encoding.
• Dealing with a WAF? Jump to WAF Bypass.

Payload families

Dalfox composes payloads from several families:

Each payload template carries a marker (class={CLASS} or id={ID}) so the verification stage can positively identify its own element in the DOM.

Context-aware selection

During discovery Dalfox classifies each parameter by injection context, the place where its reflected value lands:

• HTML body → HTML/attribute-breakout payloads
• Inside a quoted attribute → attribute-breakout payloads
• Inside <script> → JS-breakout payloads
• Inside <style> → CSS payloads
• Unknown → fallback mix of HTML + attribute

This keeps request counts sane while maximising hit rate.

Encoders

Encoders transform the same payload into multiple forms so the WAF and server-side filters don't all see the same bytes.

dalfox https://target.app -e url,html,base64

Available encoders:

Defaults: url,html. If you add none to the list, Dalfox sends only the raw payloads.

Custom payloads

Provide your own list, one payload per line:

dalfox https://target.app --custom-payload mypayloads.txt

Swap out the built-in library entirely:

dalfox https://target.app --custom-payload mypayloads.txt --only-custom-payload

Remote payload sources

Pull community wordlists on demand:

dalfox https://target.app --remote-payloads portswigger,payloadbox

Supported sources: portswigger, payloadbox. Fetched once per run, respecting --proxy and --timeout.

Inspecting payloads

Print a payload family without running a scan:

dalfox payload event-handlers  # onerror, onmouseover, ...
dalfox payload useful-tags     # svg, img, script, ...
dalfox payload uri-scheme      # javascript:, data:, vbscript:
dalfox payload portswigger     # fetch + print remote list

Customising the "alert"

The classic alert(1) can be loud. Swap it out so you can prove impact without popping dialogs everywhere:

dalfox https://target.app \
  --custom-alert-value "document.domain" \
  --custom-alert-type str

• --custom-alert-value: value passed to alert/prompt/confirm (default 1).
• --custom-alert-type: none keeps the original function, str wraps the value in quotes.

Blind XSS

Blind XSS fires later, in a context you can't see (an admin panel, a support agent's dashboard). You need an out-of-band listener:

dalfox https://target.app -b https://your-callback.interact.sh

Custom blind templates:

dalfox https://target.app \
  -b https://your-callback.example \
  --custom-blind-xss-payload blind-templates.txt
# each line may contain {} (replaced with the callback URL)

HTTP Parameter Pollution (HPP)

Some filters only inspect the first occurrence of a parameter. Dalfox can duplicate parameters to slip a payload into the second slot:

dalfox https://target.app --hpp

Deep scan

By default Dalfox stops testing a parameter once it finds a verified payload. --deep-scan keeps going:

dalfox https://target.app --deep-scan

Useful for research; slower for production pipelines.

Skipping payload stages

Next

• Pair this with WAF Bypass to bend payloads around filters.
• See Output & Reports to export findings.

Under the hood there are four subcommands: scan (the scanner), server (long-lived REST API), payload (payload utilities), and mcp (Model Context Protocol stdio server). Everything below labelled "URL / File / Pipe / Raw HTTP / SXSS" is a shape of input that the scan subcommand handles via --input-type; they are not independent subcommands.

Auto (default)

Just give Dalfox a URL. It figures out the rest.

dalfox https://target.app/search?q=test

Under the hood, Dalfox uses the scan subcommand with --input-type auto. It auto-detects whether the argument is a URL, a file path, or a stream on stdin.

URL mode

Force URL parsing (rarely needed, useful in scripts):

dalfox scan --input-type url https://target.app

File mode

Scan a list of URLs, one per line:

# urls.txt
# https://target.app/search?q=1
# https://target.app/profile?id=2
dalfox scan urls.txt
# or, explicit:
dalfox scan --input-type file urls.txt

Comments (#) and blank lines are ignored. Each URL runs through the full pipeline.

Pipe mode

Read from stdin, the common case when chaining recon tools:

cat urls.txt | dalfox scan
waybackurls example.com | gf xss | dalfox scan
hakrawler -url https://target.app | dalfox scan

Dalfox buffers the input, deduplicates, and scans every line as a target.

Raw HTTP mode

Save a request you captured in Burp, Caido, or ZAP to a file and hand it to Dalfox:

dalfox scan --input-type raw-http request.txt

The file is a standard raw HTTP request (method + path + headers + blank line + body). Dalfox preserves every header, cookie, and body parameter.

For live proxy workflows (especially Caido Active Workflows) see the dedicated Caido integration guide. It covers the exact shell pattern, the Caido boolean gotcha in If/Else nodes, and how to turn results into Findings automatically.

Stored XSS mode (SXSS)

Test the classic "inject on form A, payload appears on page B" pattern:

dalfox scan https://target.app/post-comment \
  --sxss \
  --sxss-url https://target.app/comments

Dalfox injects into the first URL, then fetches the second to check whether the payload landed. See the Stored XSS guide for the full flow.

Server mode

Run Dalfox as a long-lived HTTP service. Submit scans via REST, poll for results, cancel running jobs:

dalfox server --port 6664 --api-key "$DALFOX_API_KEY"

See REST API Server for endpoints and request shapes.

MCP mode

Expose Dalfox as a Model Context Protocol server so AI agents and IDEs (like Claude) can drive scans:

dalfox mcp

The tools (scan_with_dalfox, get_results_dalfox, list_scans_dalfox, cancel_scan_dalfox, delete_scan_dalfox, preflight_dalfox) are described in MCP Server.

Payload mode (utility)

Not a scanning mode, but useful alongside: print or fetch payloads without running a scan.

dalfox payload event-handlers    # list DOM event handlers
dalfox payload useful-tags       # list useful HTML tags
dalfox payload portswigger       # fetch PortSwigger XSS cheatsheet
dalfox payload payloadbox        # fetch PayloadBox XSS list
dalfox payload uri-scheme        # print javascript:/data: payloads

Choosing a mode

The basic flow

dalfox https://target.app/post-comment \
  --sxss \
  --sxss-url https://target.app/comments

Dalfox will:

1. Inject each payload into the first URL (post-comment).
2. Retrieve the second URL (comments) with a GET (configurable via --sxss-method).
3. Verify whether the payload reflects in the retrieval response, and whether it produced a real DOM element.

Only findings that survive both steps are reported as SXSS.

Choosing the retrieval URL

Pick the page the stored value reads from. Examples:

If you omit --sxss-url, Dalfox tries to auto-detect it from the response headers (e.g., a Location redirect after a POST).

Retrieval method

dalfox https://target.app/form --sxss \
  --sxss-url https://target.app/list \
  --sxss-method GET

GET is the default. Use POST or others if the retrieval endpoint needs it.

Authentication

Stored-XSS often requires two sessions: one that writes (user), and one that reads (admin). Use headers/cookies that grant enough access for the retrieval GET to see what you wrote.

dalfox https://target.app/profile \
  --sxss --sxss-url https://target.app/admin/users \
  -H "Cookie: admin_session=abc; role=admin"

Blind + stored

If the retrieval page is behind a login you don't have, switch to blind XSS. The payload fires on the admin's browser, and your callback server records it:

dalfox https://target.app/support/ticket \
  -b https://callback.interact.sh

You still need to wait for someone to view the page; the callback tells you when it happens.

Tips

• Scope narrowly. Use -p to name the field(s) you know are rendered on the retrieval URL. That way Dalfox isn't testing every cookie.
• Watch for sanitisation-then-render. Stored XSS often survives a HTML sanitizer on write but breaks on a second sanitization on read. Dalfox's mXSS payloads are tuned for this.
• Slow down. Some apps debounce or batch writes. A small --delay helps the retrieval see your payload.

Next

• Payloads & Encoding for tuning the injected payloads.
• Output & Reports for shipping findings.

How it works

1. Dalfox sends a small set of fingerprint probes to the target.
2. If a known WAF signature shows up (headers like cf-ray, body markers like "Attention required!", or a 429/403 shape), Dalfox notes the WAF and its confidence.
3. The scanner merges the WAF's extra encoders into your encoder list and adds the WAF's mutation list to the payload generator.
4. Payload mutations are capped (3 variants per base payload) so request volume stays sane.

This is all on by default. You only touch flags if you want to disable or steer it.

Supported WAFs

• Cloudflare
• AWS WAF
• Akamai
• Imperva / Incapsula
• ModSecurity
• OWASP CRS
• Sucuri
• F5 BIG-IP
• Barracuda
• FortiWeb
• Azure WAF
• Google Cloud Armor
• Fastly
• Wordfence

Unrecognised WAFs trigger a generic fallback strategy.

Tuning the behaviour

Auto (default)

dalfox https://target.app
# equivalent to:
dalfox https://target.app --waf-bypass auto

Force a specific WAF

Skip fingerprinting and apply a chosen WAF's strategy directly:

dalfox https://target.app \
  --waf-bypass force \
  --force-waf cloudflare

Handy when the WAF masks its headers or sits behind a CDN.

Disable WAF logic

dalfox https://target.app --waf-bypass off

No extra encoders, no mutations: just your configured payloads.

Skip the probe

dalfox https://target.app --skip-waf-probe

Still uses header-based passive detection, but no provocation requests. Use when the target is flaky and you don't want to burn rate limit on a probe.

Evasion throttle

When a WAF is detected, --waf-evasion automatically slows Dalfox to workers=1 and delay=3000ms so you don't trip rate limiters:

dalfox https://target.app --waf-evasion

Filter weak fingerprints

Each fingerprint carries a confidence score (0.0–1.0). Generic markers like Request blocked (0.3) or Server: Google Frontend (0.5) sometimes false-positive on benign origins. Use --waf-min-confidence to discard anything below the threshold:

# Keep only confident matches (drops 0.3/0.5 noise)
dalfox https://target.app --waf-min-confidence 0.7

Default is 0.3 (suppresses weak/generic matches like Server: Google Frontend). Pass --waf-min-confidence 0.0 to keep every match, or raise it when you suspect noisy passive detection is steering Dalfox into the wrong evasion strategy.

Mutation tactics (under the hood)

Different WAFs fall to different tricks. A small sample:

You don't configure these directly; they're selected automatically per WAF. To inspect what's happening, run with --debug.

Combining with encoders

Your --encoders list and the WAF's extra encoders are merged. So this:

dalfox https://target.app -e url,base64
# Cloudflare detected → extra encoders: unicode, zwsp
# Effective: url, base64, unicode, zwsp

De-duplicates automatically, preserves order.

Rate limiting & backoff

Dalfox tracks consecutive WAF blocks and automatically backs off with exponential sleep to avoid permanent blocks. You can help it along with --delay (per-request ms) and smaller --workers for fragile targets.

dalfox https://target.app --delay 500 --workers 10

Debugging

Turn on the debug stream to see fingerprint decisions and the active strategy:

dalfox --debug https://target.app 2>&1 | grep -i waf

Next

• Stored XSS covers the inject-here-verify-there pattern, which often interacts with WAFs.
• Output & Reports for integrating findings into your pipeline.