wpscanner/wpsec-cli
GitHub: wpscanner/wpsec-cli
WPSec WordPress 安全扫描服务的命令行客户端,用于从终端管理站点监控和安全报告。
Stars: 13 | Forks: 1
 
# WPSec.com 命令行客户端
一个用于 WPSec WordPress 安全扫描服务的强大命令行界面。从终端管理您的站点、运行安全报告并监控您的 WordPress 安装。API 文档可以在[这里](https://api.wpsec.com/api/documentation)找到,在 WPSec.com 需要 Premium 账户。
```
__ __ ___ __ ___ ___ __
\ V V / '_ (_- -_) _|
\_/\_/| .__/__/\___\__|
|_|
```
## ✨ 功能
- 🚀 **快速 API 集成** - 直接连接到 WPSec 的安全扫描 API
- 🌐 **站点管理** - 添加并列出用于监控的 WordPress 站点
- 📊 **报告管理** - 查看 JSON 输出的详细安全报告
- 🏓 **健康监控** - Ping API endpoint 以检查服务状态
- 🎨 **彩色输出** - 带有 emoji 和颜色的漂亮终端输出
- 🔄 **重试逻辑** - 带有自动重试的稳健错误处理
- 🐛 **Debug 模式** - 用于故障排除的详细日志记录
- 📁 **文件输出** - 将报告保存到文件以供进一步分析
## 📋 环境要求
- Python 3.6 或更高版本
- `requests` 库
- `colorama`(可选,用于彩色输出)
### 安装
```
# 克隆 repository
git clone https://github.com/wpscanner/wpsec-cli.git
cd wpsec-cli
# 安装 dependencies
pip install -r requirements.txt
```
**替代方案:下载单文件**
```
# 仅下载 Python 脚本
wget https://raw.githubusercontent.com/wpscanner/wpsec-cli/main/wpsec-cli.py
# 手动安装 dependencies
pip install requests colorama
```
### 使用 Docker 安装
您也可以使用命令行工具的 Docker 版本:
```
docker pull docker.io/jonaslejon/wpsec-cli:latest
```
### 基本用法
```
# 检查 API 状态
python wpsec-cli.py CLIENT_ID CLIENT_SECRET ping
# 列出所有站点
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_sites
# 添加新站点
python wpsec-cli.py CLIENT_ID CLIENT_SECRET add_site "My WordPress Site" "https://example.com"
# 移除站点(通过 ID,来自 get_sites)
python wpsec-cli.py CLIENT_ID CLIENT_SECRET delete_site SITE_ID
# 列出安全报告
python wpsec-cli.py CLIENT_ID CLIENT_SECRET list_reports
# 获取特定报告
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_report REPORT_ID
```
### 配合 Docker 使用
在此处阅读更多信息:https://hub.docker.com/r/jonaslejon/wpsec-cli
```
# 使用 docker
docker run --rm jonaslejon/wpsec-cli:latest CLIENT_ID CLIENT_SECRET ping
```
## 📋 环境要求
- Python 3.6 或更高版本
- `requests` 库
- `colorama`(可选,用于彩色输出)
安装依赖项:
```
pip install requests colorama
```
## 🔧 命令参考
### 全局选项
| 选项 | 简写 | 描述 |
|--------|-------|-------------|
| `--debug` | `-d` | 启用 debug 输出 |
| `--quiet` | `-q` | 最简输出模式 |
| `--stage` | | 使用 staging API 环境 |
| `--api-url` | `-u` | 覆盖 API 基础 URL |
| `--version` | `-v` | 显示版本信息 |
### 命令
#### `ping` (别名: `p`)
检查 WPSec API 是否有响应。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET ping
```
#### `get_sites` (别名: `gs`, `sites`)
列出您账户中的所有 WordPress 站点。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_sites
```
#### `add_site` (别名: `as`, `add`)
添加一个新的 WordPress 站点进行监控。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET add_site "Site Title" "https://example.com"
```
**参数:**
- `title` - 站点的描述性名称
- `url` - 包含 http:// 或 https:// 的完整 URL
#### `delete_site` (别名: `ds`, `del`)
从您的账户中移除一个 WordPress 站点。这是服务器上的软删除(站点将被隐藏并停止扫描;其扫描历史记录将被保留)。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET delete_site SITE_ID
```
**参数:**
- `site_id` - 数字站点 ID(通过 `get_sites` 获取)
#### `list_reports` (别名: `lr`, `reports`)
列出带有分页的安全报告。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET list_reports --page 1
```
**选项:**
- `--page`, `-p` - 页码(默认:1)
#### `get_report` (别名: `gr`, `report`)
检索特定的安全报告。
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_report REPORT_ID
```
**选项:**
- `--output`, `-o` - 保存到文件而不是 stdout
**参数:**
- `report_id` - 32 个字符的十六进制报告标识符
将 CLIENT_ID、CLIENT_SECRET 和 REPORT_ID 替换为适当的值。
## 🔐 配置
您需要提供 client_id 和 client_secret 作为命令行参数。Rest JSON API 密钥(CLIENT_ID 和 CLIENT_SECRET)可以在这里获取:https://wpsec.com/account/api.php
您将需要 WPSec 账户中的 API 凭证:
1. 登录您的 WPSec 仪表板
2. 导航到 API 设置:https://wpsec.com/account/api.php
3. 生成新的 Client ID 和 Client Secret
4. 在每个命令中使用这些凭证
### 环境变量(可选)
通过环境变量设置 debug 模式:
```
export WPSEC_DEBUG=1
python wpsec.py CLIENT_ID CLIENT_SECRET ping
```
## 📊 输出格式
### 标准输出
带有颜色和 emoji 的美观格式化表格:
```
✅ WPSec API is up and running \o/. Response time: 0.23 seconds
🌐 Listing 3 sites below:
ID Title URL
-- ----- ---
123 My WordPress Site https://example.com
124 Blog Site https://blog.example.com
125 Shop Site https://shop.example.com
✅ Total sites: 3
```
### 安静模式
用于脚本编写的制表符分隔值:
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_sites --quiet
123 My WordPress Site https://example.com
124 Blog Site https://blog.example.com
125 Shop Site https://shop.example.com
```
### JSON 输出
报告以格式化的 JSON 输出:
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET get_report REPORT_ID --output report.json
```
## 🐳 构建 Docker 镜像
只需运行:
```
docker build -t jonaslejon/wpsec-cli:0.5.0 -t jonaslejon/wpsec-cli:latest .
```
构建包含 SBOM:
```
DOCKER_BUILDKIT=1 docker build --attest type=sbom --attest type=provenance -t jonaslejon/wpsec-cli:0.5.0 -t jonaslejon/wpsec-cli:latest .
```
## 🛠️ 高级用法
### 与脚本配合使用
```
#!/bin/bash
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
# 检查 API 是否可用
if python wpsec-cli.py $CLIENT_ID $CLIENT_SECRET ping --quiet | grep -q "up"; then
echo "API is healthy, proceeding..."
# Add your automation logic here
else
echo "API is down, aborting"
exit 1
fi
```
### 批量操作
```
# 添加多个站点
sites=(
"Site 1,https://site1.com"
"Site 2,https://site2.com"
"Site 3,https://site3.com"
)
for site in "${sites[@]}"; do
IFS=',' read -r title url <<< "$site"
python wpsec-cli.py CLIENT_ID CLIENT_SECRET add_site "$title" "$url"
done
```
### 使用 Staging 环境
```
# 针对 staging API 进行测试
python wpsec-cli.py CLIENT_ID CLIENT_SECRET --stage ping
# 或使用自定义 API URL
python wpsec-cli.py CLIENT_ID CLIENT_SECRET --api-url "https://custom-api.example.com" ping
```
## 🐛 故障排除
### 常见问题
**身份验证失败**
```
🔐 Error: Client authentication failed, invalid client ID or client secret.
```
- 确认您的凭证是否正确
- 检查凭证是否已过期
- 确保您使用了正确的 API 环境
**无效的 URL 格式**
```
🌐 Error: Invalid URL format: example.com
```
- URL 必须包含 `http://` 或 `https://`
- 例如:`https://example.com` 而不是 `example.com`
**API 超时**
```
⏱️ Error: WPSec API timeout. Please try again later.
```
- 检查您的网络连接
- 尝试使用 `--debug` 标志获取更多详细信息
- 考虑使用 staging 环境进行测试
### Debug 模式
启用详细日志记录:
```
python wpsec-cli.py CLIENT_ID CLIENT_SECRET --debug ping
```
这将显示:
- HTTP 请求/响应详细信息
- 身份验证 token(部分掩码)
- API 响应时间
- 错误堆栈跟踪
### 获取帮助
- 首先检查 debug 输出:`--debug`
- 验证 API 状态:`ping` 命令
- 联系支持:support@wpsec.com
## 🔄 错误处理
CLI 包含稳健的错误处理机制:
- **自动重试** - 失败的请求将以指数退避机制进行重试
- **速率限制** - 优雅地处理 429 响应
- **网络问题** - 检测连接问题和超时
- **验证** - 对 URL、ID 和参数进行输入验证
- **有用的提示信息** - 清晰的错误描述并建议修复方法
## 📈 性能
- **会话复用** - 为提高效率而复用 HTTP 连接
- **重试策略** - 针对临时性故障的智能重试逻辑
- **超时处理** - 可配置的超时设置防止程序挂起
- **响应验证** - 验证 API 响应以确保可靠性
## 📝 待办事项
- _站点移除功能已加入 v0.6.0 版本(`delete_site`)。_
## 🤝 贡献
1. Fork 此仓库
2. 创建一个功能分支:`git checkout -b feature-name`
3. 进行您的更改
4. 如果适用,添加测试
5. 提交一个 pull request
### 开发环境设置
```
git clone https://github.com/wpscanner/wpsec-cli.git
cd wpsec-cli
# 安装开发 dependencies
pip install -r requirements.txt
# 运行测试
python -m pytest tests/
# 运行 linting
flake8 wpsec-cli.py
```
## 📄 许可证
该项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 🔗 链接
- [WPSec 官网](https://wpsec.com)
- [API 文档](https://api.wpsec.com/api/documentation)
- [Docker Hub](https://hub.docker.com/r/jonaslejon/wpsec-cli)
- [技术支持](mailto:support@wpsec.com)
- [GitHub Issues](https://github.com/wpscanner/wpsec-cli/issues)
## 📊 版本历史
### v0.6.0(当前版本)
- 添加了 `delete_site` 命令以移除站点(别名:`ds`、`del`)
- `get_sites` 现在显示真实的站点 URL(API 现已返回该数据)
- 在重复执行 `add_site` 时提供更友好的“站点已存在”提示
### v0.5.0
- 添加了带有 emoji 的彩色输出
- 改进了错误处理和验证
- 添加了 debug 模式和安静模式
- 增强了报告分页功能
- 更好的 URL 验证
- 添加了报告的文件输出功能
由 WPSec 团队用 ❤️ 制作
标签:Docker, Python, WordPress, 主机安全, 安全防御评估, 无后门, 请求拦截, 逆向工具