Dalfox MCP 服务器:让 Claude、Cursor 与任意 MCP 客户端直接驱动 XSS 扫描
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 兼容模式):
- 参数是扁平的。REST 把选项嵌套在
options下;本工具把它们放在顶层,options是未知字段。 - 别名只映射拼写。值类型错误仍会被拒绝;唯一例外是
cookie,它接受 REST 的单个Cookie:头字符串(以及表示"无 cookie"的null)。 - 别名不出现在发布的 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 工作流
- Agent 调用
preflight_dalfox确认目标可达并统计参数数量。 - Agent 调用
scan_with_dalfox,拿到scan_id。 - Agent 用进度对象里的
suggested_poll_interval_ms轮询get_results_dalfox。 - 状态终态且
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 通道。
进一步阅读
- 服务器集成与 REST API 对比:docs/content/integrations/server.md
- 集成总览(REST / MCP / Caido / Agent Skill 选型):docs/content/integrations/_index.md
- MCP 工具参数与 serde 策略源码:src/mcp/params.rs
- 工具 handler、容量控制与初始化握手源码:src/mcp/mod.rs
- 作业生命周期、保留期与容量常量:src/job/mod.rs
- 进度通知与 untrusted content 横幅实现:src/mcp/progress.rs、src/mcp/pagination.rs