首页›插件与扩展

插件与扩展Pro

基于 Go plugin 的原生扩展机制，把你的安全逻辑直接嵌入请求处理流水线 —— 无 IPC 开销、毫秒级响应、与主程序共享内存。

能做什么

检测扩展

在内置 OWASP 规则集之外，注入业务专属检测：JWT 校验、签名校验、定制化正则、第三方威胁情报对接等。

请求 / 响应改写

在转发前后插入头部、剥离敏感字段、替换响应内容；可用于灰度、A/B、合规脱敏等场景。

审计与告警

把命中事件投递到 Kafka / Webhook / 日志中台；按客户业务字段补全审计上下文。

动态规则源

从远端 / 数据库 / 配置中心拉取规则并热更新到引擎；按租户、域名、路径粒度差异化下发。

钩子位置

每个插件在 plugin.yaml 中声明挂载位置，决定它在请求流水线的哪个阶段介入；同一位置内按 order 从小到大执行。

位置	触发时机	典型用途
`front`	最前置，ACL 之前	改写请求、按国家 / ASN 拒绝、预计数
`before_cc`	ACL 之后，CC 检查之前	对已通过 ACL 的流量做业务限流
`before_waf`	CC 之后，WAF 规则引擎之前（默认）	UA 校验、文件名校验、扫描探测
`before_origin`	WAF 通过后，回源之前	重写 URL、注入 Header
`after`	回源完成、响应回写前的末端	日志增强、响应改写（需谨慎）

除请求前钩子外，插件还可导出 AfterResponse 响应后钩子，在上游响应回写完毕后触发，仅拿到请求、状态码与响应头（不含 body），适合状态码统计与行为分析 —— 内置的 scan-guard 正是借此检测 404 爆破。

生命周期

加载 — 取得 Pro 授权后扫描插件目录中的 .so，调用 plugin.Open 解析符号，并校验禁止符号。
注册 — 调用导出的 Init，按返回的名称、顺序与启用状态，结合 plugin.yaml 的位置挂载到对应钩子。
运行 — 每个请求在对应位置按 order 触发钩子；调用包裹 recover，单个插件 panic 不影响主链路。
热重载 — 通过控制台或 POST /api/plugins/reload 重新读取 plugin.yaml，实时更新启用状态、顺序、位置与生效站点，无需重启。

最小示例

一个检测插件的骨架（仅依赖标准库 net/http，无需额外 SDK）：

// myplugin-1.0.0/source/main.go
package main

import "net/http"

// Init 返回 (name, order, enabled, handler)
func Init() (string, int, bool, func(http.ResponseWriter, *http.Request) (*http.Request, bool)) {
    return "myplugin", 10, true, Handler
}

// Handler 是请求前钩子
// 返回 (newReq, stop)：stop=true 表示已拦截，stop=false 继续后续链路
func Handler(w http.ResponseWriter, r *http.Request) (*http.Request, bool) {
    if r.Header.Get("X-Fake") == "1" {
        w.WriteHeader(http.StatusForbidden)
        w.Write([]byte("blocked by myplugin"))
        return nil, true
    }
    return r, false
}

编译为 .so 后投递到目标节点，即可在控制台启用。详见插件开发指南。

宿主能力与事件日志

插件可选导出 SetHostAPI 获取主进程注入的受控能力，并必须导出 SetPluginLogger 上报实时事件。

宿主能力	说明
`addACLBlock`	把 IP 写入中央 ACL 黑名单，带 TTL；与面板 ACL 统一管理
`getClientIP`	用主进程可信代理规则解析客户端 IP，与 WAF / ACL / CC 完全一致
`isWhitelisted`	零信任策略下固定返回 `false`，插件不得因 IP 白名单跳过检测

实时事件日志为强制要求：每次拦截 / 命中 / 阈值触发都应调用 logger，主进程会通过 WebSocket 把事件实时推送到「插件管理」页，让你毫秒级看到插件在拦截什么。

插件市场与导入

无需本地 Go 环境：在控制台「插件管理」上传 zip 源码包，或填入公网 zip 链接由主进程下载，二者都会用与主程序一致的 Go 工具链自动编译、热加载。

插件包为单一顶层目录，目录名须为 <名称>-<版本>，内含 source/ 源码、version.json 与 README.md。
主进程校验目录结构与版本号一致性，编译失败会直接回传错误，成功则写入插件目录并立即生效。
导入带 SSRF 防护与 zip 解压保护，单文件上限 50MB。

开源内置插件

仓库 plugins/ 目录提供 9 个开箱即用、可作模板参考的实战插件（均挂在 before_waf）：

插件	功能
`ai-shield`	AI 训练爬虫 UA 黑名单与 Prompt Injection 检测，命中即临时拉黑
`auth-guard`	登录端点暴破 / 撞库防护，滑窗失败计数触发 ACL 封禁
`cloud-ssrf`	云元数据地址与危险 scheme 拦截，含 IP 进制归一化
`filename-validator`	multipart 文件名危险字符、路径穿越与空字节拦截
`graphql-guard`	GraphQL 查询深度 / Alias 限制与 introspection 拦截
`scan-guard`	目录扫描 / 404 爆破检测，滑窗阈值触发临时封禁
`smuggler-guard`	HTTP 请求走私与 CRLF 注入、异常 Content-Length 检测
`tool-fingerprint`	扫描器 UA 指纹与 OOB 域名识别，命中即封禁
`useragent-validator`	空值 / 超长 User-Agent 与扫描器关键词拦截

构建约束

插件须使用与运行中主程序完全一致的 Go 工具链版本（当前普通构建为官方 go1.26.4）与依赖版本编译，否则 ABI 不匹配会导致加载失败 —— 这是 Go plugin 包的固有约束，与 FOXWAF 无关。
仅 Linux amd64 / arm64 支持原生 .so；Windows / 非 glibc 发行版请使用脚本扩展机制。
插件等同于本机代码执行：仅启用来源可信且通过签名校验的构建产物，建议在预发布环境验证后再上线。

开源仓库

SDK、示例插件与公共规则集托管在以下仓库，欢迎提交 Issue / PR：

GitHub · foxwaf/foxwaf GitCode 镜像文档中心