Home›Plugins & Extensions

Plugins & ExtensionsPro

Native extensions powered by Go plugin embed your security logic directly into the request pipeline — zero IPC overhead, millisecond response, shared memory with the main process.

What It Can Do

Detection Extensions

Inject business-specific detection on top of the built-in OWASP rule set: JWT validation, signature checks, bespoke regex, third-party threat-intel integration, etc.

Request / Response Rewriting

Inject headers, strip sensitive fields and rewrite response bodies before/after forwarding — for gray-release, A/B testing and compliance masking.

Audit & Alerting

Ship hit events to Kafka / Webhook / log platforms and enrich audit context with customer-specific fields.

Dynamic Rule Sources

Pull rules from a remote source / database / config center and hot-reload into the engine — differentiated delivery by tenant, domain and path.

Lifecycle

Load — On startup or hot reload, scan the configured trusted directory for .so files and resolve symbols via plugin.Open.
Register — Call the exported Init entry; the plugin registers hooks with the engine (pre-request / during-detection / pre-forward / post-response).
Run — Each request triggers hooks in registration order; timeouts trip a circuit breaker and errors are isolated automatically without affecting the main chain.
Unload — On configuration change or shutdown, Close is invoked (if implemented) to release resources.

Minimal Example

Skeleton of a detection plugin (only depends on the net/http standard library, no extra SDK):

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

import "net/http"

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

// Handler is the pre-request hook
// Returns (newReq, stop): stop=true means blocked, stop=false continues the pipeline
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
}

Compile to a .so and deploy to the target node, then enable it in the console. See Plugin development guide.

Build Constraints

Plugins must be compiled with the exact same Go toolchain version as the running main program (the current default build uses official go1.26.4) and matching dependency versions — ABI mismatches cause load failures. This is an inherent constraint of Go's plugin package, not FOXWAF-specific.
Native .so is supported only on Linux amd64 / arm64; on Windows / non-glibc distros use the script extension mechanism.
Plugins run as native code: enable only artifacts from trusted sources that have passed signature verification, and validate in a staging environment before production.

Open-source Repository

The SDK, example plugins and public rule sets live in the repositories below. Issues and PRs are welcome:

GitHub · foxwaf/foxwaf GitCode Mirror Documentation