webamon-org/webamon-cli
GitHub: webamon-org/webamon-cli
一款命令行威胁情报搜索与狩猎工具，通过 Webamon API 提供大规模扫描语料检索、按需扫描、泄露凭证查询和钓鱼活动追踪能力。
Stars: 10 | Forks: 0
# Webamon Search CLI
**威胁情报界的 Google**
一个功能强大的 Webamon Search API 命令行界面。支持大规模网络搜索与威胁狩猎。返回无偏见、未过滤的结果。
**你能做什么：**
- 🔎 **搜索** —— 通过域名、IP、URL、哈希值或标签搜索扫描语料库 —— 或使用完整的 Lucene 查询
- 🛰️ **扫描** —— 按需扫描任意 URL，并获取报告或截图
- 🔑 **Infostealers** —— 按域名搜索被盗凭证
- 🎯 **Campaigns** —— 跟踪钓鱼/恶意软件资产：域名清单、变更历史、分析师标签和统计信息 *(Pro)*
- 📡 **Clusters** —— 新兴威胁雷达：自动检测到但尚未提升为 Campaigns 的指纹集群 *(Pro)*
- 📤 **导出** —— 将任何结果集导出为 JSON、CSV 或 Markdown 格式
## 安装
### 从 PyPI 安装
```
pip install webamon-cli
```
### 全局安装 (Linux/macOS)
**推荐：通过包管理器安装**
```
# Ubuntu/Debian
sudo apt update && sudo apt install pipx
pipx install webamon-cli
pipx ensurepath
# Fedora/CentOS/RHEL
sudo dnf install pipx
pipx install webamon-cli
pipx ensurepath
# macOS
brew install pipx
pipx install webamon-cli
pipx ensurepath
# Arch Linux
sudo pacman -S python-pipx
pipx install webamon-cli
pipx ensurepath
```
**备选：从源码安装**
如果你需要最新的开发版本，或者包管理器无法正常工作：
1. 首先安装 pipx：
```
# Ubuntu/Debian: sudo apt install pipx
# Fedora/CentOS: sudo dnf install pipx
# macOS: brew install pipx
# Arch: sudo pacman -S python-pipx
```
2. 克隆并安装：
```
git clone https://github.com/webamon-org/webamon-cli.git
cd webamon-cli
pipx install .
pipx ensurepath
```
**验证安装：**
```
# 测试安装
webamon --help
# 如果提示 command not found，请添加到 PATH：
export PATH="$HOME/.local/bin:$PATH"
# 然后重启你的终端或运行：
source ~/.bashrc # Linux
# 或
source ~/.zshrc # macOS
```
### 开发安装
用于开发工作：
```
git clone https://github.com/webamon-org/webamon-cli.git
cd webamon-cli
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
```
## 快速开始
**全局安装：**
```
# Ubuntu/Debian
sudo apt install pipx && pipx install webamon-cli
# Fedora/CentOS
sudo dnf install pipx && pipx install webamon-cli
# macOS
brew install pipx && pipx install webamon-cli
```
**🚀 立即开始搜索 —— 就是这么简单！**
使用显式的搜索命令：
```
webamon search example.com # Search for example.com
webamon search malware # Search for malware
webamon search nrd_20250801 # Search latest domain registrations
```
**其他命令：**
```
webamon search example.com # Explicit search command
webamon configure # Configure API key for pro features
webamon status # Test connection
webamon scan https://example.com # Scan a website
```
## 用法
### API Endpoints
**Webamon Search —— 威胁情报界的 Google**
CLI 会自动使用适当的 endpoint：
- **免费版**: `search.webamon.com`（无需 API 密钥）
- **Pro 版**: `pro.webamon.com`（需要 API 密钥）
### 配置
可以通过以下几种方式配置 CLI：
1. **交互式配置：**
```
webamon configure
```
2. **环境变量：**
```
export WEBAMON_API_KEY="your-api-key" # Optional, enables pro features
```
3. **命令行选项：**
```
webamon --api-key your-key search example.com domain.name
```
4. **配置文件：**
CLI 会在以下位置查找配置：
- `~/.webamon/config.json`
- 当前目录下的 `.webamon.json`
### 命令
#### Search
搜索 Webamon 威胁情报数据库：
```
# 搜索 domains、IPs、URLs 等：
webamon search example.com # Search for example.com
webamon search malware # Search for malware
webamon search 1.1.1.1 # Search for IP address
webamon search nrd_20250801 tag # Search in specific field
```
**工作原理：**
- `webamon search ` - 基础搜索
- `webamon search ` - 在特定字段中搜索
- `SEARCH_TERM`：你要搜索的内容（域名、IP、URL、哈希值等）
- `RESULTS`：以逗号分隔的搜索字段列表
- **默认搜索字段**：`page_title,domain.name,resolved_url,dom,tag`
- **自定义搜索字段**：指定你自己的字段列表
- `--fields`：以逗号分隔的返回字段列表（与搜索字段分开）
- **默认返回字段**：未指定时与搜索字段相同
💡 **在表格视图中，搜索匹配项会以黄色背景高亮显示。**
**示例：**
```
# 基本搜索
webamon search example.com
# 在特定 fields 中搜索
webamon search example.com domain.name,resolved_url
# 自定义返回 fields
webamon search example.com --fields page_title,domain.name
# 同时使用自定义搜索和返回 fields
webamon search example.com tag --fields page_title,domain.name
# 不同的输出格式
webamon search example.com --format json
webamon search example.com --format csv
# 导出结果
webamon search example.com --export results.json
webamon search example.com --format csv --export analysis.csv
```
**分页（仅限 Pro 用户）：**
```
# 使用默认 fields 限制结果
webamon search example.com --size 25
# 使用默认 fields 并利用 offset 进行分页
webamon search example.com --from 25 --size 25
# 结合自定义 fields 使用 offset
webamon search example.com domain.name,resolved_url --from 25 --size 25
# 使用默认 fields 跳过前 100 条结果
webamon search example.com --from 100 --size 50
# 浏览大型结果集
webamon search "*.bank.com" --from 0 --size 100
```
**Lucene 搜索：**
```
# 高级 Lucene 查询
webamon search --lucene 'domain.name:"bank*" AND scan_status:success' --index scans
# 指定要返回的 fields
webamon search --lucene 'domain.name:"example.com"' --index scans --fields domain.name,page_title
```
#### Scan
发起网站扫描：
```
# 扫描 domain
webamon scan example.com
# 扫描并自动获取 report
webamon scan example.com --fetch-report
# 扫描完整 URL
webamon scan https://example.com/login
# 获取 report 时使用 JSON 输出
webamon scan example.com --format json --fetch-report
```
#### Report
通过 ID 获取特定的扫描报告：
```
# 获取 report 详情（默认为 JSON 格式）
webamon report bf18c02d-ff0e-46a9-9a59-5b7b94fb27fb
# 使用 Table 格式以获得可读摘要
webamon report bf18c02d-ff0e-46a9-9a59-5b7b94fb27fb --format table
```
#### Infostealers
按域名搜索被盗凭证：
```
# 搜索泄露的凭证
webamon infostealers example.com
# 搜索带有连字符的 domain（自动加引号）
webamon infostealers bank-site.com
# 获取更多结果（Pro 用户）
webamon infostealers example.com --size 50
# 指定要返回的 fields
webamon infostealers example.com --fields domain,username,password
# JSON 输出
webamon infostealers example.com --format json
# CSV 输出（自动导出到文件）
webamon infostealers example.com --format csv
# 导出到自定义文件
webamon infostealers example.com --export compromised_creds
webamon infostealers example.com --format csv --export creds.csv
```
#### Screenshot
获取扫描截图：
```
# 获取 screenshot 信息
webamon screenshot bf18c02d-ff0e-46a9-9a59-5b7b94fb27fb
# 将 screenshot 保存到文件
webamon screenshot bf18c02d-ff0e-46a9-9a59-5b7b94fb27fb --save screenshot.png
```
#### Status
检查 API 连通性：
```
webamon status
```
#### Fields
发现可用的扫描字段：
```
# 显示所有可用的 fields
webamon fields
# 搜索特定的 fields
webamon fields --search domain
# 按类别显示 fields
webamon fields --category certificate
# 以简单列表形式获取 fields
webamon fields --search ip --format list
```
#### Campaigns
Campaign 情报 —— 跟踪的钓鱼和恶意软件分发资产，及其
域名清单、变更历史和分析师标签。
```
# 列出已追踪的 campaigns
webamon campaigns list
webamon campaigns list --search clickfix # free-text filter
webamon campaigns list --tag phishing # filter by analyst tag
webamon campaigns list --size 50 --from 50 # paginate
# 单个 campaign 的完整详情（通过 id 或确切名称）
webamon campaigns show 337271a6...
webamon campaigns show "ClickFix Fake-Cloudflare"
# 某个 campaign 的 Domain inventory
webamon campaigns domains 337271a6...
webamon campaigns domains 337271a6... --online true # live domains only
webamon campaigns domains 337271a6... --q login # substring filter
webamon campaigns domains 337271a6... --sort last_seen --order desc
webamon campaigns domains 337271a6... --since 2026-07-01 # date window
# Change history
webamon campaigns changes 337271a6... # one campaign
webamon campaigns changes # all campaigns (stream)
webamon campaigns changes --dim domains --since 2026-07-01 # only new domains
webamon campaigns changes 337271a6... --exclude-baseline
# 使用中的 Analyst tags，及其 campaign 计数
webamon campaigns tags
webamon campaigns tags --q click
# Estate 统计数据
webamon campaigns stats # global: domains, liveness, top TLDs
webamon campaigns stats 337271a6... # scoped to one campaign
```
| 子命令 | 功能说明 |
|---|---|
| `list` | 跟踪的 Campaigns，最新活动优先 |
| `show` | 完整展示单个 Campaign —— 种子查询、总数、样本 |
| `domains` | 分页显示域名清单，支持存活状态和日期筛选 |
| `changes` | 某个 Campaign 的变更历史，或全资产范围的流数据 |
| `tags` | 每个分析师标签及其关联的 Campaigns 数量 |
| `stats` | 域名计数、在线/离线划分、TLD 分布 |
所有列表类型的子命令均支持 `--format table|json` 和 `--export FILE`
（根据格式不同，可以是 `.json`、`.csv` 或 `.md`）。
#### Clusters
新兴 Clusters —— 检测器自动发现并分组的指纹集群，这些是
**尚未成为跟踪 Campaigns** 的对象。涵盖最新、50–1万个域名，已过滤
样板内容。它们是你的提升候选对象。
```
# Live radar（直接使用命令即可列出）
webamon clusters
webamon clusters list
# 按严重程度进行 Triage
webamon clusters list --severity critical
webamon clusters list --severity high --sort recent_7d
# 按 fingerprint 类型和 size band 过滤
webamon clusters list --type links --min-domains 1000
webamon clusters list --type ssl --max-domains 500
# Date windows
webamon clusters list --since 2026-07-19 --date-field first_seen
webamon clusters list --sort detected_at --include-stale
# 一次性枚举整个 live feed（最大 page size）
webamon clusters list --size 1000 --format json --export radar
# 按严重程度和 fingerprint 类型统计 Radar 总数
webamon clusters summary
# 查看单个 cluster 的完整信息 - 通过 cluster_id、fingerprint 或 prefix
webamon clusters show ssl:abc123def456
webamon clusters show abc123
# 仅获取 Lucene seed，以便进行提升
webamon clusters show abc123 --seed-only
```
**筛选条件** —— `--severity` (`critical`/`high`/`watch`)、`--type`
(`links`/`ssl`/`dom`/`asn`/`scripts`/`tech`/`domains`)、`--min-domains`、
`--max-domains`、`--since`/`--until`（配合 `--date-field`
(`first_seen`/`last_seen`/`detected_at`) 使用）、`--sort` (`unique_domains`、
`delta_24h`、`recent_7d`、`first_seen`、`last_seen`、`detected_at`、`severity`)、
`--order`、`--size` (默认 50，最大 1000)、`--from`、`--include-stale`。
表格视图会显示严重程度、指纹类型、域名数量、24小时和7天
增量、首次发现时间、样本诱饵，以及指纹 —— 底部还附带
严重程度分布。使用 `clusters show` 可查看完整对象，包括样本
域名、热门 TLD 和增长序列。
### 全局选项
- `--api-key`：覆盖 API 密钥
- `--config-file`：使用特定的配置文件
- `--verbose, -v`：启用详细输出模式
## 示例工作流
### 安全研究
```
# 搜索子 domains
webamon search "*.example.com"
# 扫描可疑 domains
webamon scan suspicious-domain.com
# 获取被标记站点的 screenshots
webamon screenshot --save evidence.png
```
### 域名情报
```
# 基本 domain 查询
webamon search example.com domain.name,resolved_url,page_title
# 使用 Lucene 进行高级搜索
webamon search --lucene 'domain.name:"example.com" AND scan_status:success' --index scans
# 批量 domain 分析
for domain in $(cat domains.txt); do
webamon search $domain >> results.json
done
```
### Campaign 分流 *(Pro)*
```
# 过去一天内整个 estate 中发生了什么变动？
webamon campaigns changes --since 2026-07-28
# 哪个 campaign 增长最快？然后深入了解。
webamon campaigns list --size 20
webamon campaigns show 337271a6...
webamon campaigns stats 337271a6...
# 获取 live domains 以便进行阻断
webamon campaigns domains 337271a6... --online true --size 1000 \
--format json --export blocklist
```
### 提升新兴 Cluster *(Pro)*
```
# 1. 检查 radar，优先查看最严重的
webamon clusters summary
webamon clusters list --severity critical --sort recent_7d
# 2. 检查候选项 - 示例 domains、TLDs、growth curve
webamon clusters show ssl:abc123def456
# 3. 获取其 seed 查询，将其提升为 tracked campaign
webamon clusters show abc123 --seed-only
# -> fingerprint.ssl:"abc123def456"
# 4. 为整个 radar 生成快照以用于报告
webamon clusters list --size 1000 --format json --export radar-$(date +%F)
```
## 配额与定价
### 免费版
- **每日 20 次 API 调用**
- **每次响应返回 10 条结果**
- 基础搜索功能
- 有限的 Infostealer 数据访问
### Pro 方案
当你达到每日配额时，CLI 会建议你升级到 Pro 以获取更广泛的访问权限：
- **创始分析师 (Founding Analyst)**：每日 1,000+ 次调用，每次响应最多 100 条结果
- **企业版 (Enterprise)**：每日 10,000+ 次调用，每次响应最多 500 条结果
- **所有方案**：完整的 Infostealer 数据访问、分页功能、优先支持
如需了解最新的定价和功能，请访问：https://webamon.com/pricing
如果你超出了配额，将会看到包含升级信息的友好错误提示。
## 配置文件格式
```
{
"api_key": "your-api-key-here",
"verbose": false
}
```
## 开发
### 搭建开发环境
```
# 克隆并安装
git clone https://github.com/webamon-org/webamon-cli.git
cd webamon-cli
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
```
### 构建
```
python -m build
```
## 卸载
### 全局安装卸载
```
pipx uninstall webamon-cli
```
### PyPI 安装卸载
```
pip uninstall webamon-cli
```
### 开发安装卸载
```
# 如果使用 pip install -e . 安装
pip uninstall webamon-cli
# 删除 repository
rm -rf webamon-cli
```
## 许可证
Apache License 2.0
Copyright 2025 Webamon
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
```
http://www.apache.org/licenses/LICENSE-2.0
```
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
## 贡献
我们欢迎你的贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细的指南，包括：
- 搭建开发环境
- 代码风格和测试要求
- 提交 Bug 报告和功能请求
- Pull Request 流程和代码审查
快速开始：Fork → 分支 → 编码 → 测试 → Pull Request
## 安全
安全对我们至关重要。请查阅 [SECURITY.md](SECURITY.md) 了解：
- 报告安全漏洞
- 用户安全最佳实践
- API 密钥和数据保护指南
- 事件响应流程
标签：Blue Team, GitHub, Python, 威胁情报, 开发者工具, 数据泄露, 文档结构分析, 无后门, 逆向工具