Shodan 技能是一个零依赖的 Python 客户端，封装了有文档的 Shodan API。所有调用都经由 scripts/shodan_api.py 执行，该脚本在标准输出打印稳定的 JSON 信封，并返回明确的退出码。
用途
该技能用于查询 Shodan API，完成主机情报、暴露面研究、搜索与分面、DNS 查询、按需扫描、网络告警与通知器管理、批量数据集等任务。所有路径均相对于该技能文件夹；如果工作目录不在该文件夹内，需要使用文件夹的绝对路径。
首次调用前的配置
先运行 python3 scripts/shodan_api.py config test，它会解析 API 密钥并报告套餐与剩余额度。如果没有密钥，需要阅读配置说明并设置密钥。不要要求用户把密钥粘贴到命令、提示、源文件或聊天消息中；config set 会从隐藏提示或 stdin 读取密钥，使其不进入命令行参数、shell 历史或进程列表。
主要能力与操作方式
运行一个操作的格式为：python3 scripts/shodan_api.py GROUP ACTION [arguments]。
python3 scripts/shodan_api.py operations 会以 JSON 形式打印全部 61 个操作，包含 method、path、access class 和 credit cost；GROUP ACTION --help 给出单个操作的确切参数。operations 也提供可读形式的同一清单。
建议按以下顺序执行：先从 operations 中选择操作，匹配用户请求，不扩大目标范围、不添加用户未请求的操作；再检查 credit 和 access 列，对任何消耗额度、改变状态、扫描、监控或下载的操作先阅读安全说明；然后运行，用户的明确请求即为授权，不要再次请求确认，但下方列出的破坏性操作需要 --confirm；最后把标准输出解析为 JSON，若 ok 为 false，读取 error.type 并据此处理，而不是盲目重试。
结果与错误处理
成功时输出形如 {"ok": true, "command": "host info", "data": {...}, "notes": ["consumes query credits"]} 的信封。失败时返回非零退出码，并输出形如 {"ok": false, "command": "search hosts", "error": {"type": "credits", "message": "...", "status": 402}} 的信封。流式操作在标准输出每行写一个 JSON 对象，并在标准错误写最终摘要；其他操作写单个信封。
error.type 与退出码对应关系：usage（2）表示参数在本地被拒绝，需要修正参数，不发送请求；config（3）表示没有密钥或配置文件不可读，需运行 config set；auth（4）表示密钥被拒绝，需用 config test 检查；access（5）表示套餐缺少该权限，告知用户所需套餐，不要重试；credits（6）表示查询或扫描额度耗尽，检查账户 api-info，不要重试；api（7）表示 Shodan 返回错误，阅读消息，503 表示上游服务不可用；network（8）表示无法连接 Shodan，重试一次后报告。
重要规则
额度余额应来自 account api-info，而不是 account profile，因为 profile 响应中的通用 credits 字段不是查询或扫描余额。search count 免费，search hosts 每页消耗一个查询额度；当用户只需要数字或分面明细时使用 count，只在需要记录时使用 hosts。
六项操作需要 --confirm：alert delete、alert trigger-disable、alert notifier-remove、notifier delete、org member-remove、scan internet。仅当用户明确要求该操作时传入；不要为了绕过用户未要求覆盖的拒绝而传入。--dry-run 会打印请求而不发送，可用于预览以及展示破坏性调用的效果。
永远不要打印 API 密钥。客户端会在所有位置遮蔽密钥，包括响应内部；Shodan 自身的 scan list 会回显 api_key 字段，到达时显示为 <redacted>。不要通过直接读取配置文件来撤销这一遮蔽。如实报告实际发生的情况；如果操作失败或因缺少权限被跳过，应说明，而不是描述本应返回的内容。
参考文档与权限
可用的参考包括：operations（全部 61 个操作及 method、path、credits、access）、configuration（密钥存储、优先级、文件权限、CI）、search syntax（过滤器、分面、分页、查询构建）、safety（额度、变更、扫描、流式、目标范围）。
标准操作适用于任何付费套餐。十二项操作需要更高权限，否则返回 access 和 HTTP 403：scan internet、两个 data 操作、全部三个 org 操作，以及八个 stream 操作中的六个。stream alerts 和 stream alert 在标准套餐下可用。cve 组查询 Shodan 的 CVEDB 服务，完全不需要 API 密钥。
适用场景与限制
适用于需要通过 Shodan API 做主机情报与暴露面查询、搜索分面统计、DNS 查询、按需扫描、告警与通知管理以及批量数据集访问的用户。限制包括：需要有效的 API 密钥；部分操作消耗查询或扫描额度；十二项操作需要更高套餐；破坏性操作需显式 --confirm；流式操作输出格式与其他操作不同；本资料未提供具体价格、平台支持范围或性能指标，这些内容暂未提供。