WPScan 仓库开发指南：面向 AI Agent 的架构解析、测试与构建实践

网络安全漏洞扫描渗透测试应用安全CLI【免费下载链接】wpscanWPScan WordPress security scanner. Written for security professionals and blog maintainers to test the security of their WordPress websites. Contact us via contactwpscan.com项目地址https://gitcode.com/gh_mirrors/wp/wpscan点击查看免费下载本文以仓库根目录的 AGENTS.md 为骨架面向需要在 WPScan 仓库中开发、调试与测试的 AI 编码 Agent 与 Ruby 开发者系统梳理项目的架构分层、控制器链、Finders/Models 设计、开发命令、测试规范与 WPScan API 集成细节。读完本文你将掌握如何在该仓库中安全地修改代码、运行测试、构建 Gem、本地启动扫描并理解动态 Finders、Slug 分类、API 请求追踪等核心机制在源码中的真实实现。项目概览WPScan 是什么WPScan 是一个用 Ruby 编写的 WordPress 安全扫描器面向安全从业者与博客维护者用于检测 WordPress 站点的漏洞、枚举资产并执行口令攻击。根据 AGENTS.md 与 wpscan.gemspec它具备以下关键特征Ruby Gem CLI 工具wpscan.gemspec中声明了可执行文件wpscan要求 Ruby 版本 3.3依赖activesupport、typhoeus、nokogiri等核心库MVC 式架构由 Controllers编排、Finders检测策略、Models领域对象三层构成本地数据库驱动漏洞与指纹数据存放在本地$XDG_CACHE_HOME/wpscan/db、~/.cache/wpscan/db或旧版~/.wpscan/db并通过wpscan --update与 WPScan API 同步扫描框架与 WordPress 专用代码共存通用扫描框架位于lib/wpscan/Target、Browser、Controller::Base、Scan、Finders、Formatter 等WordPress 特定行为通过模块混入mixin实现例如WPScan::Target::Platform::WordPress被 include 进WPScan::Target见 lib/wpscan/target.rb。环境搭建与开发命令安装依赖bundle install运行测试AGENTS.md 给出了完整的测试命令矩阵# 运行除慢测试外的全部测试PR 默认 bundle exec rspec --tag ~slow # 运行完整测试套件含慢测试仅在 master 分支运行 bundle exec rspec # 运行指定测试文件 bundle exec rspec spec/path/to/file_spec.rb # 覆盖率默认开启通过 .simplecov 配置 bundle exec rspec从 Rakefile 可以看到rake spec任务本身也预设了--tag ~slow与 PR 场景保持一致完整套件只在 master 上执行。代码质量检查RuboCop项目使用 RuboCop 强制 Ruby 代码风格配置见根目录.rubocop.yml# 运行 rubocop bundle exec rubocop # 自动修复 bundle exec rubocop -a # 仅对正在修改的文件执行推荐 bundle exec rubocop -a path/to/file1.rb path/to/file2.rbAGENTS.md 特别强调每次修改代码后必须运行 rubocop这是合入 PR 的前置条件。构建 Gem# 构建 gem会自动执行 rubocop 与 rspec bundle exec rake build # 本地安装 gem install pkg/wpscan-*.gemRakefile 中的实现印证了这一点task build: exec而exec数组在安装了rubocop/rake_task与rspec/core/rake_task时分别追加:rubocop与:spec——即构建前强制质量门禁。本地运行 WPScan# 从源码运行在 git 仓库外执行避免加载路径冲突 ruby -Ilib bin/wpscan --url https://example.com # 或安装为 gem 后直接运行 wpscan --url https://example.com数据库操作# 更新本地数据库 wpscan --update数据库默认存放位置见 lib/wpscan.rb 的实现逻辑若旧版路径~/.wpscan/db存在则沿用否则使用$XDG_CACHE_HOME/wpscan/db未设置XDG_CACHE_HOME时回落到~/.cache/wpscan/db。测试套件则通过redefine_constant将DB_DIR覆盖为spec/fixtures/db/避免污染真实缓存。架构深度解析入口点bin/wpscan 与控制器链CLI 入口为 bin/wpscan其核心逻辑是用操作符把各控制器串成链条再调用s.runWPScan::Scan.new do |s| s.controllers WPScan::Controller::VulnApi.new WPScan::Controller::CustomDirectories.new WPScan::Controller::InterestingFindings.new WPScan::Controller::WpVersion.new WPScan::Controller::AuthenticatedInventory.new WPScan::Controller::MainTheme.new WPScan::Controller::Enumeration.new WPScan::Controller::PasswordAttack.new WPScan::Controller::Aliases.new s.run end各控制器职责如下控制器职责VulnApi漏洞数据所需的 API Token 设置CustomDirectories自定义 wp-content/plugins 目录检测InterestingFindings响应头分析、robots.txt、readme 文件等WpVersionWordPress 版本检测AuthenticatedInventory已认证资产盘点登录态下可枚举的信息MainTheme当前启用主题检测Enumeration插件、主题、用户等枚举见 CLI 选项PasswordAttack暴力破解攻击Aliases处理遗留 CLI 选项注意Core控制器并非显式加入链中而是由 lib/wpscan/scan.rb 的Scan#initialize通过controllers WPScan::Controller::Core.new隐式插入链首在before_scan阶段负责 Banner 展示、数据库更新、WordPress 站点识别与目标可用性检查。从 app/controllers/core.rb 可以看到before_scan依次执行输出 banner/help/version → 校验 API Token 冲突 → 按需更新数据库 → 设置 HTTP 缓存 → 检查目标可达性 → 加载服务器模块 → 确认站点是否为 WordPress。扫描编排Scan 与 Controllerslib/wpscan/scan.rb 是扫描编排的核心Scan#initialize记录起始内存、捕获并脱敏命令行参数mask_sensitive_arguments会隐藏--api-token、--http-auth、--proxy-auth、--cookie-string、--wp-auth、--enterprise-db-token等敏感值防止日志泄露密钥Scan#run在ensure块中保证即使出错也会 abort 未完成的请求并逆序执行after_scan见 lib/wpscan/controllers.rb确保统计信息在任何情况下都能输出exit_hook根据扫描结果返回进程退出码检测到漏洞时退出VULNERABLE否则OK参数错误、中断、标准错误分别映射到不同的WPScan::ExitCode常量lib/wpscan/scan.rb。Finders检测策略层Finders 位于app/finders/为各类 WordPress 组件实现多种检测策略passive / aggressive / mixed。AGENTS.md 列出的主要 Finder 类型与仓库目录一一对应WpVersion— 版本检测app/finders/wp_version/含 RSS/Atom generator、readme、唯一指纹等策略MainTheme— 活动主题检测app/finders/main_theme/含首页/404 页 CSS 样式与 URL 匹配Plugins/Themes— 插件、主题枚举app/finders/plugins/、app/finders/themes/含已知位置、首页/404 页 URL、WP JSON API 等策略Users— 用户枚举app/finders/users/含作者 ID 暴力枚举、oEmbed/RSS/WP JSON API、Yoast SEO 作者站点地图等InterestingFindings— 备份文件、调试日志、XML-RPC、robots.txt 等app/finders/interesting_findings/ConfigBackups/DbExports/Medias/Timthumbs— wp-config 备份、数据库导出、附件暴力枚举、Timthumb 脚本检测app/finders/config_backups/等Passwords— 登录认证机制app/finders/passwords/含 wp-login 与 XML-RPC。扫描框架侧lib/wpscan/finders/提供了UniqueFinder、SameTypeFinder、IndependentFinder等抽象基类分别对应每个组件只匹配一个结果、同类多策略聚合与独立无依赖检测三种模式WordPress 专用 Finder 通过继承这些基类获得通用能力。Models领域对象层app/models/定义了扫描中涉及的领域模型WpItem— 插件/主题的基类app/models/wp_item.rbPlugin、Theme— 具体 WordPress 组件WpVersion— 携带漏洞信息的 WordPress 版本InterestingFinding及其子类ConfigBackup、DbExport、Media、Timthumb、XMLRPC、Headers、RobotsTxt等。模型还负责调用 WPScan API 获取漏洞数据WpVersion#vulnerabilities等逻辑最终路由到WPScan::DB::VulnApi并受VulnerabilityFilter的过滤逻辑约束。数据库层lib/wpscan/db/Updaterlib/wpscan/db/updater.rb同步本地数据库与 WPScan API。FILES常量定义了常规同步文件metadata.json、wp_fingerprints.json、timthumbs-v3.txt、config_backups.txt、db_exports.txt、backup_folders.txt、dynamic_finders.yml、LICENSE、sponsor.txt并会自动清理OLD_FILES中已废弃的旧文件当设置了--enterprise-db-token时额外从enterprise-data.wpscan.org下载wordpresses.json.gz、plugins.json.gz、themes.json.gz企业漏洞库压缩包通过X-DB-JSON-AUTH请求头鉴权VulnApilib/wpscan/db/vuln_api.rbAPI 客户端uri指向https://wpscan.com/api/v4/get方法对 404/429 静默返回空结果、对 HTTP 错误最多重试 3 次启用local_db时直接读取本地 gzip 漏洞库而不再请求 APIDynamicFinderslib/wpscan/db/dynamic_finders/根据数据库元数据dynamic_finders.yml自动生成 Finder使版本检测策略完全数据驱动Fingerprints版本检测指纹lib/wpscan/db/fingerprints.rb对应wp_fingerprints.json。重要模式Scanner Framework 单类混入模式。通用框架类WPScan::Target、WPScan::Browser、WPScan::Controller::{Base,Core}、WPScan::ParsedCli、WPScan::Vulnerability、WPScan::Model::{InterestingFinding,XMLRPC}等均为统一类不按框架/WordPress 分层拆分WordPress 专有行为通过模块混入注入。例如 lib/wpscan/target.rb 中class Target WebSite之后include Server::Generic与include Platform::WordPress。参数解析则委托给外部的opt_parse_validatorGemlib/opt_parse_validator/。动态 Finders。WPScan::DB::DynamicFinders::Baselib/wpscan/db/dynamic_finders/base.rb定义了允许的动态 Finder 类Comment、Xpath、HeaderPattern、BodyPattern、JavascriptVar、QueryParameter、ConfigParser。以 lib/wpscan/db/dynamic_finders/plugin.rb 为例finder_configs按 passive/aggressive 区分passive 模式选用path为 nil 的配置无需额外请求aggressive 模式选用带path的配置主动请求指定文件路径。版本检测类动态 FinderFinders::PluginVersion等也由此系统驱动。Slug 分类。WordPress 的插件/主题 slug 通过classify_slug助手lib/wpscan/helper.rb转换为 Ruby 类名处理三类边界情况以数字开头的 slug 加D_前缀如123-plugin→D_123Plugin因为 Ruby 类名不能以数字开头特殊字符转为下划线全非拉丁字符的 slug 变成HexSlug_加十六进制字节编码。API 请求追踪。lib/wpscan.rb 通过全局Typhoeus.on_complete钩子统计total_requests、total_data_sent、total_data_received、cached_requests与api_requests依据响应对象的from_vuln_api?判断用于监控 WPScan API 使用量与限额同时每次请求后调用WPScan::Browser.instance.trottle!进行请求节流。另外Typhoeus::Config.memoize false用于规避 Hydra 的内存泄漏对应 typhoeus#562。测试实践测试结构测试使用RSpec WebMock做 HTTP 桩Fixtures 位于spec/fixtures/包含动态 Finders、vuln_api、各 Finder 的响应样本、视图输出等共享示例位于spec/shared_examples/覆盖率由 SimpleCov 提供配置在.simplecov。关键测试助手spec/spec_helper.rbspec/spec_helper.rb 提供以下工具函数rspec_parsed_options(args)— 解析 CLI 参数内部会实例化除Base外的全部控制器以收集选项spec/spec_helper.rb#L74-L80df_expected_all— 动态 Finder 测试期望读取expected.ymlvuln_api_data_for(path)— 加载 vuln_api fixturesspec/fixtures/db/vuln_api/下的 JSONredefine_constant(constant, value)— 在测试中覆盖 WPScan 常量如DB_DIR实现隔离。测试标签--tag ~slow— 排除慢测试CI 中 PR 默认完整套件仅在 master 推送时运行。WebMock 端口归一化spec/spec_helper.rb中的 Typhoeus 适配器约 spec/spec_helper.rb#L82-L96对默认端口做了归一化处理http 的 80 端口与 https 的 443 端口会被移除以保证桩请求与实际请求 URL 一致——这是针对 WebMock/Typhoeus 兼容性的定制补丁对应 bblimke/webmock#552。常见陷阱GotchasActive Support 必须最先加载active_support/all必须在其他 Gem 之前 require否则使用 JSON 格式时会出现编码问题见 lib/wpscan.rb 顶部注释源码运行要在 git 仓库外ruby -Ilib bin/wpscan时避免在仓库目录内执行防止加载路径冲突数据库位置测试会通过redefine_constant将DB_DIR覆盖为spec/fixtures/db/生产环境按前述 XDG/legacy 规则决定API Token 冲突提前失败Core#before_scan在数据库更新前即调用VulnApi.validate_api_tokens!校验冲突 Token避免在--update不带--url的场景下误下载企业漏洞库见 app/controllers/core.rb。API 集成与配置WPScan API需要 API Token通过--api-token命令行参数、WPSCAN_API_TOKEN环境变量或配置文件提供免费额度25 次请求/天计费方式每检测到一个 WordPress 版本、插件、主题消耗一次请求响应追踪Typhoeus.on_complete钩子统计请求量lib/wpscan.rb--vuln-api-status可查看剩余额度。配置文件加载顺序WPScan 按以下顺序加载选项后者优先级更高加载逻辑见 lib/wpscan/controllers.rb 的register_config_files$XDG_CONFIG_HOME/wpscan/scan.json或$XDG_CONFIG_HOME/wpscan/scan.yml设置了XDG_CONFIG_HOME时~/.config/wpscan/scan.json或~/.config/wpscan/scan.yml未设置XDG_CONFIG_HOME时~/.wpscan/scan.json或~/.wpscan/scan.ymlpwd/.wpscan/scan.json或pwd/.wpscan/scan.yml。配置文件中 CLI 选项需使用snake_case命名例如{ api_token: your-token, max_threads: 10, url: https://example.com }源码实现中option_parser.config_files.result_key cli_options且Controllers#run会先解析选项再按before_scan → run → after_scan顺序执行整个控制器链lib/wpscan/controllers.rb。小结AGENTS.md 是进入 WPScan 仓库协作开发的操作手册它定义了从依赖安装、测试、RuboCop、构建到架构认知的完整工作流。结合源码可以确认仓库的扫描能力建立在一套清晰的 MVC 式分层Controllers/Finders/Models、数据驱动的动态 Finder 机制以及框架单类 WordPress 模块混入的设计之上。无论是人工维护者还是 AI Agent遵循 AGENTS.md 中改完必跑 rubocop、PR 默认跳过慢测试、注意加载顺序与数据库路径等约定即可安全高效地参与 WPScan 的迭代开发。赞分享网络安全漏洞扫描渗透测试应用安全CLI【免费下载链接】wpscanWPScan WordPress security scanner. Written for security professionals and blog maintainers to test the security of their WordPress websites. Contact us via contactwpscan.com项目地址https://gitcode.com/gh_mirrors/wp/wpscan点击查看免费下载相关推荐Compiler Explorer 开发指南面向 AI Agent 的仓库协作、构建测试与 SQS 编译工作线程架构解析Compiler Explorer 开发指南面向 AI Agent 的仓库协作、构建测试与 SQS 编译工作线程架构解析 本篇指南以仓库根目录 AGENTS.后端前端开发工具Infer 仓库开发指南面向 AI 编码代理的构建、测试与架构手册Infer 仓库开发指南面向 AI 编码代理的构建、测试与架构手册 本篇指南以仓库根目录的 AGENTS.md https://link.gitcode.co静态分析代码质量开发工具Borg 2.x 仓库 AI 协作开发指南分支策略、构建测试与架构速览面向 Agent 与开发者Borg 2.x 仓库 AI 协作开发指南分支策略、构建测试与架构速览面向 Agent 与开发者 Borg 是采用压缩与认证加密的去重归档工具本仓库当前运维存储上一篇G-Helper华硕笔记本性能控制的终极免费解决方案下一篇Blockly for Android 开源项目快速入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考