MapScan DSH

DeepSeek Harness 动态 Cordis 插件：FOFA / Shodan / 鹰图 Hunter / ZoomEye / Quake 五平台网络空间测绘综合查询。 统一搜索、归一化输出、API Key 持久化管理，面向渗透测试与资产测绘工作流。

Overview

五个国内主流网络空间测绘平台（FOFA / Shodan / 鹰图Hunter / ZoomEye / Quake）语法各异、鉴权方式各异。 MapScan 把它们封装成 6 个统一的动态工具，输出归一化结果（ip/端口/协议/域名/标题/banner/证书/地理/组件/风险）， 并内置 API Key 持久化管理，让渗透测试、SRC 资产梳理、攻击面测绘可以直接用自然语言驱动。

工具	说明
map_search	五平台统一搜索；platform 可省略(自动联合所有已填 Key 的平台, 未配置自动跳过)、pages 翻页、save 落盘
map_ip_detail	单 IP 测绘详情；platform 可省略(自动并行查询已填 Key 的平台)；可选 honeyscore 蜜罐评分
map_stats	聚合统计；platform 可省略(自动统计已填 Key 的平台)：FOFA 字段分布、Shodan 总数+facets
map_account	账户与配额；platform 可省略(自动查询所有已填 Key 的平台)：fcoin/F点/query_credits/剩余积分/credit
map_dns	Shodan DNS：hostnames 批量解析(域名→IP, 免额度) / domain 子域枚举(A/CNAME 记录)
map_set_keys	API Key 持久化管理（凭证库 / 环境变量，支持查看与删除）

• 按 Key 自动路由：所有 platform 参数均可省略——只对已填写 API Key 的平台执行，未填写的自动跳过并列入 skipped
• 零运行时依赖：插件本体只使用 DSH 沙箱能力（ctx.shell 驱动的 curl + web.fetch 回退），无任何 npm 运行时依赖
• 沙箱友好：支持自定义 Header（ZoomEye API-KEY）与 POST（Quake X-QuakeToken）
• 可测试：模块化 ESM 源码 + node:test 单元/集成测试（85 例）+ 零依赖构建流水线
• 可并行：只读工具声明 isConcurrencySafe；多平台场景内部并行、结果去重附摘要
• 可取消：转发调用方 exec.signal 到 shell 请求，用户中断可终止 curl 子进程

Compatibility

项目	已验证版本	验证日期
DeepSeek Harness	@deepseek-ai/dsh 0.2.0-rc.2（DSH 桌面版 V0.2.0-rc.2 运行时）	2026-10-04
DeepSeek Harness（本地实测）	@deepseek-ai/dsh-base 0.1.7-rc.2（脚本与端点端到端实测环境）	2026-10-04
Node.js（构建/测试工具链）	24.9.0（engines >=22.19；CI 矩阵 22/24/26）	2026-10-04
操作系统	Windows 11（curl 8.21；ctx.shell=pwsh 执行器）	2026-10-04

最低运行时要求：DSH ≥ 0.1.7-rc.2。 DSH 在 0.1.7-rc.2 将 shell 执行从单步 ctx.shell.run(request) 改为两步 resolve(request) + execute(spec)，本插件 1.5.0 起按两步契约实现； 在 0.1.0-rc.6 等旧版本上会因缺少 execute 抛出可读的契约错误而无法工作。

平台 API 契约以各平台官方文档及 projectdiscovery/uncover 核对，见 docs/API.md。 兼容性结论只覆盖上述记录环境；生态收录目录的判定口径见 docs/COMPLIANCE.md。

Install / Uninstall

MapScan 是一个 DSH bundle 插件：package.json 声明 dsh.bundle.patch → 根目录 cordis.patch.yml， 补丁把 mapscan-dsh 作为一行挂载进装配树。这是被 dsh plugin / 插件市场 / 设置页插件清单识别的唯一声明方式。

✨ 方式一：插件市场 / 设置页安装（推荐）

设置 → 插件 → 安装，填入以下任一：

O3SET/dsh-mapscan                                  # GitHub 仓库（topic: dsh-plugin）
github:O3SET/dsh-mapscan                           # 显式 git 源
file:D:/path/to/dsh-mapscan                        # 本地克隆（绝对路径）

方式二：一键脚本（本地克隆，等价动作）

git clone https://github.com/O3SET/dsh-mapscan.git
node dsh-mapscan\scripts\install.mjs
# 重启 DSH 进程 → 6 个 map_* 工具全局可用

install.mjs 做三件事，与插件市场的安装动作一致：

1. 在 profile 目录执行 pnpm add link:<本仓库>（link: 不复制 devDependencies，且仓库改动即时生效，升级无需重装）；
2. 把 mapscan-dsh 追加进 profile package.json 的 dsh.profile.bundles 层列表；
3. 清理 1.5.0 之前旧装法遗留的手工 insert: 行（避免重复注册）。

• 非默认 profile：$env:DSH_PROFILE="你的profile"; node scripts/install.mjs（本仓库默认 desktop）
• 卸载：node scripts/uninstall.mjs（移除 bundle 层登记 + pnpm 依赖后重启）
• 幂等：重复执行安全
• 排错：装完在插件列表里看不到 → 确认 package.json 有 dsh.bundle.patch 且 cordis.patch.yml 随包发布； 旧版「junction + 手写补丁行」的装法能被 loader 加载但插件清单读不到，会表现为「已安装却检测不到」

开发/预览安装（动态插件，会话级，可选）

构建产物 dist/mapscan-host.js 是 DSH 函数体，可在会话内临时安装：

cordis_define { kind: new, idPrefix: mscan, code: { host: <dist 内容> } }
cordis_run   { pluginId: ..., packageId: ..., mode: run }

动态插件与持久化插件共存时作用域版本优先；正式使用建议走方式一或方式二。 清除已存 Key：map_set_keys { "remove": ["fofa","shodan","hunter","zoomeye","quake"] }

Quick start

# 1. 配置 API Key（持久化到凭证库）
map_set_keys { "fofa": "你的Key", "shodan": "你的Key" }

# 2. 搜索
map_search { "platform": "fofa",   "query": "app=\"nginx\" && country=\"CN\"", "size": 20 }
map_search { "platform": "shodan", "query": "nginx port:443 country:CN" }

# 3. 详情 / 统计 / 配额
map_ip_detail { "platform": "shodan", "ip": "1.1.1.1" }
map_stats     { "platform": "fofa", "query": "app=\"nginx\"", "fields": "title,port" }
map_account   { "platform": "fofa" }

更多示例见 examples/queries.md，检索语法见 docs/QUERY-SYNTAX.md。

Configuration

方式一：配置文件 / 插件 Config（当前可用）

直接编辑 profile 里 mapscan-dsh 那一行的 config: 块，或让插件市场/插件管理把它写进去：

- insert:
    - id: mapscan-dsh
      name: 'mapscan-dsh'
      config:
        fofa: '你的 FOFA Key'
        shodan: '你的 Shodan Key'
        timeoutSec: 45

Config 是 schemastery schema（见 src/index.js），插件挂载时由 Cordis 校验后注入 apply。

方式二：对话里配置 / 环境变量

配置项	默认	说明
Config fofa / shodan / hunter / zoomeye / quake	未配置	插件 Config，明文保存在 profile 配置里
Config timeoutSec	30	单请求超时（秒），夹取 5~300
map_set_keys 参数	未配置	写入 DSH 凭证库（持久化，不落配置文件）
环境变量 MAPSCAN_*_API_KEY	—	与凭证库同名引用，环境变量优先
环境变量 FOFA_API_KEY / SHODAN_API_KEY / HUNTER_API_KEY / ZOOMEYE_API_KEY / QUAKE_API_KEY	—	社区惯用名，次优先

关于设置页图形表单（暂未启用）

本仓库带有实验性的浏览器半侧 src/client.js（注册 settings.section 页面）， 但尚未在真机验证通过，且它的加载失败会让插件在客户端列表里显示异常， 因此 package.json 刻意不声明 dsh.client / exports["./client"]，该产物不会被加载。

若要启用，需把它接回 package.json 的 dsh.client（platform: 'web'）与 exports["./client"]， 并具备浏览器控制台以便调试。已确认的实现要点：

1. DSH 不会从插件 Config 自动生成表单——autoGenerate 目前没有任何客户端消费 （dsh-settings README: “no shipped client does so yet”）；
2. Config 必须是 schemastery schema（isNativeConfigSchema 判定），否则配置 status 为 unsupported；
3. 字段要在表单里可见且可写，必须加 .volatile()；API Key 另加 .role('secret') （读取时值被抹掉，只回传 {path,set} 存在性）；
4. 写入只在本机回环地址下持久化；
5. 客户端 bundle 是 classic script，模块 id 必须等于包名，且只能 require 宿主模块表里的 react / react-dom / @deepseek-ai/cordis / dsh-client-store / dsh-client-ui-slots / dsh-client-ui-primitives / dsh-client-ui-dockkit —— 表外 require 会抛 “missed the module table”。 | 工具参数 key | — | 单次调用临时覆盖，不落盘 | | size（每页条数） | 20（最大 100） | 各工具统一夹取 |

Key 解析优先级：工具参数 key > 插件 Config（设置页）> 环境变量 / 凭证库 > 社区惯用环境变量名。 即设置页填过的值会掩盖凭证库条目；想回到凭证库，请把设置页对应字段清空。

⚠️ 落盘提示：设置页填写方式会把 Key 以明文写入 profile 的 cordis.patch.yml。 若不希望 Key 落盘，请改用 map_set_keys（凭证库）或环境变量，并保持设置页表单为空。 其余敏感项不写任何配置文件。

Key 获取地址：fofa.info 个人中心、account.shodan.io、hunter.qianxin.com 个人中心、zoomeye.org/profile、quake.360.net 个人中心。

Permissions & data

• 文件系统：仅在 map_search 使用 save 参数时写入你指定的 JSON 文件路径（默认不写任何文件）
• 网络：仅访问五个平台官方 API 域名（fofa.info / api.shodan.io / hunter.qianxin.com / api.zoomeye.org / quake.360.net）
• 凭据：读取设置页 Config、MAPSCAN_* 与平台惯用名环境变量/凭证库条目；API Key 出现在子进程（curl）命令行中，属平台 API 的鉴权要求，注意本机进程列表可见性
• 数据：查询结果仅返回给模型与会话，除 save 外不落盘
• 插件为 Host-only 代码，在 DSH 沙箱内运行；安装第三方插件即代表信任其代码，请审阅 源码（安全报告见 SECURITY.md）

Troubleshooting

现象	处理
未配置 xxx 的 API Key	到设置页「插件 → MapScan」填 Key，或用 map_set_keys/环境变量；map_set_keys 无参查看状态
设置页填了 Key 却不生效	优先级为「工具参数 > 设置页 Config > 凭证库」；设置页留空后才会回退凭证库。改完需重启 DSH
设置页「插件」里没有 MapScan 的配置项	确认插件已装且被识别（见 Install 章节排错），并已重启 DSH——Config 在插件挂载时才注册
FOFA 返回错误: [-700] 账号无效	Key 错误/过期，到 fofa.info 个人中心核对
响应不是 JSON (HTTP 401)	Shodan/ZoomEye/Quake 的 401 响应非 JSON，Key 无效时属正常提示，核对 Key
Hunter 返回错误 code=401: 令牌过期	鹰图 Key 过期，重新生成；hunter 根域名 403 是 WAF 正常现象，仅 /openApi/* 可用
HTTP 请求失败 (无响应体)	目标平台不可达或超时；插件会附上 curl stderr 详情，检查网络/代理
未挂载凭证服务(credentials)	当前 DSH 组合缺凭证提供方，改用环境变量注入 Key

Development

npm install        # devDeps: eslint / prettier / husky / lint-staged
npm run check      # lint + format:check + build + test 全量检查 (pre-commit 也会跑增量检查)
npm test           # 构建并运行全部测试
npm run build      # 重新生成 dist/mapscan-host.js

目录结构、沙箱约束、新增平台清单、发布流程见 docs/DEVELOPMENT.md； 贡献约定见 CONTRIBUTING.md；生态收录规范对照见 docs/COMPLIANCE.md。

License & security

MIT © 2026 MapScan contributors。安全漏洞请私下报告（见 SECURITY.md），勿公开提交 Issue。

免责声明

本工具仅用于授权测试、安全研究与资产梳理。使用者须遵守目标平台的服务条款与当地法律法规，并对自身行为负责。