thaikolja/checkwp

# 检查WP CheckWP 是一款面向 WordPress 插件的离线优先安全扫描器。它可以扫描插件目录和 `.zip` 压缩包，以检测恶意软件、后门、不安全的代码模式以及常见的漏洞类别，例如远程代码执行、SQL 注入、跨站脚本攻击 (XSS)、CSRF、不安全的文件上传以及权限问题。 AI 验证是可选的。扫描器只有在提供 `--ai-key` 时才会启用 AI 支持。 ## CheckWP 的功能 - 扫描插件目录和插件 ZIP 压缩包 - 在扫描前验证 WordPress 插件的结构 - 检测 PHP 和 JavaScript 恶意软件特征 - 发现插件代码中常见的安全缺陷 - 生成 HTML、JSON、Markdown 和 PDF 报告 - 通过 `checkwp-api` 提供 FastAPI 服务 - 包含用于本地验证的 `mock-malicious-plugin/` ## 为什么离线模式很重要 默认扫描旨在即使不调用任何外部 API 也能发挥作用。它结合了： 1. 基于特征的检测 2. 全文件正则表达式匹配 3. 上下文感知的误报检查 4. 针对代码混淆和恶意载荷执行的复合恶意软件启发式分析 这提高了对后门和可疑载荷的检测能力，即使在不使用 AI 的情况下也是如此。 ## 工作原理 | 阶段 | 具体内容 | |--------------------------|----------------------------------------------------------------------------------------------------| | 输入验证 | CheckWP 接受一个插件文件夹或 ZIP 压缩包，并验证其是否符合 WordPress 插件的特征 | | 安全解压 | ZIP 压缩包在提取时会采取路径遍历和符号链接保护措施 | | 文件发现 | 根据扩展名、大小和排除的文件夹对文件进行过滤 | | 离线扫描 | 对完整文件内容应用特征库和启发式规则 | | 可选的 AI 验证 | 如果提供了 `--ai-key`，则可以通过与 OpenAI 兼容的端点对发现的问题进行复查 | | 报告生成 | 结果将被输出为 HTML、JSON、Markdown 和 PDF 格式 | ## 检测覆盖范围 | 类别 | 示例 | |-----------------------|------------------------------------------------------------------------------------------| | 远程代码执行 | `eval()`、`assert()`、`create_function()`、可变函数执行 | | 命令注入 | `system()`、`exec()`、`passthru()`、`shell_exec()`、`popen()` | | SQL 注入 | 不安全的 `$wpdb` 查询以及 SQL 中的原生超全局变量 | | XSS | 未转义的输出、`innerHTML`、`document.write()` | | CSRF | 缺少 nonce 验证的表单和 AJAX 处理程序 | | 文件问题 | 动态 include/require、不安全的文件读取、不安全的文件上传 | | 反序列化 | 对用户可控输入使用 `unserialize()` | | 授权 | 公开的 REST 路由、薄弱的权限检查 | | 恶意软件特征 | `eval(base64_decode())`、编码后的恶意载荷、数据窃取、隐藏管理员账户创建、盗刷脚本 | | 混淆 | `chr()` 链式调用、`String.fromCharCode()`、过长的编码块、熵值激增 | ## 安装说明 ### pipx ``` pipx install checkwp ``` ### PyPI / pip ``` pip install checkwp ``` ### Homebrew ``` brew tap thaikolja/checkwp brew install checkwp ``` ### 本地开发安装 ``` git clone https://gitlab.com/thaikolja/checkwp.git cd checkwp python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ## 快速入门 ``` checkwp ./my-plugin checkwp ./my-plugin.zip checkwp ./my-plugin --deep -o report.html --no-open checkwp ./mock-malicious-plugin --deep --no-open ``` ## CLI 用法 ``` checkwp [options] ``` ### 核心选项 | 选项 | 描述 | |---------------------------------------------|-----------------------------------------------------------| | `-o, --output PATH` | 输出文件路径 | | `-f, --format {html,json}` | 报告格式 | | `--stdout` | 将报告打印到标准输出 | | `--no-open` | 不自动打开 HTML 报告 | | `-s, --severity {critical,high,medium,low}` | 最低报告严重程度 | | `--deep` | 启用更深入的离线启发式规则和基于熵的检查 | | `--quick` | 将输出限制为高和严重级别的发现项 | | `-t, --threads N` | 工作线程数量 | | `--max-file-size KB` | 要扫描的最大文件大小 | | `--context-lines N` | 要包含在发现项周围的上下文行数 | | `--exclude NAME` | 排除某个目录名称；可重复使用 | | `--include-ext EXT` | 添加额外的文件扩展名；可重复使用 | | `--php-only` | 仅扫描类 PHP 文件 | | `--js-only` | 仅扫描类 JavaScript / TypeScript 文件 | | `--no-banner` | 隐藏启动横幅 | | `--no-color` | 禁用彩色输出 | | `-V, --version` | 显示版本号 | ### AI 选项 | 选项 | 描述 | |--------------------------|-------------------------------------------------------------------| | `--ai-key KEY` | 启用 AI 验证 | | `--ai-endpoint URL` | 与 OpenAI 兼容的 Base URL。如果省略，则默认使用 OpenAI | | `--ai-model MODEL` | 用于 AI 验证的模型名称 | | `--ai-temperature FLOAT` | 采样温度 | 重要提示： - `--ai-endpoint` 仅接受完整的与 OpenAI 兼容的 URL - 不使用任何提供商别名 - 如果省略 `--ai-endpoint`，CheckWP 将使用 `https://api.openai.com/v1` ### AI 示例 OpenAI： ``` checkwp ./my-plugin \ --ai-key "sk-..." \ --ai-model "gpt-4o" ``` 使用显式 OpenAI 兼容 URL 的 DeepSeek： ``` checkwp ./my-plugin \ --ai-key "sk-..." \ --ai-endpoint "https://api.deepseek.com/v1" \ --ai-model "deepseek-chat" ``` 通用的 OpenAI 兼容端点： ``` checkwp ./my-plugin \ --ai-key "token" \ --ai-endpoint "https://example.com/v1" \ --ai-model "my-model" ``` ## API 用法 在本地启动 API： ``` checkwp-api ``` 默认本地地址： - `http://127.0.0.1:8000` ### API 端点 | 方法 | 端点 | 用途 | |--------|-----------------------------|------------------------------| | `GET` | `/` | 服务索引 | | `GET` | `/health` | 健康检查 | | `GET` | `/version` | API 版本 | | `POST` | `/scan` | 上传并扫描一个插件 ZIP | | `GET` | `/static/reports/{id}.html` | 访问已保存的 HTML 报告 | ### 常见的 OpenAI 兼容端点 URL | 提供商 | 用于 `--ai-endpoint` 或 `ai_endpoint` 的 Base URL | |------------|-----------------------------------------------| | OpenAI | `https://api.openai.com/v1` | | DeepSeek | `https://api.deepseek.com/v1` | | OpenRouter | `https://openrouter.ai/api/v1` | | Groq | `https://api.groq.com/openai/v1` | | Together | `https://api.together.xyz/v1` | ### 上传并扫描 ZIP ``` curl -X POST "http://127.0.0.1:8000/scan?format=json" \ -F "file=@./my-plugin.zip" ``` ### 上传并使用 AI 验证进行扫描 ``` curl -X POST "http://127.0.0.1:8000/scan?format=json&ai_key=sk-...&ai_endpoint=https://api.deepseek.com/v1&ai_model=deepseek-chat" \ -F "file=@./my-plugin.zip" ``` ## 报告 | 格式 | 用例 | |----------|--------------------------------------------------| | HTML | 人工审查、分享以及基于浏览器的分类评估 | | JSON | CI/CD、脚本编写和自动化 | | Markdown | 轻量级文本报告 | | PDF | 便携式报告移交 | 当生成 HTML 输出时，CheckWP 还会写入配套的 `.md` 和 `.pdf` 文件。 ## 用于验证的模拟插件 代码库中包含 `mock-malicious-plugin/`，这是一个故意留下漏洞的示例插件，包含： - SQL 注入 - XSS - 不安全的重定向 - 不安全的文件上传 - 公开的 REST 路由 - 隐藏管理员创建 - 混淆的 PHP 恶意载荷 - 可疑的 JavaScript 恶意载荷 在本地运行它以验证检测质量： ``` checkwp ./mock-malicious-plugin --deep --no-open ``` ## 开发 ``` pytest ruff check . mypy src/ python -m build ``` ## 发布 ### PyPI ``` python -m build python -m twine check dist/* python -m twine upload dist/* ``` ### pipx 发布到 PyPI 之后： ``` pipx install checkwp ``` ### Homebrew 使用已发布的 PyPI 源码压缩包的 SHA256 值更新 `homebrew/checkwp.rb`。 相关文件： - `homebrew/HOMEBREW.md` - `.github/workflows/release.yml` ## 作者 | 字段 | 值 | |---------------|----------------------------------------| | 姓名 | Kolja Nolte | | 网站 | `https://checkwp.org` | | 邮箱 | `kolja.nolte@gmail.com` | | GitLab | `https://gitlab.com/thaikolja/checkwp` | | GitHub 镜像 | `https://github.com/thaikolja/checkwp` | ## 许可证 MIT。请参阅 `LICENSE`。

标签：AV绕过, CISA项目, CLI, CSRF, FastAPI, Go语言工具, PDF报告生成, Petitpotam, PHP安全, SEO安全扫描, SQL注入检测, Web安全, WiFi技术, WordPress安全, XSS检测, ZIP解压安全, ZIP路径穿越防护, 人工智能辅助检测, 代码安全审计, 后门检测, 启发式分析, 威胁情报, 安全合规, 开发者工具, 恶意广告软件检测, 提示词注入, 插件扫描器, 操作系统监控, 攻击路径可视化, 正则表达式匹配, 特征码检测, 离线扫描, 符号链接防护, 网站安全检测, 网络代理, 自定义DNS解析器, 蓝队分析, 跨站脚本攻击, 远程代码执行检测, 逆向工具, 错误基检测, 静态代码分析, 黑客工具