Config File

Dalfox picks one config directory:

1. $XDG_CONFIG_HOME/dalfox/ when XDG_CONFIG_HOME is set and non-empty
2. otherwise $HOME/.config/dalfox/ (%USERPROFILE%\.config\dalfox\ when HOME is unset, e.g. on Windows)

It does not fall through to the second directory when the first holds no file. Inside the chosen directory it reads config.toml, or config.json when there is no config.toml. If neither exists, it writes a commented-out config.toml template there and runs with built-in defaults. This happens on the first run of any subcommand except completion and man, not only scan.

Override with --config <path>. TOML and JSON are both accepted: a .json path is parsed as JSON first, anything else as TOML first, and the other format is tried if that fails. A --config path that does not exist is created from a default template (JSON for a .json path) and the run uses built-in defaults, with a notice on stderr. Config files are capped at 1 MiB.

Everything lives under the [scan] table and mirrors the dalfox scan flag names (snake-cased). The one rename is --blind / -b, whose key is blind_callback_url; the global --debug flag is the debug key.

The config file only applies to CLI scans. dalfox server and dalfox mcp take scan options from each request and ignore [scan].

Complete example

[scan]
# INPUT
input_type = "auto"   # auto, url, file, pipe, raw-http, har
dedup_urls = "exact"  # exact, signature (collapse URLs differing only in param values), off
# state_file = "scan.state"  # record completed targets and skip them on re-run. CLI only — ignored by `dalfox server` / MCP

# OUTPUT
format = "plain"
# output = "results.json"
include_request = false
include_response = false
include_all = false
silence = false
dry_run = false
stream_findings = false
poc_type = "plain"
# limit = 100
limit_result_type = "all"
only_poc = []
# baseline = "baseline.json"
baseline_mode = "filter"
no_color = false

# TARGETS
param = []
# data = "user=test"
# headers = ["Accept: text/html"]
cookies = []
method = "GET"
# user_agent = "Mozilla/5.0"
# cookie_from_raw = "request.txt"

# SESSION
# session_check = "Sign out"
# session_check_url = "https://app.example.com/api/me"
on_session_loss = "abort"

# SCOPE
include_url = []
exclude_url = []
ignore_param = []
out_of_scope = []    # one pattern per entry: ["*.gov", "cdn.example.com"]
# out_of_scope_file = "scope.txt"

# DISCOVERY
only_discovery = false
skip_discovery = false
skip_reflection_header = false
skip_reflection_cookie = false
skip_reflection_path = false

# MINING
# mining_dict_word = "params.txt"
remote_wordlists = []
skip_mining = false
skip_mining_dict = false
skip_mining_dom = false

# NETWORK
timeout = 10
scan_timeout = 0
delay = 0
rate_limit = 0
retries = 0
retry_delay = 1000
# proxy = "http://127.0.0.1:8080"
insecure = true
follow_redirects = false
ignore_return = []

# ENGINE
workers = 50
max_concurrent_targets = 50
max_targets_per_host = 100

# XSS SCANNING
encoders = ["url", "html"]
remote_payloads = []
# custom_blind_xss_payload = "blind.txt"
# blind_callback_url = "https://callback.example"
# blind_oob = []                       # [] = enable with the public interactsh mesh; or name servers: ["oast.fun"]
# blind_oob_secret = "token"           # auth token for a self-hosted interactsh server
# blind_oob_wait = 30                  # seconds to keep polling after payloads are sent
# custom_payload = "payloads.txt"
only_custom_payload = false
# inject_marker = "FUZZ"
custom_alert_value = "1"
custom_alert_type = "none"
skip_xss_scanning = false
deep_scan = false
sxss = false
# sxss_url = "https://target.app/retrieval"
sxss_method = "GET"
sxss_retries = 3
max_payloads_per_param = 0
skip_ast_analysis = false
analyze_external_js = false
detect_outdated_libs = false
hpp = false

# WAF
waf_bypass = "auto"
skip_waf_probe = false
# force_waf = "cloudflare"
waf_evasion = false
waf_min_confidence = 0.3

# LOGGING
debug = false

Key reference

Input

Output

Targets

Session

Mid-scan session-loss detection — see Session monitoring.

Scope

Discovery & mining

Network

Engine

XSS scanning

WAF

Logging

Precedence

CLI flag  >  Config file  >  Built-in default

• A list key (headers, encoders, param, …) is replaced, not merged: one -H on the command line drops every headers entry from the config.
• A command-line flag can turn an on/off switch such as deep_scan or silence on, but never off. When the config sets one to true, no flag turns it back off for a single run. insecure is the exception: --insecure=false overrides the config.

Validation

Config values skip the CLI's argument parser, so Dalfox checks them when it loads the file:

• An invalid value for a fixed-choice key (format, poc_type, limit_result_type, only_poc, baseline_mode, custom_alert_type, dedup_urls, waf_bypass, on_session_loss, encoders), an unknown method / sxss_method / force_waf, a session_check that is not a valid regex, a session_check_url that is not an absolute URL, or limit = 0 prints a Warning: on stderr. That key then falls back to its built-in default and the scan continues. method, sxss_method and force_waf are case-normalised the same way the flags are.
• proxy, sxss_url and session_check_url go through the same startup checks as their flags. A proxy scheme Dalfox cannot route, or a URL whose scheme is not http/https, stops the scan with PARSE_ERROR (exit 2).
• Numeric keys have the same limits as their flags (workers, timeout, delay, scan_timeout, rate_limit, retries, retry_delay, sxss_retries, max_concurrent_targets, max_targets_per_host, waf_min_confidence). An out-of-range value stops the scan with INVALID_INPUT_TYPE (exit 2).
• Unknown keys, and keys placed outside the [scan] table, are ignored without a warning, so check the spelling and placement of a key that seems to have no effect.
• A file that fails to parse (a TOML syntax error, or a value of the wrong type such as workers = "10") is dropped whole. With --config Dalfox prints a warning. The default-path file is dropped silently.

See Getting Started → Configuration for examples.