mar0ls/shodan_go

# Shodan-Go CLI [](https://go.dev/doc/install) [](https://github.com/mar0ls/shodan_go/actions/workflows/build.yml) [](https://github.com/mar0ls/shodan_go/actions/workflows/test.yml) [](.golangci.yml) [](https://github.com/mar0ls/shodan_go/releases/latest) [](docs/DOCUMENTATION.md) 一个轻量级的 Go 语言命令行工具，用于查询 Shodan API。 [Go 1.25+](https://go.dev/doc/install) • [代码文档](docs/DOCUMENTATION.md) ## 概述 `shodan_go` 提供了一个小型、脚本友好的 CLI，支持： - 查询账户积分 - 查询单个主机信息 - 分页搜索主机 - 导出完整搜索结果为 JSON ## 主要功能 - 极简 CLI，包含两个核心命令：`host` 和 `search` - 支持上下文感知的 HTTP 客户端，包含 30 秒超时和取消功能 - API 密钥通过 `url.Values` 编码，绝不直接插入 URL 字符串 - API 密钥会从错误信息中剥离（`sanitizeErr` 会从 `*url.Error` 中移除它） - IP 路径使用 `url.PathEscape` 编码，防止 URL 注入 - 支持搜索分页（`--page`、``--all`） - JSON 导出时进行输出路径清理（`--out`） - 分页获取时自动重试，采用指数退避策略 - 通过 `golangci-lint` 支持代码检查和格式化 - 根据源码注释自动生成开发者文档 ## 环境要求 - Go `1.25` 或更高版本 - Shodan API 密钥 - 能够访问 `https://api.shodan.io` 的网络 ## 安装说明 ### 下载预编译二进制文件（推荐） 从 [GitHub Releases](https://github.com/mar0ls/shodan_go/releases/latest) 下载最新版本： ``` # Linux (amd64) tar -xzf shodan-go-linux-amd64.tar.gz ./shodan-go --help # macOS (Apple Silicon) tar -xzf shodan-go-macos-arm64.tar.gz ./shodan-go --help # Windows (amd64) — 解压 shodan-go-windows-amd64.zip ``` ### 从源码构建 ``` git clone https://github.com/mar0ls/shodan_go.git cd shodan_go go build -o shodan-go . ``` 在开发模式下直接运行： ``` go run . ``` ## 安全说明 客户端和 CLI 中内置了以下安全措施： | 关注点 | 缓解措施 | |---------|------------| | URL 中的 API 密钥 | 通过 `url.Values` 传递，绝不使用 `fmt.Sprintf` | | 错误信息中的 API 密钥 | `sanitizeErr` 在记录日志前从 `*url.Error` 中剥离密钥 | | IP 参数的 URL/路径注入 | 在嵌入 URL 路径前应用 `url.PathEscape` | | 输出文件路径遍历 | 使用 `filepath.Clean` + 双点遍历检查（绝对路径如 `/tmp/out.json` 允许使用）| | 长时间运行/挂起的请求 | 每个 HTTP 请求都使用 `context.Context` + 30 秒客户端超时 | | 源代码中的密钥 | `SHODAN_API_KEY` 仅从环境变量读取，绝不硬编码 | ## 配置 通过环境变量设置 API 密钥： ``` export SHODAN_API_KEY="your_api_key" ``` 如果未设置 `SHODAN_API_KEY`，CLI 将退出并报错。 ## 使用方法 通用格式： ``` ./shodan-go [options] ``` ### 命令 | 命令 | 描述 | |---|---| | `host ` | 显示一个主机 IP 的详细信息 | | `search [options] ` | 通过 Shodan 查询搜索主机 | ### 搜索选项 | 选项 | 描述 | |---|---| | `--page N` | 仅获取第 `N` 页（默认：`1`）| | `--all` | 获取所有页面（会消耗额外积分）| | `--out ` | 将完整 JSON 结果保存到文件（相对或绝对路径）| | `-h`, `--help` | 显示用法并退出 | ### 示例 ``` # Host lookup ./shodan-go host 8.8.8.8 # 搜索首页 ./shodan-go search "apache country:PL" # 搜索指定页 ./shodan-go search --page 3 "nginx country:DE" # 搜索所有页面并导出 JSON（相对路径） ./shodan-go search --all --out results.json "webcam country:PL" # 搜索所有页面并导出到绝对路径 ./shodan-go search --all --out /tmp/results.json "webcam country:PL" # 显示帮助 ./shodan-go --help # 从第 38 页恢复之前中断的搜索 ./shodan-go search --page 38 --all --out results.json "webcam country:PL" # 从结果 JSON 列出所有 IP 的示例 jq -r '.. | .ip_str? // empty' results.json | sort -u ``` ### 错误处理 使用 `--all` 获取多个页面时，CLI 会自动启用保护措施： - **速率限制延迟** — 页面请求之间暂停 1 秒，避免 API 限流。 - **退避重试** — 每个失败的页面最多重试 3 次，延迟递增（2 秒、4 秒、6 秒）。 - **保留部分结果** — 如果页面在所有重试后失败，已收集的结果会保留并正常输出（打印和/或使用 `--out` 保存）。 - **恢复提示** — 失败时 CLI 会打印页码，方便您稍后使用 `--page N --all` 继续。 ``例如：./shodan-go search --page 38 --all --out results.json "webcam country:PL"`` ## 测试 运行完整测试套件（包含竞态条件检测）： ``` go test -race ./... ``` 生成覆盖率报告： ``` go test -race -coverprofile=coverage.out ./... go tool cover -func=coverage.out # summary per function go tool cover -html=coverage.out # interactive HTML report ``` 当前覆盖率：约 77%（`shodan/api` 约 82%，`shodan` 主包约 75%）。 零覆盖率的项都是已弃用的别名包装器和 `main()` 入口点（需要有效的 API 密钥）。 ## 开发者工具 格式化、代码检查和生成文档： ``` # Lint + 格式检查（配置在 .golangci.yml 中） golangci-lint run -c ./.golangci.yml # 从源代码注释生成文档 ./scripts/generate_docs.py ``` ## 构建与分发 使用辅助脚本进行本地/跨平台构建。两个脚本都会自动解析项目根目录，因此您可以从任何工作目录运行它们。 ### POSIX (Linux/macOS) ``` # 本地构建 -> ./shodan-go ./scripts/build.sh # 跨平台构建示例 ./scripts/build.sh linux-amd64 ./scripts/build.sh macos-arm64 ./scripts/build.sh windows-amd64 # 自定义输出基础名称 ./scripts/build.sh local my-cli ``` ### PowerShell (Windows) ``` # 本地构建 -> .\shodan-go.exe ./scripts/build.ps1 # 跨平台构建示例 ./scripts/build.ps1 -Target linux-amd64 ./scripts/build.ps1 -Target windows-amd64 # 自定义输出基础名称 ./scripts/build.ps1 -Target local -Out shodan-go.exe ``` ## 项目结构 ``` . ├── .github/ │ └── workflows/ │ ├── build.yml # CI: build matrix (Linux/macOS/Windows) + cross-compile │ └── test.yml # CI: race tests, coverage upload, golangci-lint ├── api/ │ ├── shodan.go # Client struct, Option pattern, sanitizeErr │ ├── api.go # GetAPIInfo │ ├── host.go # SearchHosts, GetHostByIP, host types │ └── client_test.go # httptest-based API tests ├── docs/ # Auto-generated documentation ├── scripts/ # Build and docs generation helpers ├── main.go # CLI entrypoint (host / search commands) ├── main_test.go # Unit tests for CLI functions ├── .golangci.yml # Lint/formatter configuration └── go.mod ``` ## 文档 详细的代码级文档生成至： - [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) ## 贡献指南 欢迎提交 Issue 和 Pull Request。 请提供清晰的描述，并在提交更改前运行代码检查。

标签：API客户端, API集成, ESC4, EVTX分析, GitHub, Golanger, Go语言, JSON导出, OSINT, XSS, 主机侦察, 云存储安全, 互联网情报, 可观测性, 威胁情报, 实时处理, 密码管理, 开发者工具, 数据导出, 日志审计, 漏洞情报, 程序破解, 网络安全, 网络扫描, 隐私保护