liuweitao/shodan-skill
GitHub: liuweitao/shodan-skill
面向 Shodan API 的多平台 AI Agent 技能插件与命令行客户端，提供对 58 项官方操作的完整契约化覆盖。
Stars: 3 | Forks: 0
# Shodan Skill
一个非官方、以安全为重心的命令行客户端和通用 Agent Skill，适用于已文档化的 Shodan API。一个可移植的 `shodan-skill` 实现支持 OpenClaw、Codex、Claude Code 和 Hermes。
本项目不隶属于 Shodan，也不受其认可或赞助。Shodan 名称和服务引用仅用于描述 API 兼容性。
[English](README.md) | [中文](README_CN.md)
[完整文档](https://liuweitao.github.io/shodan-skill/) | [中文文档](https://liuweitao.github.io/shodan-skill/zh/)
双语用户手册包含面向任务的指南、命令参考、实践方案和故障排除。本 README 依然作为简明的项目和安装入口。
## 已验证范围
版本 2.0.0 映射并对 2026-07-27 从官方开发者文档中重新枚举出的全部 58 项操作进行了契约测试：
- 45 项 REST 操作，涵盖主机、搜索、DNS、扫描、告警、通知器、数据集、组织、账户和工具
- 8 项流式操作，包含 JSON Lines 和 SSE 处理
- 3 项趋势操作，路由至独立的趋势服务
- 2 项漏洞操作，路由至漏洞服务
版本 2.0.0 是继早期仅支持 OpenClaw 的 v1 版本之后的一次重大可移植性重写。安装、命令结构、输出、API 覆盖范围和安全行为均已更改；请将现有的工作流迁移至下文记录的分组 CLI。
已提交的[官方 API 快照](references/official-api-snapshot.yaml)记录了每项操作、来源 URL、检索日期以及标准化的文档哈希值。覆盖清单将每一项操作映射到唯一的 CLI 命令和一个收集到的 pytest 契约节点。默认测试套件是确定性的且完全离线：它不需要 API key、不消耗积分、不扫描目标、不打开实时流、不下载实时数据、也不修改账户。
原始的官方文档化 HTTP API 是权威标准。请参阅[覆盖清单](references/api-coverage.yaml)、[SDK 兼容性基线](references/sdk-baseline.md)以及明确排除的[仅 SDK 便捷路由](references/sdk-only.md)。响应字段引用可从[数据 schema](references/data-schemas.md) 链接查看，包括 Datapedia 的 banner schema 以及官方的漏洞和 Threatnet 事件规范。
## 安装与认证
需要 Python 3.10 或更高版本。
```
python -m pip install .
shodan-skill --version
shodan-skill --help
```
用于开发环境：
```
python -m pip install -e ".[dev]"
```
在环境中设置 API key：
```
export SHODAN_API_KEY="your-key"
```
PowerShell：
```
$env:SHODAN_API_KEY = "your-key"
```
CLI 还可以复用位于 `~/.shodan/api_key` 或 `~/.config/shodan/api_key` 的官方 Shodan CLI 配置；当两者同时存在时，传统路径优先。切勿将 key 放在源文件、提示词、测试夹具或可能被记录的命令参数中。
## 运行时控制
CLI 会特意忽略环境中的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `.netrc` 设置。这可以防止继承的代理意外接收到 Shodan 的查询认证。请仅通过 `SHODAN_PROXY` 或显式的根选项 `--proxy` 来配置代理。
| 环境变量 | 根选项 | 默认值 | 约束条件 |
|---|---|---:|---|
| `SHODAN_CONNECT_TIMEOUT` | `--connect-timeout` | 10 秒 | 有限正数 |
| `SHODAN_READ_TIMEOUT` | `--read-timeout` | 30 秒 | 有限正数 |
| `SHODAN_WRITE_TIMEOUT` | `--write-timeout` | 30 秒 | 有限正数 |
| `SHODAN_POOL_TIMEOUT` | `--pool-timeout` | 10 秒 | 有限正数 |
| `SHODAN_STREAM_TIMEOUT` | `--stream-timeout` | 60 秒 | 有限正数 |
| `SHODAN_RETRIES` | `--retries` | 2 | 0 到 5 的整数 |
| `SHODAN_PROXY` | `--proxy` | 禁用 | 绝对的 HTTP(S) 代理 URL |
| `SHODAN_SAFETY_MODE` | `--safety-mode` | `direct` | `direct` 或 `strict` |
根选项必须出现在命令组之前：
```
shodan-skill --read-timeout 45 --retries 1 host info 8.8.8.8
shodan-skill --proxy https://proxy.example:8443 search count "port:443"
```
当代理 URL 包含凭据时，首选 `SHODAN_PROXY` 而非命令参数，因为进程参数在 shell 历史记录或进程列表中可能可见。代理凭据和 API key 会在解析器失败、诊断、结果和异常输出中进行脱敏处理。
## 命令组
```
host Host information and history
search Host search, count, facets, filters, and tokens
scan Read scan metadata or submit scans
alert Alerts, triggers, ignored services, and attached notifiers
notifier Notification provider and notifier management
query Community saved-query directory
dns Domain history, resolve, and reverse lookup
tools HTTP headers and caller public IP
account Account profile, API plan, usage limits, and credit balances
stream Banners, ASN, countries, ports, CVEs, alerts, and custom feeds
trends Historical search, filters, and facets
exploits Exploit search and count
data Enterprise datasets, files, and verified downloads
org Enterprise organization information and membership
reference Local links to current filters, schemas, and Datapedia
```
使用 `shodan-skill account api-info` 查看 API 计划详情、使用限制以及剩余的查询或扫描积分。仅使用 `shodan-skill account profile` 查看成员资格和个人资料元数据；其通用的 `credits` 字段并不是 API 的查询或扫描积分余额。
示例：
```
shodan-skill host info 8.8.8.8
shodan-skill search hosts "product:nginx" --facets country:5
shodan-skill search count "port:443"
shodan-skill dns domain example.com --history
shodan-skill exploits search apache --page 2 --omit-code
shodan-skill stream ports 22,443 --limit 10
```
使用 `shodan-skill GROUP ACTION --help` 查看完整的参数契约。已弃用的下划线命令名仍作为兼容性别名保留，但会发出警告。
## 安全与账户要求
CLI 和 Skill 默认处于 `direct` 模式。在本地验证之后，显式命令或用户请求将直接执行，对于积分消耗、状态更改、下载、扫描或受监控网络无需二次确认。具有确定性预览的操作会将其写入 stderr 并立即继续。使用根级别的 `--dry-run` 可在不发送请求的情况下进行验证和预览。
设置 `SHODAN_SAFETY_MODE=strict` 或传递根级别的 `--safety-mode strict` 以恢复以前的确认行为。在 strict 模式下，请使用 `--confirm` 或 `--yes`；扫描和受监控网络还需要使用 `--acknowledge-authorization`。出于脚本兼容性考虑，现有的确认选项在 direct 模式下仍被接受。诸如 `--y`、`--conf` 和 `--ack` 之类的缩写依然会被拒绝。
搜索过滤器、额外的搜索页面、DNS 域名查找和扫描可能会根据 Shodan 的规则消耗积分。互联网扫描、全局/自定义流、趋势、数据集和组织操作需要适用的 Enterprise 授权。CLI 会将身份验证、授权、积分、超时、网络、API 和完整性失败映射到非零退出代码。已配置的 API key 不会导致运行未声明的操作。
消耗积分的 GET 请求不会自动重试，从而防止暂时性故障导致积分影响成倍增加。不消耗积分的 GET 请求保留有限重试和 `Retry-After` 处理。
数据集下载会以流式传输到 `.part` 文件，支持有限的 HTTP Range 恢复，默认验证大小和可用的 SHA-1 元数据，并在完成时不会覆盖下载过程中出现的目标文件。现有的部分和最终文件需要显式的 `--resume` 或 `--overwrite` 行为。
## 输出与退出代码
非流式 stdout 默认输出为稳定的 JSON 封包：
```
{
"ok": true,
"data": {},
"meta": {
"command": "host-info",
"credits_used": null,
"credit_impact": "none",
"credits_estimated": null
},
"error": null
}
```
`credit_impact` 是 `none`、`conditional`、`query`、`scan` 或 `unknown` 中的一种。`credits_estimated` 仅在 CLI 可以在请求前确定一个保守计数时才会被填充。向后兼容的 `credits_used` 字段保持为 `null`，因为 Shodan 响应不提供权威的单次请求使用量；它决不能被解释为零。
默认情况下，流会为每个 JSON Line 发出一个封包。`--stream-format sse` 请求官方的 SSE 表示形式，并将每个封包作为 SSE `data:` 事件发出。有限超时的流会禁用服务器心跳消息，因此安静的订阅源不会掩盖空闲超时。`--debug` 请求 Shodan 通过 `debug=1` 丢弃诊断信息；诊断信息和变更预览将输出到 stderr。在适用的地方选择 `--output json`、`--output jsonl` 或 `--output human`。
| 退出码 | 含义 |
|---:|---|
| 0 | 成功 |
| 2 | 用法或 strict 模式安全拦截 |
| 3 | 身份验证 |
| 4 | 授权或授权许可 |
| 5 | 积分 |
| 6 | 网络 |
| 7 | API、下载或完整性错误 |
| 8 | 超时 |
| 9 | 流或操作中断 |
| 10 | 意外的内部错误 |
API key、类似凭据的字段、bearer token、authorization header、cookie、通知器密钥、webhook URL 和签名 URL 凭据都会被递归脱敏。Shodan key 会在内部作为查询认证传递，但绝不会显示在 URL 中。
## 文档漂移与 schema
根据已提交的快照检查实时的官方文档：
```
python scripts/refresh_official_snapshot.py --check
```
此只读命令需要网络访问权限，但不会发送任何 Shodan API 请求。如果官方页面已做出有意更改，请在更新覆盖清单之前重新生成并审查清单：
```
python scripts/refresh_official_snapshot.py --write
python scripts/verify_coverage.py --require-complete
```
预定的 GitHub workflow 每周执行一次漂移检查。`shodan-skill reference datapedia` 也会返回指向 Datapedia 概览、banner JSON schema 和变更日志的直接链接，且不需要 key。
## Agent 平台包
从根目录的 `SKILL.md` 生成并验证每个适配器：
```
python scripts/build_bundles.py
python scripts/verify_skill.py
```
将生成的一个包安装到平台发现布局中：
```
python scripts/install_skill.py --platform codex
python scripts/install_skill.py --platform openclaw
python scripts/install_skill.py --platform claude-code
python scripts/install_skill.py --platform hermes
```
安装程序在替换现有安装之前会进行提示。仅在打算替换时才传递 `--yes`。请单独安装 CLI 包，以便 Agent 可以在不知道 Skill 目录的情况下调用 `shodan-skill`。
## 测试、安全与发布
强制的离线检查：
```
python -m pytest
python -m pytest --cov=shodan_skill --cov-report=term-missing --cov-fail-under=90
python -m ruff check .
python -m ruff format --check .
python -m mypy src/shodan_skill
python scripts/verify_coverage.py --require-complete
python scripts/verify_skill.py
python scripts/verify_manual.py
python scripts/verify_release.py
python -m build
```
在安装其锁定的依赖项后构建双语文档站点：
```
python -m pip install --requirement requirements-docs.txt
python -m mkdocs build --strict
```
覆盖验证器还会运行 `pytest --collect-only`，并拒绝缺少或重复使用特定操作契约节点的清单条目。GitHub CI 涵盖了在 Linux、Windows 和 macOS 上的 Python 3.10、3.12 和 3.14 版本。配置了 CodeQL、依赖项更新、官方文档漂移监控器、发布校验和、CycloneDX SBOM 和 GitHub 构建来源。请按照 [SECURITY.md](SECURITY.md) 中的说明私下报告漏洞。
CI 在 Linux 上运行一次完整的质量、覆盖率、包漂移和打包门禁，同时一个单独的矩阵在所有受支持的 Python 和操作系统组合上运行兼容性测试。推送诸如 `v2.0.0` 的版本标签会启动发布工作流；该工作流在创建或更新 GitHub Release 并附加已验证的产物之前，会验证标签和所有发布门禁。
实时验证默认处于禁用状态，需要明确的用户授权以及独立的环境变量和 pytest 门禁：
- `SHODAN_LIVE_TESTS=1` 和 `--allow-live-shodan` 用于授权的只读检查
- `--allow-shodan-credits` 用于消耗积分的检查
- `SHODAN_MUTATING_TESTS=1` 和 `--allow-shodan-mutations` 用于单独授权的变更操作
- `SHODAN_ENTERPRISE_TESTS=1` 用于拥有授权许可的 Enterprise 账户
- `SHODAN_TEST_TARGETS` 仅包含已授权的扫描或监控目标
任何环境变量、配置的 key 或测试标志本身都不会授权进行实时扫描、变更操作、流式传输、下载或消耗积分的请求。普通的 `python -m pytest` 会显式跳过所有真实 API 测试。
## 许可证
MIT
标签：API集成, GitHub, Shodan API, 可观测性, 威胁情报, 安全规则引擎, 实时处理, 密码管理, 开发者工具, 漏洞查询, 逆向工具