首页›插件与扩展

插件与扩展Pro

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

能做什么

检测扩展

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

请求 / 响应改写

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

审计与告警

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

动态规则源

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

生命周期

加载 — 启动或热更新时按配置中声明的可信目录扫描 .so，调用 plugin.Open 解析符号。
注册 — 调用导出的 Init 入口；插件向引擎注册钩子（请求前 / 检测中 / 转发前 / 响应后）。
运行 — 每个请求按注册顺序触发钩子，超时自动熔断、错误自动隔离不影响主链路。
卸载 — 配置变更或退出时调用 Close（若实现），释放资源。

最小示例

一个检测插件的骨架（仅依赖标准库 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 后投递到目标节点，即可在控制台启用。详见插件开发指南。

构建约束

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

开源仓库

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

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