Dalfox MCP 服务器:让 Claude、Cursor 与任意 MCP 客户端直接驱动 XSS 扫描

原创2026-10-12 09:16:281,606 阅读
文章标签:网络安全CLI

Dalfox MCP 服务器:让 Claude、Cursor 与任意 MCP 客户端直接驱动 XSS 扫描

Dalfox 的 dalfox mcp 子命令将一个基于 stdio 的 Model Context Protocol(MCP)服务器暴露给 AI 客户端,使 Claude Desktop、Claude Code、Cursor 等任意 MCP 兼容宿主都能直接调用 Dalfox 的 XSS 扫描能力。本文基于仓库文档 docs/content/integrations/mcp.md 与 MCP 实现源码,完整讲解服务器的启动配置、六个工具的完整参数与返回结构、异步扫描工作流、资源/提示(Resources/Prompts)扩展,以及面向 Agent 的安全边界设计。读完你将能够:把 Dalfox 接入主流 MCP 客户端,用 preflight_dalfox 预估扫描成本,用异步轮询或 wait=true 阻塞两种方式执行扫描,并正确解读结构化结果与 untrusted content 告警。

背景:什么是 MCP,Dalfox 在其中扮演什么角色

Model Context Protocol(MCP)是一个开放标准,用于让 AI 客户端与外部工具通信。Dalfox 通过 dalfox mcp 运行一个 stdio 传输的 MCP 服务器,使 Claude Desktop、Claude Code、Cursor 以及任何 MCP 兼容客户端都能直接驱动 Dalfox 扫描。文档明确强调:服务器通过 stdin/stdout 与客户端对话,应当由客户端启动它,而不是在终端里手动运行——它不是一个交互式命令。

从源码看,MCP 集成位于 src/mcp/mod.rs,基于 rmcp crate 提供的 stdio JSON-RPC 运行时(见该文件模块注释);扫描作业的核心调度逻辑则复用了 src/job/mod.rs 与 src/job/runner.rs 中 REST 服务器同一套执行引擎。也就是说:MCP 与 CLI、REST API 共享完全相同的扫描引擎,结果一致,只是"管道"不同——正如集成总览文档 docs/content/integrations/_index.md 所述。

启动服务器

dalfox mcp

该命令在 src/main.rs 中被路由到 mcp::run_mcp_server(),以 ScanOutcome 作为进程退出码:握手或传输失败会以非零码退出,便于 systemd 等监督器感知"服务器根本没起来",而不是误判为正常关闭。

如需调试日志,可运行:

dalfox mcp --debug

调试行输出到 stderr,不会污染 MCP 的 stdout 通道(文档 Troubleshooting 一节与 src/mcp/mod.rs 的实现一致:所有诊断统一走 eprintln!,并对日志消息做清洗)。

客户端配置:Claude Desktop 与 Claude Code

Claude Desktop

在 claude_desktop_config.json 中注册:

{
  "mcpServers": {
    "dalfox": {
      "command": "dalfox",
      "args": ["mcp"]
    }
  }
}

重启 Claude Desktop 后,Dalfox 会以名为 dalfox 的工具提供方出现。

Claude Code 与其他 CLI 客户端

claude mcp add dalfox -- dalfox mcp

六个工具总览:异步为先的设计

MCP 服务器暴露六个工具。扫描默认是异步的:提交一个扫描,轮询结果,然后继续做别的事。只有 preflight_dalfox 是内联返回答案的;scan_with_dalfox 在传入 wait: true 时才阻塞,且两者都支持按需流式进度通知。

工具 作用 同步/异步
scan_with_dalfox 提交扫描 默认立即返回 {scan_id, status: "queued"};wait: true 时阻塞
get_results_dalfox 轮询扫描状态与结果 异步轮询
list_scans_dalfox 列出所有被跟踪的扫描 异步
cancel_scan_dalfox 取消排队或运行中的扫描 异步
delete_scan_dalfox 从内存中删除扫描记录 异步
preflight_dalfox 不发攻击载荷地分析目标(参数发现 + 影响估算) 同步(无需轮询)

六个工具对应的 handler 都定义在 src/mcp/mod.rs,每个工具的输入参数类型集中在 src/mcp/params.rs。

scan_with_dalfox:提交一次扫描

请求示例与完整字段

文档给出一个精选示例:

{
  "target": "https://example.com/search?q=test",
  "method": "GET",
  "param": ["q"],
  "headers": ["Authorization: Bearer token"],
  "encoders": ["url", "html"],
  "timeout": 10,
  "scan_timeout": 0,
  "workers": 50,
  "rate_limit": 0,
  "insecure": true,
  "blind_callback_url": "https://callback.example",
  "blind_oob": true,
  "blind_oob_wait": 30,
  "session_check": "Sign out",
  "session_check_url": "https://app/me",
  "deep_scan": false,
  "skip_ast_analysis": false,
  "analyze_external_js": false,
  "detect_outdated_libs": false
}

而完整字段表(含默认值)如下——target 是唯一必填字段,其余均可省略:

{
  "target": "https://example.com/search?q=test",
  "param": [],
  "method": "GET",
  "data": null,
  "headers": [],
  "cookies": [],
  "user_agent": null,
  "encoders": ["url", "html"],
  "timeout": 10,
  "scan_timeout": 0,
  "delay": 0,
  "follow_redirects": false,
  "insecure": true,
  "proxy": null,
  "include_request": false,
  "include_response": false,
  "skip_mining": false,
  "skip_discovery": false,
  "deep_scan": false,
  "skip_ast_analysis": false,
  "analyze_external_js": false,
  "detect_outdated_libs": false,
  "blind_callback_url": null,
  "workers": 50,
  "rate_limit": 0,
  "waf_bypass": "auto",
  "skip_waf_probe": false,
  "force_waf": null,
  "waf_evasion": false,
  "waf_min_confidence": 0.3,
  "min_confidence": "high",
  "remote_payloads": [],
  "remote_wordlists": [],
  "max_payloads_per_param": 0,
  "wait": false,
  "wait_timeout_sec": 300
}

核心字段语义

  • target:唯一必填。必须以 http:// 或 https:// 开头,且必须可被 target_parser 解析;否则返回 invalid_params 错误(见 src/mcp/mod.rs)。
  • encoders:接受任意组合的已实现 payload 编码器:url、html、htmlpad、2url、3url、4url、base64、unicode、zwsp。顺序无关——扫描器按固定优先级应用(url → html → htmlpad → 2url → 3url → 4url → base64 → unicode → zwsp)并去重。传入 <a href="https://link.gitcode.com/i/737f163dc856fbc893a44b66087e8b16" target="_blank">"none"] 可完全禁用编码。该字段镜像 CLI 的 --encoders/-e 标志;未知的编码器名会被直接拒绝,否则它会静默匹配不到任何东西、悄悄缩减扫描的 payload 覆盖率(校验逻辑见 [src/job/mod.rs,可接受集合来自 src/cmd/scan/mod.rs 的 ENCODER_VALUES)。
  • method:与 CLI 接受的动词集合相同,并自动转为大写("post" → "POST")。发送不支持的动词是错误,而不是把一个错误方法发到线上(测试见 src/mcp/tests.rs)。
  • data:POST/PUT 的请求体,可以是表单编码("user=admin&pass=test")或 JSON 字符串。
  • cookies:接受 "name=value" 条目列表;headers 接受完整 "Name: Value" 行;user_agent 覆盖 User-Agent 头。
  • blind_callback_url:必须为空(表示"不做 blind XSS")或以 http:///https:// 开头。设置它会武装存储型 blind-XSS 注入——<script src=...> payload 会被写入每个 query、body、header 和 cookie 参数并留在目标上,因此一个永远收不到回调的值会被直接拒绝,而不是把那些 payload 白白留在目标上。
  • blind_oob:受管的 OAST(interactsh)通道——与 CLI 的 --blind-oob 相同。传 true 使用公共 mesh,或传一个 interactsh 主机列表(<a href="https://link.gitcode.com/i/c0ff1b1b9cc20368a8ce2cbc1d3bdcbf" target="_blank">"oast.fun"]);Dalfox 自行注册、把每个回调关联到引起它的 payload 并自行轮询,因此一个回调会成为 detection_method: "oob" 的 V 发现,而无需你自己跑监听器。轮询器与扫描绑定:扫描开始它启动,扫描结束、被取消或被删除时它停止(对应实现见 [src/job/spec.rs 的 BlindOobRequest 枚举)。
  • blind_oob_wait(0–600,默认 30):扫描最后一次请求后继续轮询 OOB 回调的秒数,计入 scan_timeout。
  • session_check(一个必须持续匹配已认证响应的正则)与 session_check_url(一个廉价的已认证端点,用于替代目标做探测):即使没有 cookie 也能开启会话丢失检测;无效的正则或非 http(s) 的探测 URL 会返回 invalid_params 错误。会话中途死亡的细节见下文 get_results_dalfox。
  • insecure:控制 TLS 证书校验(默认 true,扫描器友好);设为 false 则强制证书校验、拒绝自签名或过期证书。镜像 CLI 的 --insecure 标志。注意默认值为 true 意味着默认跳过证书校验——对 https 目标扫描时,src/mcp/mod.rs 会在作业日志中记录该事实,提醒你如需校验可传 insecure: false。
  • analyze_external_js:默认 false(opt-in)。设为 true 会在预检阶段抓取同源 <script src> 包并对它们运行 AST DOM-XSS 分析,适用于所有 sink 逻辑都在外部 bundle、页面没有服务端反射的 SPA。上限:16 个文件、每文件 512 KiB(常量见 src/scanning/ast_dom_phase.rs)。--include-url/--exclude-url 作用域过滤器是 CLI 专属,MCP 无对应参数,发送即报错。
  • detect_outdated_libs:默认 false(opt-in)。设为 true 会额外输出过时/已知漏洞 JS 库的信息性 [I] 发现(CWE-1104,0 次额外请求)。不开时扫描只报告 XSS。
  • rate_limit:限制扫描的出站请求速率(请求/秒;0 = 不限,默认)。在所有 worker 任务间统一执行,可用于对脆弱目标温柔一点或保持在 WAF 阈值之下。
  • scan_timeout:整个扫描的墙钟预算(秒;默认 0 = 不限),区别于每个请求的 timeout。触发时扫描停止、保留部分发现、以 cancelled 状态收尾并带提及 scan_timeout 的 error_message。用它约束长扫描或 deep_scan,保证 Agent 的轮询循环一定会终止。
  • delay(默认 0,范围 0–9999 毫秒)、follow_redirects(默认 false,跟随 3xx 响应)、proxy(把每个请求路由到 HTTP 或 SOCKS 代理,如 "http://127.0.0.1:8080")。
  • include_request/include_response(均默认 false):把原始 HTTP 请求文本和原始响应体附加到每个发现上,供取证分析。仅在确实需要证据时开启——响应可能很大。
  • 五个 WAF 字段镜像 CLI 的 WAF 标志:
    • waf_bypass:"auto"(检测后绕过,默认)或 "off"(仅检测并报告);"force" 也被接受且行为同 "auto"。
    • skip_waf_probe(默认 false):跳过主动挑衅探测;预检响应上的被动检测仍然运行。
    • force_waf:固定某个 WAF 画像(如 "cloudflare"、"akamai"、"modsec")替代检测结果;在 "auto"/"force" 下生效,"off" 下仅报告不绕过。
    • waf_evasion(默认 false):开启自适应规避。
    • waf_min_confidence:检测置信度下限 [0.0, 1.0](默认 0.3),低于它的指纹被丢弃。
    • waf_bypass/force_waf 的未知值、超出范围的 waf_min_confidence 会被作为 invalid_params 拒绝。
  • min_confidence("low" 或 "high";省略则保留所有发现):即 CLI 的 --min-confidence。"high" 会把所有低置信度发现从作业结果和 findings_so_far 中剔除;I 发现不评级、始终保留。其他任何值都会被作为 invalid_params 拒绝。
  • remote_payloads/remote_wordlists(均默认 []):在扫描开始前从远程提供方拉取额外的 XSS payload("portswigger"、"payloadbox")和参数词表("burp"、"assetnote")。未注册的名称会被拒绝——否则它会静默拉到空、让扫描在调用方要求的 payload 覆盖缺失时仍然报告 done。
  • max_payloads_per_param:限制每个参数被测试的 payload 数量(默认 0 = 除内置安全上限外不限)。Agent 冒烟扫描建议用小值如 10–50。
  • wait(默认 false):把调用变成阻塞式——不再立即返回 {scan_id, status: "queued"},而是阻塞到扫描 done/error/cancelled 并返回与 get_results_dalfox 相同的结构。wait_timeout_sec(默认 300,范围 1–86400)是该等待的墙钟预算,wait: false 时被忽略;超时后作业继续运行、响应携带 wait_timed_out: true。
  • param:指定要测试的参数,支持 "name:location" 位置提示语法(query、body、header、cookie、path、json)。

返回结构

提交成功(异步模式)返回:

{ "scan_id": "9f2c…", "target": "https://example.com/search?q=test", "status": "queued" }

参数拒绝策略:宁可报错,不可静默降级

MCP 工具的参数解析采用严格的 deny_unknown_fields 策略(见 src/mcp/params.rs 模块注释):工具不认识的字段名会被拒绝,调用以 JSON-RPC 错误(-32602,invalid params)返回,并点名出错的键、列出所有可接受的键。它不会被静默丢弃——否则一个拼错的 cookies 会让扫描以未认证状态跑、什么都找不到、报告 status: "done" 且零发现,而这个"干净"结果与真实结果无法区分。被拒绝的调用不携带 scan_id,因此没有可轮询的东西,也不可能被误认为一次跑过的扫描。

所有坏参数都走同一个通道——缺少 target、本应是字符串的地方给了数字、超出上限的值——因此客户端只需关注 error;工具结果通道只留给真正跑过的工具。各字段上限与 REST API 相同:timeout 1–299 秒、delay 0–9999 毫秒、workers 1–500、scan_timeout 0–86400 秒、max_payloads_per_param 0–100000(常量见 src/job/mod.rs)。

一个注意点:部分宿主对 JSON-RPC 错误只给用户显示一个笼统的失败,而不会把错误文本回传给模型,所以模型可能看不到到底是哪个键写错了。

REST 拼写别名

为了让常见错误不成其为错误,REST API 的字段拼写被接受为别名:url 对应 target、cookie 对应 cookies、header 对应 headers、worker 对应 workers、blind 对应 blind_callback_url。cookie 还接受单个 Cookie: 头字符串("sid=abc; lang=en")代替列表。工具 schema 广告的是上面的规范 MCP 名称;别名存在的意义是让按 REST 文档写的参数也能跑出它们描述的扫描。

对别名有三条限制(以免被误认为通用 REST 兼容模式):

  1. 参数是扁平的。REST 把选项嵌套在 options 下;本工具把它们放在顶层,options 是未知字段。
  2. 别名只映射拼写。值类型错误仍会被拒绝;唯一例外是 cookie,它接受 REST 的单个 Cookie: 头字符串(以及表示"无 cookie"的 null)。
  3. 别名不出现在发布的 schema 中。schema 只广告规范 MCP 拼写;在派发前用 inputSchema 校验参数、再拒绝 REST 拼写调用的客户端,将在请求到达服务器之前就拒绝它——别名帮助的是原样透传参数的调用方。优先使用规范名称。

另外两个表面上的选项在这里刻意缺席而非别名化,请求它们会报错:REST 的 callback_url(一个会让模型把扫描输出发送到自己选定的主机的 webhook)和 CLI 的 --cookie-from-raw(即 cookie_from_raw,一个服务端文件读取,见 src/mcp/params.rs 的安全说明)。请直接通过 cookies 传 cookie。

preflight_dalfox:不发送载荷的目标预检

在投入扫描之前先评估目标。它不接受 scan_with_dalfox 的全套参数——它不发载荷,因此描述节流、worker、WAF 处理、blind XSS 或等待的选项没有可作用的对象,会被拒绝。其完整字段表如下(target 是唯一必填):

{
  "target": "https://example.com",
  "param": [],
  "method": "GET",
  "data": null,
  "headers": [],
  "cookies": [],
  "user_agent": null,
  "timeout": 10,
  "proxy": null,
  "follow_redirects": false,
  "insecure": true,
  "skip_discovery": false,
  "skip_mining": false,
  "encoders": ["url", "html"],
  "max_payloads_per_param": 0,
  "deep_scan": false
}

返回可达性、发现的参数与预估请求数:

{
  "target": "https://example.com",
  "reachable": true,
  "method": "GET",
  "params_discovered": 3,
  "estimated_total_requests": 412,
  "params": [
    { "name": "q", "location": "Query", "estimated_requests": 196 },
    { "name": "page", "location": "Query", "estimated_requests": 108 },
    { "name": "lang", "location": "Cookie", "estimated_requests": 108 }
  ]
}

不可达目标返回 reachable: false 并带 error_code: "CONNECTION_FAILED"。param 仅为与扫描工具对称而被接受、但不生效:preflight 总是报告完整发现集(对应实现见 src/mcp/mod.rs,注释明确说明传入 param 过滤器会低估发现量)。

encoders、max_payloads_per_param 和 deep_scan 本身不发任何东西——它们描述的是你正要调度的那次 scan_with_dalfox 调用,因此 estimated_total_requests 反映的是那次扫描的扇出。请传入你打算实际扫描用的相同值。

估算把扫描每参数运行的两个阶段(反射与 DOM 验证)都算在内,各自受每参数 payload 上限约束——与 --dry-run 相同的算法。它是个下界:WAF 绕过变异以及扫描额外添加的 CSP/技术特定 payload 不计入。

get_results_dalfox:轮询扫描

请求只需一个 scan_id:

{ "scan_id": "9f2c…" }

运行中的响应

{
  "scan_id": "9f2c…",
  "target": "…",
  "status": "running",
  "settled": false,
  "progress": {
    "params_total": 10,
    "params_tested": 4,
    "requests_sent": 215,
    "requests_failed": 0,
    "findings_so_far": 1,
    "estimated_completion_pct": 40,
    "suggested_poll_interval_ms": 2000
  }
}

完整的状态响应还携带 results(扫描终结前为 null;对从未到达目标或被取消在开始前的扫描也保持 null)、pagination、queued_at_ms、started_at_ms、finished_at_ms、duration_ms,以及设置时的 error_message。requests_failed 统计从未到达目标的请求:当它占 requests_sent 很大比例时,零发现意味着扫描从未真正运行,而不是目标干净。

完成后的响应

{
  "scan_id": "9f2c…",
  "status": "done",
  "settled": true,
  "results": [
    {
      "type": "V",
      "type_description": "Vulnerable - dalfox asserts this input is exploitable; act on it",
      "detection_method": "dom-verification",
      "confidence": "high",
      "confidence_reason": "DOM verification confirmed an executable position (DOM marker)",
      "inject_type": "inHTML",
      "method": "GET",
      "param": "q",
      "payload": "<svg/onload=alert(1)>",
      "evidence": "DOM verification successful for param q (DOM marker)",
      "cwe": "CWE-79",
      "severity": "High"
    }
  ]
}

关键语义

  • _untrusted_content_notice:每个携带发现的响应都带这个横幅,且被序列化为第一个键,让 Agent 在读到警告内容之前先看到警告。evidence、response、request、payload、param、location、message_str 字段引用的是扫描目标选择的字节,而目标正是被测对象——所以 Agent 必须把它们当作要报告的数据,绝不可当作指令。被扫描的页面可以嵌入形如对模型下达指令的文本,照做就会让目标替你挑选下一次调用的 target、proxy、blind_callback_url 或 include_*(实现见 src/mcp/pagination.rs,密钥 _untrusted_content_notice 因前导下划线排序靠前,保证序列化时先于内容输出)。preflight_dalfox 在发现参数时也附带同一告警,因为每个发现参数的 name 都取自目标自己的标记。
  • offset/limit 分页与 pagination:分页描述符报告 {total, offset, limit, returned, has_more}。单页另有 2 MiB 发现字节上限(常量 MAX_RESULTS_PAGE_BYTES 见 src/mcp/pagination.rs),因为决定一次扫描产生多少发现的是目标而不是调用方。当预算截断页面时,pagination 会增加 truncated_by_size: true 与 max_page_bytes——返回的发现比 limit 要求的少,其余的仍在下一个 offset 处可取。单个超过预算的发现会被单独发出而非丢弃,因此分页总能前进。
  • settled 与轮询节奏:progress.estimated_completion_pct 和 params_tested 随每个被发现的参数完成而实时前进,可用于安排轮询——遵循 suggested_poll_interval_ms。一旦扫描离开 queued,状态响应还包含 settled:终态 worker 仍在排空时为 false,记录可安全删除时变为 true。尚未 settled 的终态响应保持非零的建议轮询间隔;在调用 delete_scan_dalfox 之前先等 settled: true。
  • 连接失败 ≠ 干净:如果目标不可达(DNS 失败、连接拒绝、TLS 错误、超时),扫描以 status: "error" 结束、error_message 含 CONNECTION_FAILED,而不是以空 results 的 done 结束——与 preflight_dalfox 用 reachable: false 报告的区别相同。target 必须以 http:// 或 https:// 开头。
  • 会话中途死亡:当调用携带凭据(cookies,或 headers 中的 Cookie/Authorization 条目)——或显式设置了 session_check/session_check_url——Dalfox 会在扫描前对已认证响应做指纹、在结束时复检;若会话在此期间过期,扫描以 status: "error" 收尾、error_message 以 SESSION_LOST: 开头,而不是空 results 的 done。不要把这样的扫描总结为"未发现 XSS"——其实什么也没测。未传凭据且未传 session_check 时,监控零成本(相关实现与测试见 src/mcp/tests.rs)。
  • warnings:不致使扫描失败的问题仍然送达——当存在时(如 blind_oob 注册或轮询失败、session_check 基线无法捕获、发现参数被上限截断),结果会附带一个 warnings 列表。零发现且 warnings 非空的 done 扫描不是目标干净的证明。

list_scans_dalfox / cancel_scan_dalfox / delete_scan_dalfox

list_scans_dalfox:列出所有被跟踪的扫描

所有参数可选,最新优先:

{ "status": "running", "offset": 0, "limit": 0 }

status 取 queued、running、done、error、cancelled 之一;offset/limit 对列表分页(limit: 0,默认,从 offset 起返回全部)。

返回 total、scans: [{scan_id, target, status, settled, result_count, queued_at_ms, started_at_ms, finished_at_ms, duration_ms}] 与 pagination: {offset, limit, returned, has_more},失败扫描还带 error_message——没有它,一行 status: "error", result_count: 0 看起来就和干净扫描一模一样。

cancel_scan_dalfox:取消排队或运行中的扫描

{ "scan_id": "9f2c…" }

返回 {scan_id, target, cancelled, previous_status}。仅当扫描处于 queued 或 running 时 cancelled 为 true;对已结束的扫描调用是 no-op、cancelled 为 false。运行中的扫描在下一个取消检查点停止,以 cancelled 状态留在列表中、保留部分结果。

delete_scan_dalfox:从内存删除扫描记录

{ "scan_id": "9f2c…" }

永久地从内存中移除一条被跟踪的扫描。只有终态(done、error、cancelled)且 worker 已结束排空的扫描才能被删除;运行中或排队中的扫描必须先取消。若删除报告"worker 仍在排空",请轮询扫描并稍等片刻后重试。终态扫描也会在 1 小时后自动清除。

返回 {scan_id, target, deleted: true, previous_status}。

容量限制

MCP 服务器最多持有 100 个活动(排队或运行中)扫描与 32 个并发 preflight(常量见 src/job/mod.rs 与 src/job/mod.rs)。超出任一限制的调用以 JSON-RPC -32603 错误被拒绝,提示服务器已满;与 -32602 不同,-32603 值得在某个扫描结束或被取消后重试。被取消的扫描在 worker 真正停止(settled: true)前占住其槽位。最多保留 1000 个已完成扫描,超出后丢弃最旧的;每个终态扫描在结束后 1 小时清除。

单个扫描最多测试 512 个参数(MAX_DISCOVERED_PARAMS,见 src/job/mod.rs)。目标暴露更多参数时,发现集被截断、扫描仍以 done 结束,所以请传 param 挑选哪些重要。

deep_scan(每个反射 payload 记录一条发现)在约 2000 条发现后停止(在途请求可能再多几条;MAX_FINDINGS_PER_JOB 见 src/job/mod.rs)。它仍以 done 结束,error_message 说明结果是部分的。

结构化结果与行为提示(annotations)

每个工具都在 tools/list 中发布 outputSchema,并以符合它的 structuredContent 对象应答 tools/call,因此客户端可以校验并解构响应,而不是解析字符串。同一 JSON 仍以常规文本内容块提供,所以今天读文本的客户端无需改变。

每个工具还携带展示 title 与标准行为提示,让客户端自行决定哪些调用可安全执行而无需询问:

工具 readOnlyHint destructiveHint idempotentHint openWorldHint
scan_with_dalfox false true false true
preflight_dalfox false false false true
get_results_dalfox true — true false
list_scans_dalfox true — true false
cancel_scan_dalfox false false true false
delete_scan_dalfox false true false false

openWorldHint: true 标记每个通过网络触达第三方主机的工具。destructiveHint: true 标记两个可能永久改变事物的工具:一个丢弃记录,另一个把 payload 注入每个被发现的参数——包括你提供的 POST body,且在设置 blind_callback_url 时会留下留在目标上的存储型 <script src=...>。注意 preflight_dalfox 也不是只读的:它不发攻击 payload,但它接受 method 和 data,且其挖掘阶段会发出探测请求,因此 POST preflight 可以改变目标上的状态。

initialize 握手把服务器标识为 dalfox(展示标题 Dalfox XSS Scanner),带自身版本、图标,并以文档站作为 websiteUrl;声明 tools、resources、prompts、completions 能力,并返回覆盖工具预期顺序、发现轴读取方式与下述来源规则的 instructions(见 src/mcp/mod.rs)。

进度通知、资源与提示

进度(Progress)。 给 wait=true 的 scan_with_dalfox 调用或 preflight_dalfox 附加 _meta.progressToken,Dalfox 会在调用打开期间针对该 token 流式发送 notifications/progress——客户端就能展示"在动"而不是为可能持续数分钟的工作显示静默转圈。对扫描而言,数值型 progress 是累计已发送请求数(不是百分比——规范要求数值必须递增,而 params_tested 在整个发现/挖掘阶段都停为零,见 src/mcp/progress.rs 的设计说明),message 携带阶段、已测参数、迄今发现数与从未到达目标的请求数。preflight_dalfox 改为每两秒发一次心跳(analyzing target (Ns elapsed))。终态不发布任何通知:工具自身的结果就是完成信号。

取消(Cancellation)。 对在途 wait=true 调用发送 notifications/cancelled 会停止扫描本身,而不仅仅是停止等待——作业以 cancelled 收尾、error_message 为 the client cancelled the tool call、保留它已发现的东西。这与等待预算单纯到期(wait_timed_out: true)刻意不同:后者让扫描继续运行,以便你继续轮询。

资源(Resources)。 扫描不仅可调用,还可寻址:

URI 内容
dalfox://scans 作业索引——与 list_scans_dalfox 返回的相同 body
dalfox://scan/{scan_id} 单个扫描的状态、进度与发现——与 get_results_dalfox 返回的相同 body

resources/list 返回索引外加每个被跟踪扫描的一个条目(带光标分页),因此宿主的上下文选择器显示真实扫描而非待填写的模板。索引读取自限 200 行——resources/read 不接受分页参数,因此 body 在其 pagination 中说明在哪里被截断(见 src/mcp/resources.rs)。scan_with_dalfox 和 get_results_dalfox 的结果还携带指向扫描的 resource_link 内容块,让客户端附加发现而非要求模型重述;对协商到早于 2025-06-18 协议版本的客户端,链接被省略(该版本之前无法解析此块类型)。

提示(Prompts)。 两个工作流发布在客户端的提示菜单中:

Prompt 参数 作用
scan_target target 用 preflight 评估扫描规模、运行它、按置信度报告发现
triage_findings scan_id 沿 type/detection_method 轴读取已完成的扫描,说明未覆盖的部分

completion/complete 为 triage prompt 和 dalfox://scan/{scan_id} 模板填充 scan_id 参数(来源是仍被跟踪的扫描),这一点很重要:scan id 是 64 字符的摘要,没人能手输。

典型 Agent 工作流

  1. Agent 调用 preflight_dalfox 确认目标可达并统计参数数量。
  2. Agent 调用 scan_with_dalfox,拿到 scan_id。
  3. Agent 用进度对象里的 suggested_poll_interval_ms 轮询 get_results_dalfox。
  4. 状态终态且 settled == true 后,Agent 可调用 delete_scan_dalfox,然后总结发现并向用户汇报。

由于扫描是异步的,Agent 始终保持响应。若想把长扫描折叠进单次调用,请用带进度 token 的 wait=true。

授权与安全边界

与 CLI 相同、且 Dalfox 无法替你检查的规则:只扫描你被授权测试的目标。 考虑在 Agent 系统提示中给 Dalfox MCP 调用加一道显式用户确认步骤,例如"每次扫描前确认范围"。

发现是 Agent 的不可信输入。 与 CLI 和 REST API 不同,MCP 把扫描输出交给会照着读到的内容行动的模型,而发现中每个被引用的字节都是目标选择的。Dalfox 用 _untrusted_content_notice 标记这些响应,但标签是提醒、不是沙箱——把范围决策(哪个目标、哪个代理、哪个回调)留在操作者手中,绝不要让扫描器从页面读到的内容改变它。

扫描的 error_message 也一样:已认证会话中途死亡时,Dalfox 报告的是源站把它重定向到的 URL,因此即使零发现的扫描,该字段也引用目标。携带它的 body——状态轮询、list_scans_dalfox 列表、对应的资源——都因此携带 _untrusted_content_notice。

故障排查

  • 工具不显示? 确保 dalfox 二进制在 MCP 客户端所用的 PATH 上。对 macOS 上的 Claude Desktop,那通常就是 /usr/local/bin 或 /opt/homebrew/bin。
  • 结果为空? 再轮询一次;扫描是异步的。用 suggested_poll_interval_ms 作为节奏。
  • 想要日志? 设置阶段运行 dalfox mcp --debug。调试行走 stderr,不污染 MCP 通道。

进一步阅读

登录后查看全文
dalfox