sinhaparth5/coraza-waf-mod

# Coraza WAF Mod 一个用于 Go 的单二进制 Web 应用防火墙 + 反向代理，基于 [Coraza](https://github.com/corazawaf/coraza) (OWASP CRS) 构建，并带有内置的管理控制台。无需配置文件，无需外部数据库，无需 Node 工具链 —— 只需一个二进制文件，一个 SQLite 文件，使用 CLI 标志进行引导设置，其余一切均通过控制台完成。Docker 可用于本地开发，但并非必须。 ``` [Client] → [Coraza WAF + Proxy] → [Backend App(s)] ↕ [SQLite DB] ↕ [Admin Dashboard] ``` ## 功能 - **WAF 防护** — 内置于二进制文件中的 Coraza v3 与 OWASP 核心规则集 (CRS)。开箱即用地拦截 SQLi、XSS、RCE、路径遍历、受限文件访问以及已知的扫描器 User Agent。可以在 CRS 之上加载自定义 `.conf` 规则。 - **反向代理 / 多应用路由** — 按 Host 头（虚拟主机）或路径前缀（自动剥离前缀，类似于 nginx 的 `location`）进行路由，支持任意数量的后端应用。 - **IP 与国家/地区封禁** — 手动 IP 允许/拦截规则，以及基于 GeoIP2 的国家/地区封禁 (MaxMind GeoLite2)，支持感知 Cloudflare 的真实 IP 提取，以及可选的受信任代理 CIDR（用于 `X-Forwarded-For` / `X-Real-IP`）。 - **TLS** — 纯 HTTP、自动 Let's Encrypt 证书或您自己的证书/私钥 —— 可全局应用和/或应用于单个服务（通过控制台上传证书或为每个后端启用自动签发）。 - **管理控制台** — HTMX/Tailwind 用户界面，提供实时流量和威胁图表、可过滤并带有实时跟踪功能的请求日志、IP/地理规则管理以及服务（后端应用）管理 —— 所有更改立即生效，无需重启。 - **Prometheus 指标** — `/admin/metrics` 暴露请求量、延迟以及按原因细分的拦截计数器 (IP/地理/WAF)，并附带 Go runtime 指标。它受与控制台其余部分相同的 session-cookie 管理员身份验证保护（而非 HTTP Basic Auth），因此 scrape job 需要一种方式来携带已登录的 session cookie，而不是普通的用户名/密码。 - **一切皆在 SQLite 中** — 请求日志、IP/地理规则、服务和 TLS 状态全都存储在一个 `waf.db` 文件中。无需搭建 Postgres/Redis/MySQL。 ## 安装 ### 选项 A — 原生二进制（推荐） ``` curl -fsSL https://waf-install.astrareconslabs.com/coraza-waf-mod/install.sh | sudo bash ``` 这会下载适合您系统架构 (amd64/arm64) 的发布版二进制文件，验证其 SHA256 校验和，创建一个专用的非 root 系统用户 (`coraza-waf-mod`，仅授予 `CAP_NET_BIND_SERVICE` 权限，使其无需以 root 身份运行即可绑定 80/443 端口)，交互式地提示输入管理员邮箱和密码（或自动生成），并通过 `coraza-waf-mod setup` 将其植入数据库。随后，它会安装一个 systemd unit，使用 CLI 标志启动该二进制文件，并启动服务。 检查其运行状态： ``` sudo systemctl status coraza-waf-mod sudo journalctl -u coraza-waf-mod -f ``` 无需编辑任何配置文件 —— 安装程序设置的所有内容要么是固化在 systemd unit 中的标志（运行 `sudo systemctl cat coraza-waf-mod` 查看），要么是存储在数据库中并通过控制台管理的设置。数据、证书和 `waf.db` 位于 `/var/lib/coraza-waf-mod/` 目录下。 #### 升级 重新运行相同的命令： ``` curl -fsSL https://waf-install.astrareconslabs.com/coraza-waf-mod/install.sh | sudo bash ``` 安装程序会检测到位于 `/usr/local/bin/coraza-waf-mod` 的现有二进制文件并切换至升级模式：它会下载并验证最新版本，替换二进制文件，重写 systemd unit 并重启服务 —— 完全跳过交互式提示。在升级过程中，绝对不会触碰管理员凭据和 TLS 证书。如果希望固定特定版本而不是总是获取最新版本，请使用 `curl -fsSL ... | sudo CORAZA_VERSION=v1.2.3 bash`。 ### 选项 B — 从源码构建 需要 Go 1.25+。 ``` git clone https://github.com/sinhaparth5/coraza-waf-mod.git cd coraza-waf-mod make build # go generate (minifies JS) + go build -> ./coraza-waf-mod # Seed 一个 admin 账户（password 从 stdin 读取，而不是一个 flag）： echo "your-password" | ./coraza-waf-mod setup --admin-email you@example.com ./coraza-waf-mod # defaults: --listen :8080 --db waf.db --certs ./certs ``` `make run` 一步完成构建和运行（请先至少运行一次 `setup`，以便能够登录）。全过程纯 Go 实现（SQLite 驱动是 `modernc.org/sqlite`，无 CGO），因此只需 Go 工具链即可干净构建。请参阅 `main.go` 中等效于 `./coraza-waf-mod --help` 的标志，或 `CLAUDE.md` 中的标志表，以了解每个引导选项（`--listen-tls`、`--waf-rules`、`--geo-db`、`--retention`、`--tls-cert`/`--tls-key`、`--trusted-proxies`）。 ### 选项 C — 交叉编译的发布版二进制文件 ``` make dist # cross-compiles Linux amd64/arm64 and Windows amd64 binaries, CGO_ENABLED=0 make checksums # writes dist/checksums.txt ``` ### 选项 D — Docker（本地开发） ``` docker compose run --rm waf setup --db /data/waf.db --admin-email you@example.com docker compose up --build ``` `Dockerfile`（多阶段构建，最终镜像为 `scratch`）和 `docker-compose.yml` 仅供本地容器开发使用 —— 不是推荐的生产环境部署方式（请参见选项 A）。 ## 用法 1. 启动服务器（参见上文安装说明）—— 无需配置文件，仅使用 CLI 标志进行引导设置。 2. 首次登录前，使用 `coraza-waf-mod setup --admin-email you@example.com` 植入管理员账户（密码从标准输入读取）。`install.sh` 会以交互方式为您完成此操作。 3. 在 `http://:/admin` 打开管理控制台（该路径目前固定为 `/admin`），并使用该邮箱和密码登录。 4. 从 **Services** 添加后端应用：为其指定名称、匹配规则（Host 或路径 Prefix）以及后端 URL。向导在保存前会检查后端是否可达。服务完全存储在数据库中 —— 没有配置文件植入步骤。 5. 从各自的控制台页面管理 IP 规则、国家/地区封禁和请求日志 —— 所有操作都会立即生效。 6. （可选）从其所在行的 **Manage** 按钮为单个服务启用 TLS（上传证书，或开启自动签发 —— 从 Settings 页面设置 ACME 联系邮箱，或者在运行 `coraza-waf-mod setup` 时传入 `--domain`/`--acme-email`）。 ### GeoIP 设置（可选） 国家/地区封禁默认使用内置的 MaxMind GeoLite2 Country 数据库，因此全新构建的 Windows/Linux 版本无需手动复制 `.mmdb` 文件即可直接运行。本产品包含由 MaxMind 创建的 GeoLite 数据，可从 [https://www.maxmind.com](https://www.maxmind.com) 获取。 若要使用较新的外部副本覆盖内置数据库： 1. 在 [GeoLite2 注册页面](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/)创建 MaxMind 账户。 2. 在 MaxMind 账户门户中，生成用于数据库下载的 License Key。 3. 下载 `GeoIP2 Binary (.mmdb)` 格式的 `GeoLite2-Country`，然后解压出 `GeoLite2-Country.mmdb`。 4. 将该文件放在服务可读取的位置，例如： ``` sudo mkdir -p /var/lib/coraza-waf-mod sudo cp GeoLite2-Country.mmdb /var/lib/coraza-waf-mod/ ``` 5. 使用 `--geo-db` 让二进制文件指向它： ``` ./coraza-waf-mod --geo-db /var/lib/coraza-waf-mod/GeoLite2-Country.mmdb ``` （对于 systemd 安装，请将 `--geo-db ...` 添加到 unit 的 `ExecStart=` 行中，并执行 `sudo systemctl daemon-reload && sudo systemctl restart coraza-waf-mod`。） 保持 `--geo-db` 未设置即可使用内置数据库。GeoLite 用户必须保持数据库更新；MaxMind 要求在新版本发布后的 30 天内替换或销毁旧版本的数据库，因此发布构建应定期刷新内置的 `.mmdb`。 ## 开发 ``` make build # build (runs go generate first — required after editing static/js/src/*.js) make test # go test ./... make clean # remove binary, minified JS, dist/ ``` 如果您正在修改代码库，请参阅 `CLAUDE.md` 获取架构说明。

标签：AppImage, EVTX分析, Go语言, SQL注入防护, Web应用防火墙, XSS防护, 反向代理, 日志审计, 流量监控, 程序破解, 自定义请求头, 请求拦截