AWAFAWAF

开发者

Antibot/AWAF 源码仓库 githubniko/antibot 的结构：入口、模块化检查、列表、验证码、阻断、日志、更新以及安全扩展方式。

仓库用途

https://github.com/githubniko/antibot 中的 Antibot/AWAF 是一个 PHP 防护层，通常在被保护站点的主应用之前加载。它根据配置、列表和浏览器信号检查访问者，然后做出三种结果之一：放行、显示带验证码的验证页，或阻断。

真正的防护代码部署到被保护站点时通常位于 /antibot/index.php。

index.php
xhr.php
includes/
includes/Checks/
includes/Utility/
lists/
templates/
skins/
js/
images/README/
VERSION

入口文件

  • index.php 是主要防护入口。它不会在 CLI 下运行，会跳过 xhr 和 favicon，加载 includes/autoload.php，创建 WAFSystem::getInstance()，并在防护启用时调用 run()。
  • xhr.php 是验证页使用的 JSON/XHR 入口。它启动 session，禁用缓存，处理 captcha skin 请求，通过 isAllowed2() 执行第二阶段检查，并在验证码成功后设置 marker。
  • .htaccess 和 README 示例支持在被保护站点中直接 require_once，或使用 auto_prepend_file 接入。

中央组装

主对象位于 includes/WAFSystem.class.php。它是一个 singleton，负责组装依赖和 checker 模块：

includes/autoload.php 会递归加载 includes/ 下的 PHP 文件，并按文件名排序。新增类时不要假设存在 Composer 或 PSR autoload；文件必须适配这个简单加载器。

  • Config 读取并补全 config.ini，创建 cache/，并保存 BasePath、CachePath、DOCUMENT_ROOT、ANTIBOT_PATH。
  • Profile 规范化 IP、HTTP protocol、User-Agent、Referer、Request URI、语言、RayID 和 RayIDSecret。
  • Logger、Marker、Template、GrayList 和 session storage 被各个检查共享。
  • includes/Checks/* 包含独立模块：IP、ASN、URL、Referer、User-Agent、Tor、FingerPrint、HTTP、Mobile、FPS、IFrame 和搜索引擎机器人。

检查流程

第一阶段在显示验证页之前运行：

第二阶段由 xhr.php 处理，浏览器 JavaScript 会发送 func: "checks"：

  • 如果 marker 已经有效，访问者会立即放行。
  • 先执行快速 allow 规则：whitelist_ip、ASN 白名单和搜索引擎机器人。
  • 然后执行 block 规则：配置为 BLOCK 的 IPv6、HTTP protocol、blacklist_ip、ASN block、Tor、URL block 和 User-Agent block。
  • 当对应 allow 规则启用时，URL、User-Agent 和 Referer 可以不经过验证码直接放行请求。
  • 如果没有规则放行访问者，Template->showVerificationPage() 返回 templates/template.inc.php。
  • js/api.js 收集 fingerprint、FPS、screen metrics、pixel ratio、referrer、location、BAS/旧 Mozilla engine 信号、iframe 状态和其他浏览器数据。
  • Api 只接受 POST JSON，限制输入大小，要求 CSRF token，并把异常请求加入 graylist。
  • isAllowed2() 会阻断缺失的必要信号、BAS/旧 driver，并按 action BLOCK 或 CAPTCHA 处理 mobile/FPS/Fingerprint/IFrame/HTTP/ASN/Tor。
  • 如果所有过滤器通过，Marker->set() 保存 marker，API 返回 allow。

模块化检查

大多数检查都以独立类的形式放在 includes/Checks/。很多模块有相同结构：enabled、action、lists/ 下的列表路径，以及 Checking() 或 isListed()。

扩展系统时，优先新增独立 checker 类，并在 initializeComponents() 以及对应阶段 isAllowed() 或 isAllowed2() 中显式接入。如果新逻辑需要独立设置、独立列表或独立 action，不要把它混入已有类。

  • WhiteListIP 和 BlackListIP 继承 ListBase，通过网络工具类支持 IPv4、IPv6、CIDR 和范围。
  • RequestChecker、RefererChecker 和 UserAgentChecker 使用字符串或正则风格列表处理 URL、referrer 和 User-Agent 规则。
  • ASNChecker 将 ASN 网络缓存到 cache/ 下的 SQLite 数据库，并按 updateTime 刷新。
  • TorChecker 下载并缓存 Tor exit node 列表。
  • FingerPrint 用 blacklist_fingerprint 检查浏览器 fingerprint，并可将 IP 加入 blacklist_ip。
  • FPSChecker、MobileChecker、HTTPChecker 和 IFrameChecker 不使用列表文件，而是根据 config 和 profile 值决策。
  • IndexBot 使用 indexbot_rules 中的 PTR 规则验证搜索机器人；这是较重的 DNS 检查，因此规则顺序很重要。

列表和配置

config.ini 通过 Config->init() 和 Config->set() 创建和补全。参数缺失时，模块会写入默认值和注释。Boolean 值支持 On/Off、true/false、yes/no、1/0。

lists/ 保存用户列表和运行时列表。基础类 ListBase 会在首次使用时创建文件，忽略 # 后的注释，使用 file lock 追加记录，并为注释添加时间戳。

重要列表：

不要硬编码这些文件的绝对路径。请使用 Config->BasePath、Config->CachePath 和 config 中的路径，因为安装目录不一定是 /antibot/。

  • whitelist_ip、blacklist_ip、graylist
  • whitelist_uri、blacklist_uri、captcha_uri
  • whitelist_useragent、blacklist_useragent、captcha_useragent
  • whitelist_referer、blacklist_referer、captcha_referer
  • whitelist_asn、blacklist_asn、captcha_asn
  • blacklist_fingerprint、blacklist_tor、indexbot_rules

验证码、模板和客户端文件

验证码不会直接设置 marker。API 先返回 captcha，并在 session 中写入隐藏标志。Skin 成功后，客户端调用动态 marker 函数；xhr.php 验证 hidden value 后才调用 Marker->set()。

  • Template->showVerificationPage() 返回 templates/template.inc.php，发送 no-cache/noindex headers，并在 main.header404 启用时可为占位页返回 404。
  • Template->showBlockPage() 返回 templates/template_block.inc.php，HTTP 状态为 403。
  • skins/checkbox.php、slider.php、slider_rotate.php、slider_zsay.php 和 example.php 是验证码变体。Skin 通过 main.captcha_type 选择；xhr.php 在 require 文件前会清理请求中的 skin 名称。
  • js/api.js、fp.js、frame_rate.js、metrika.js、tags.js 和 js/lang/* 提供浏览器检查、fingerprint/FPS、语言和 Yandex Metrika 集成。

日志、marker 和更新

Logger 写入 logs/antibot.log，每行包含日期、RayID、IP 和消息。DEBUG 级别会追加 JSON context。日志轮转在 xhr.php 的检查过程中触发，使用 logs.max_size 和 logs.rotate。

Marker 默认将标记保存在带 aw_ 前缀的 cookie 中。可选的 cookie.storage_type = awsession 会使用 cache/sessid/ 下的文件 session storage。修改 cookie.cookie_name 会重置访问者 marker，因为 RayIDSecret 由 salt、IP 和 User-Agent 生成。

当 sysupdate.enabled = On 时，SysUpdate 会通过 GitHub API 和分支 zip 包从 githubniko/antibot 更新代码。删除旧版本时会保留 .git、.gitignore、lists/、logs/、cache/、*.ini、*.bak、*.backup、*.origin 和更新包。本地修改过的 PHP、JS、templates 或 skins 可能被更新覆盖，因此应把这些修改放入版本控制或独立部署流程。

安全扩展和调试

  • 先通过 Config->init() 添加新设置，让现有安装获得安全默认值。
  • 保持规则顺序：轻量 allow/block 检查应位于 DNS、ASN、外部 HTTP 下载和浏览器检查之前。
  • 对基于列表的规则，继承 ListBase；只有数据格式不同时才重写 validation/comparison。
  • 不要信任 JavaScript 数据：isAllowed2() 必须检查每个字段是否存在以及类型是否正确，就像现在对 frameRate、fingerPrint、isBas、screenWidth、pixelRatio、isFrame 和 location 所做的那样。
  • 在 proxy 或 Cloudflare 后面运行时，使用 HeaderProxy 和 header_proxy 配置段，不要直接读取 REMOTE_ADDR。
  • 通过 logs/antibot.log 调试行为：查看 RayID、IP、allow/block/captcha 原因以及写入列表的记录。
  • 不要单独修改公开 API status 名称（allow、captcha、block、fail、no_csrf）；如需修改，必须同步更新 js/api.js 和 skins。
  • 发布前检查 PHP 兼容性。README 声明支持 PHP 5.6.4+，因此不要使用会破坏旧安装的语法。