corazawaf/coraza-proxy-wasm
GitHub: corazawaf/coraza-proxy-wasm
基于 Coraza WAF 的 proxy-wasm 过滤器，为 Envoy 和 Istio 提供云原生 Web 应用防火墙能力。
Stars: 206 | Forks: 48
# Coraza Proxy WASM
基于 [Coraza](https://github.com/corazawaf/coraza) 构建并实现 [proxy-wasm ABI](https://github.com/proxy-wasm/spec) 的 Web Application Firewall WASM 过滤器。它可以直接加载到 Envoy 中，也可以作为 Istio 插件使用。
请注意，WAF 并不是一种即插即用的安全解决方案。它需要针对 WAF 要保护的环境和流量量身定制配置并进行调优才能发挥作用。在生产环境中使用时，强烈建议充分了解部署的配置（参见 [@recommended-conf](./wasmplugin/rules/coraza.conf-recommended.conf) 和 [@crs-setup-conf](./wasmplugin/rules/crs-setup.conf.example)），并对所使用的规则集进行调优。有关调优 OWASP Core Rule Set (CRS) 的更多信息，请参阅 [误报与调优](https://coreruleset.org/docs/concepts/false_positives_tuning/) 指南。
## 快速开始
`go run mage.go -l` 列出了所有可用的命令：
```
▶ go run mage.go -l
Targets:
build* builds the Coraza wasm plugin.
check runs lint and tests.
coverage runs tests with coverage and race detector enabled.
doc runs godoc, access at http://localhost:6060
e2e runs e2e tests with a built plugin against the example deployment.
format formats code in this repository.
ftw runs ftw tests with a built plugin and Envoy.
lint verifies code quality.
runEnvoyExample spins up the test environment, access at http://localhost:8080.
teardownEnvoyExample tears down the test environment.
ReloadEnvoyExample reloads the test environment.
test runs all unit tests.
* default target
```
### 构建要求
构建此过滤器需要：
- [Go](https://go.dev/doc/install)
- [TinyGo](https://tinygo.org/getting-started/install/) `0.34.0`。注意：目前不支持更高版本。
最新的所需版本可以查看 [`minGoVersion` 和 `tinygoMinorVersion` 变量](./magefiles/magefile.go)。
### 构建过滤器
```
go run mage.go build
```
你可以在 `./build/main.wasm` 找到 WASM 插件。
### 多阶段（Multiphase）
默认情况下，coraza-proxy-wasm 在启用多阶段评估的情况下运行（参见 [coraza.rule.multiphase_evaluation](.magefiles/magefile.go) 构建标签）。它允许在规则变量准备就绪的阶段对其进行评估，可能会提前进入规则定义的阶段。此功能适用于 coraza-proxy-wasm，特别是 Envoy 的请求生命周期，旨在尽快检查到目前为止已接收到的数据。这有助于尽早执行操作，避免 WAF 绕过。此功能与 [早期阻断（Early Blocking） CRS 功能](#recommendations-using-crs-with-proxy-wasm) 相结合，可以有效地提高异常评分，并最终在尽可能早的阶段丢弃请求。
如果你想禁用它，请在构建过滤器之前将 `MULTIPHASE_EVAL` 环境变量设置为 `false`。
### 在 Envoy 进程中运行过滤器
为了运行 coraza-proxy-wasm，我们需要启动一个包含此过滤器配置的 envoy 配置
```
...
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
codec_type: auto
route_config:
...
http_filters:
- name: envoy.filters.http.wasm
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
config:
name: "coraza-filter"
root_id: ""
configuration:
"@type": "type.googleapis.com/google.protobuf.StringValue"
value: |
{
"directives_map": {
"default": [
"SecDebugLogLevel 9",
"SecRuleEngine On",
"SecRule REQUEST_URI \"@streq /admin\" \"id:101,phase:1,t:lowercase,deny\""
]
},
"default_directives": "default"
}
vm_config:
runtime: "envoy.wasm.runtime.v8"
vm_id: "coraza-filter_vm_id"
code:
local:
filename: "build/main.wasm"
```
### 使用 CRS
[Core Rule Set](https://github.com/coreruleset/coreruleset) 已内置到扩展中，要在配置中使用它，你只需将其直接包含在规则中：
加载整个 coreruleset：
```
configuration:
"@type": "type.googleapis.com/google.protobuf.StringValue"
value: |
{
"directives_map": {
"default": [
"Include @demo-conf",
"SecDebugLogLevel 9",
"SecRuleEngine On",
"Include @crs-setup-conf",
"Include @owasp_crs/*.conf"
]
},
"default_directives": "default"
}
```
加载部分内容：
```
configuration:
"@type": "type.googleapis.com/google.protobuf.StringValue"
value: |
{
"directives_map": {
"default": [
"Include @demo-conf",
"SecDebugLogLevel 9",
"SecRuleEngine On",
"Include @crs-setup-conf",
"Include @owasp_crs/REQUEST-901-INITIALIZATION.conf"
]
},
"default_directives": "default"
}
```
#### 在 coraza-proxy-wasm 中使用 CRS 的建议
- 为了尽可能多地缓解发送到上游的恶意请求（或打开的连接），建议保持启用 [CRS 早期阻断（Early Blocking）](https://coreruleset.org/20220302/the-case-for-early-blocking/) 功能（SecAction [`900120`](./wasmplugin/rules/crs-setup.conf.example)）。
### 运行 go-ftw (CRS 回归测试)
以下命令在完全加载 CRS 的情况下，针对过滤器运行 [go-ftw](https://github.com/coreruleset/go-ftw) 测试套件。
```
go run mage.go ftw
```
查看其配置文件 [ftw.yml](./ftw/ftw.yml) 以了解当前被排除的测试的详细信息。
还可以通过执行以下命令来运行单个测试：
```
FTW_INCLUDE=920410 go run mage.go ftw
```
## 示例：启动 coraza-wasm-filter 进行手动测试
一旦过滤器构建完成，你可以通过命令 `go run mage.go runEnvoyExample`、`go run mage.go reloadEnvoyExample` 和 `go run mage.go teardownEnvoyExample` 来启动、测试和销毁测试环境。
带有 coraza-wasm 过滤器的 Envoy 将可以通过 `localhost:8080` 访问。
该过滤器配置为在异常评分模式下加载 CRS 运行。
有关详细信息和本地调整配置，请参阅 [@recommended-conf](./wasmplugin/rules/coraza.conf-recommended.conf) 和 [@crs-setup-conf](./wasmplugin/rules/crs-setup.conf.example)。
为了在执行请求时单独监控 envoy 日志，你可以在另一个终端中运行：
- Envoy 日志：`docker compose -f ./example/envoy/docker-compose.yml logs -f envoy-logs`。
- 关键的 wasm（审计）日志：`docker compose -f ./example/envoy/docker-compose.yml logs -f wasm-logs`
Envoy 示例还附带了一个 Grafana 仪表板，可以在 `localhost:3000` (admin/admin) 访问，以便监控内存消耗。
### 手动请求
可以手动执行并调整以掌握过滤器行为的请求列表：
```
# True positive 请求：
# Custom rule phase 1
curl -I 'http://localhost:8080/admin'
# Custom rule phase 2
curl -i -X POST 'http://localhost:8080/anything' --data "maliciouspayload"
# Custom rule phase 3
curl -I 'http://localhost:8080/status/406'
# Custom rule phase 4
curl -i -X POST 'http://localhost:8080/anything' --data "responsebodycode"
# XSS phase 1
curl -I 'http://localhost:8080/anything?arg='
# SQLI phase 2（读取请求体）
curl -i -X POST 'http://localhost:8080/anything' --data "1%27%20ORDER%20BY%203--%2B"
# 触发 CRS 扫描器检测规则 (913100)
curl -I --user-agent "Grabber/0.1 (X11; U; Linux i686; en-US; rv:1.7)" -H "Host: localhost" -H "Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5" localhost:8080
# True negative 请求：
# 带有无害参数的 GET 请求
curl -I 'http://localhost:8080/anything?arg=arg_1'
# A payload (reading the body request)
curl -i -X POST 'http://localhost:8080/anything' --data "This is a payload"
# 无害的响应体
curl -i -X POST 'http://localhost:8080/anything' --data "Hello world"
# 常见的 user-agent
curl -I --user-agent "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" localhost:8080
```
### WAF 指标
指标以 prometheus 格式在 `localhost:8082`（envoy 配置中的 admin cluster）公开。
```
curl -s localhost:8082/stats/prometheus | grep waf_filter
```
我们将获取带有相应标签的指标：
```
# TYPE waf_filter_tx_interruptions counter
waf_filter_tx_interruptions{phase="http_request_headers_identifier",rule_id="101",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_request_body_identifier",rule_id="102",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_response_headers_identifier",rule_id="103",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_response_body_identifier",rule_id="104",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_request_body_identifier",rule_id="949110",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_response_headers_identifier",rule_id="949110",identifier="global",owner="coraza"} 1
waf_filter_tx_interruptions{phase="http_request_headers_identifier",rule_id="949111",identifier="global",owner="coraza"} 1
# TYPE waf_filter_tx_total counter
waf_filter_tx_total{} 11
```
标签：AI工具, AppImage, CISA项目, Envoy, EVTX分析, Go, Istio, Ruby工具, WAF, WASM, Web应用防火墙, 安全防护, 日志审计, 自定义请求头, 请求拦截