## 使用方法

> [!WARNING]
> **弃用通知**：威胁排除（`Excludes`）将在即将发布的版本（**v2**）中弃用。请参见 [#73](https://github.com/teler-sh/teler-waf/discussions/73) 和 [#64](https://github.com/teler-sh/teler-waf/issues/64)。

以下是在 Go 应用程序中使用 teler-waf 的示例：

1. 在你的 Go 代码中导入 teler-waf 包：```go
import "github.com/teler-sh/teler-waf"

3. 使用 `Teler` 实例的 `Handler` 方法创建一个 `net/http.Handler`。该处理器随后可在应用程序的 HTTP 路由中使用，以便将 teler-waf 的安全措施应用于特定路由。```go
handler := waf.Handler(http.HandlerFunc(yourHandlerFunc))

就这样！你已经在你的Go应用中配置了teler-waf。

**选项：**

要获取可用于自定义teler-waf的选项列表，请参见[`teler.Options`](https://pkg.go.dev/github.com/teler-sh/teler-waf#Options)结构体。

### 示例

以下是一个如何自定义teler-waf的选项和规则的示例：```go
// main.go
package main

import (
	"net/http"

	"github.com/teler-sh/teler-waf"
	"github.com/teler-sh/teler-waf/request"
	"github.com/teler-sh/teler-waf/threat"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// This is the handler function for the route that we want to protect
	// with teler-waf's security measures.
	w.Write([]byte("hello world"))
})

var rejectHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// This is the handler function for the route that we want to be rejected
	// if the teler-waf's security measures are triggered.
	http.Error(w, "Sorry, your request has been denied for security reasons.", http.StatusForbidden)
})

func main() {
	// Create a new instance of the Teler type using the New function
	// and configure it using the Options struct.
	telerMiddleware := teler.New(teler.Options{
		// Exclude specific threats from being checked by the teler-waf.
		Excludes: []threat.Threat{
			threat.BadReferrer,
			threat.BadCrawler,
		},
		// Specify whitelisted URIs (path & query parameters), headers,
		// or IP addresses that will always be allowed by the teler-waf
		// with DSL expressions.
		Whitelists: []string{
			`request.Headers matches "(curl|Go-http-client|okhttp)/*" && threat == BadCrawler`,
			`request.URI startsWith "/wp-login.php"`,
			`request.IP in ["127.0.0.1", "::1", "0.0.0.0"]`,
			`request.Headers contains "authorization" && request.Method == "POST"`
		},
		// Specify file path or glob pattern of custom rule files.
		CustomsFromRule: "/path/to/custom/rules/**/*.yaml",
		// Specify custom rules for the teler-waf to follow.
		Customs: []teler.Rule{
			{
				// Give the rule a name for easy identification.
				Name:      "Log4j Attack",
				// Specify the logical operator to use when evaluating the rule's conditions.
				Condition: "or",
				// Specify the conditions that must be met for the rule to trigger.
				Rules: []teler.Condition{
					{
						// Specify the HTTP method that the rule applies to.
						Method: request.GET,
						// Specify the element of the request that the rule applies to
						// (e.g. URI, headers, body).
						Element: request.URI,
						// Specify the pattern to match against the element of the request.
						Pattern: `\$\{.*:\/\/.*\/?\w+?\}`,
					},
				},
			},
			{
				// Give the rule a name for easy identification.
				Name: `Headers Contains "curl" String`,
				// Specify the conditions that must be met for the rule to trigger.
				Rules: []teler.Condition{
					{
						// Specify the DSL expression that the rule applies to.
						DSL: `request.Headers contains "curl"`,
					},
				},
			},
		},
		// Specify the file path to use for logging.
		LogFile: "/tmp/teler.log",
	})

	// Set the rejectHandler as the handler for the telerMiddleware.
	telerMiddleware.SetHandler(rejectHandler)

	// Create a new handler using the handler method of the Teler instance
	// and pass in the myHandler function for the route we want to protect.
	app := telerMiddleware.Handler(myHandler)

	// Use the app handler as the handler for the route.
	http.ListenAndServe("127.0.0.1:3000", app)
}

> [!IMPORTANT]
> 请注意，`condition`、`method` 和 `element` 是可选参数。它们的默认值如下：`condition` 设置为 **or**，`method` 设置为 **ALL**，`element` 设置为 **ANY**。因此，如果需要，你可以将这些参数留空。`pattern` 参数是必填的，除非你指定了一个 `dsl` 表达式。在这种情况下，当提供了 `dsl` 表达式时，teler-waf 将忽略分配给 `method` 和 `element` 的任何值，即使它们已被定义。要查看一些示例，请参阅 [`tests/rules/`](https://github.com/teler-sh/teler-waf/tree/master/tests/rules/valid) 目录。

你可以通过指定实际文件路径或 glob 模式来设置 `CustomsFromFile` 选项，指向你的自定义规则文件的位置。例如：```go
// Create a new instance of the Teler middleware and
// specify custom rules with the CustomsFromFile option.
telerMiddleware := teler.New(teler.Options{
    CustomsFromFile: "/path/to/custom/rules/**/*.yaml",
})

检查传入的请求方法是否为"GET":```sql
request.Method == "GET"

检查传入请求的IP地址是否来自localhost：```sql
request.IP in ["127.0.0.1", "::1", "0.0.0.0"]

检查传入请求体是否包含"foo"：```sql
request.Body contains "foo"

这些示例展示了 DSL 表达式的表达能力，使你能够基于各种请求属性定义复杂的条件。通过利用这些表达式，你可以有效定义评估传入请求的标准，并据此定制自定义规则或白名单，从而实现对应用程序行为的精细控制。

#### 可用变量

使用 DSL 表达式时，你可以访问多种变量，这些变量提供了关于传入请求和被分析威胁类别的宝贵信息。以下是可用变量的详细说明：

- **威胁类别**

	所有 `threat.Threat` 类型的常量标识符都可以作为有效变量使用。这些标识符代表与分析相关的不同威胁类别。

- **`request`**

	`request` 变量表示传入的请求，并提供对其字段及对应值的访问。`request` 变量下包含以下子变量：

  - `request.URI`：表示传入请求的 URI，包括路径、查询参数、参数和片段。
  - `request.Headers`：表示传入请求的标头，以多行形式呈现。
  - `request.Body`：表示传入请求的正文。
  - `request.Method`：表示传入请求的方法。
  - `request.IP`：表示与传入请求关联的客户端 IP 地址。
  - `request.ALL`：以切片形式表示上述请求字段中的所有字符串值。

- **`threat`**

	`threat` 变量表示正在分析的威胁类别。它属于 `threat.Threat` 类型，允许你基于与请求相关的具体威胁类别进行评估和决策。

通过在 DSL 表达式中利用这些变量，你可以有效访问和操作传入请求的属性，并评估相关的威胁类别。这使得你能够创建针对特定用例定制的自定义规则条件<!--以及白名单-->。

#### 可用函数

此外，你还可以使用多种函数。这些函数既包括 expr 包提供的[内置函数](https://expr.medv.io/docs/Language-Definition#built-in-functions)，也包括 DSL 包中专门定义的函数。这些函数利用了 Go 内置 `strings` 包提供的功能。以下是可用函数的详细列表：

- `cidr`：获取指定 CIDR 范围内的所有 IP 地址。
- `clone`：创建字符串的副本。
- `containsAny`：检查字符串是否包含任何指定的子串。
- `equalFold`：以不区分大小写的方式比较两个字符串。
- `hasPrefix`：检查字符串是否具有指定的前缀。
- `hasSuffix`：检查字符串是否具有指定的后缀。
- `join`：使用指定的分隔符连接多个字符串。
- `repeat`：将字符串重复指定的次数。
- `replace`：替换字符串中的子串。
- `replaceAll`：替换字符串中所有出现的子串。
- `request`：在 DSL 表达式中访问请求特定信息。
- `threat`：访问与被分析威胁类别相关的信息。
- `title`：将字符串转换为标题大小写。
- `toLower`：将字符串转换为小写。
- `toTitle`：将字符串转换为标题大小写。
- `toUpper`：将字符串转换为大写。
- `toValidUTF8`：将字符串转换为有效的 UTF-8 编码字符串。
- `trim`：去除字符串首尾的空白字符。
- `trimLeft`：去除字符串开头的空白字符。
- `trimPrefix`：去除字符串的指定前缀。
- `trimRight`：去除字符串末尾的空白字符。
- `trimSpace`：去除字符串首尾空白，并合并字符串内部的连续空白。
- `trimSuffix`：去除字符串的指定后缀。

关于运算符和内置函数的更多详细信息，请参阅 [Expr 文档](https://expr.medv.io/docs/Getting-Started)。该文档提供了关于在 DSL 表达式中使用运算符和探索可用内置函数的全面指南。

### 简化配置管理

为了有效配置，需要定义一系列设置，包括白名单、自定义规则定义、日志偏好及其他参数。[`option`](https://pkg.go.dev/github.com/teler-sh/teler-waf/option) 包简化了这一配置工作流，使你能够高效地将 JSON 和 YAML 格式的配置数据解组或加载为 teler-waf 能够理解并应用的格式。```go
// Load configuration from a YAML file.
opt, err := option.LoadFromYAMLFile("/path/to/teler-waf.conf.yaml")
if err != nil {
    panic(err)
}

// Create a new instance of the Teler type with
// the loaded options.
telerMiddleware := teler.New(opt)

### 日志

以下是 teler-waf 在请求中检测到威胁时日志行的大致示例：```json
{"level":"warn","ts":1672261174.5995026,"msg":"bad crawler","id":"654b85325e1b2911258a","category":"BadCrawler","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/","ip_addr":"127.0.0.1:37702","headers":{"Accept":["*/*"],"User-Agent":["curl/7.81.0"]},"body":""}}
{"level":"warn","ts":1672261175.9567692,"msg":"directory bruteforce","id":"b29546945276ed6b1fba","category":"DirectoryBruteforce","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/.git","ip_addr":"127.0.0.1:37716","headers":{"Accept":["*/*"],"User-Agent":["X"]},"body":""}}
{"level":"warn","ts":1672261177.1487508,"msg":"Detects common comment types","id":"75412f2cc0ec1cf79efd","category":"CommonWebAttack","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/?id=1%27%20or%201%3D1%23","ip_addr":"127.0.0.1:37728","headers":{"Accept":["*/*"],"User-Agent":["X"]},"body":""}}

通过这种自定义程度，您可以构建个性化且信息丰富的响应，并在 teler-waf 阻止或拒绝请求时显示这些响应。`HTML` 选项允许您直接以字符串形式指定所需的 HTML 内容，而 `HTMLFile` 选项则允许您引用包含自定义 HTML 响应的外部文件。

此外，为提升用户体验，您可以在 HTML 内容中利用占位符生成动态元素。在运行时，这些占位符将被替换为实际值，从而生成更具上下文相关性的响应。目前支持和可用的占位符包括：

* `{{ID}}`：请求 ID，可用于唯一标识每个被拒绝的请求。
* `{{message}}`：拒绝消息，说明请求被阻止的原因。
* `{{threat}}`：威胁类别，提供有关检测到的安全威胁的信息。

通过使用这些占位符，您可以创建详细且全面的响应，有效传达请求被拒绝或阻止的理由。

### Falco Sidekick

[Falco Sidekick](https://github.com/falcosecurity/falcosidekick) 是一款工具，用于接收来自 Falco（一个开源的云原生运行时安全项目）的事件，并将这些事件发送到不同的输出通道。它允许您将安全告警转发到各种第三方系统，例如 Slack、Elasticsearch、Loki、Grafana、Datadog 以及[更多](https://github.com/falcosecurity/falcosidekick#outputs)。这使安全团队能够实时高效地监控和响应安全威胁及事件。

将 Falco Sidekick 与 teler-waf 集成也是可行的。通过使用 `FalcoSidekickURL` 选项，您可以配置 teler-waf 将事件发送到 Falco Sidekick，后者会为您接收并处理这些事件。为此，只需使用 `New` 函数创建一个新的 `Teler` 类型实例，并提供 `FalcoSidekickURL` 选项，填入您的 Falco Sidekick 实例 URL。例如：```go
// Create a new instance of the Teler type using
// the New function & integrate Falco Sidekick.
telerMiddleware := teler.New(teler.Options{
	FalcoSidekickURL: "http://localhost:2801",
})

最后，在某些情况下，可能需要将威胁数据集加载到内存中，而非保存到用户级缓存目录。当你运行的应用或服务部署在无发行版或运行时镜像上，且文件访问可能受限或缓慢时，这一点尤为实用。在此场景下，你可以设置一个名为 **InMemory** 的选项为 `true`，从而将威胁数据集加载到内存中，实现更快的访问速度。```go
// Create a new instance of the Teler type using the
// New function & enable in-memory threat datasets store.
telerMiddleware := teler.New(teler.Options{
	InMemory: true,
})

> [!NOTE]
> 基准测试结果可能有所不同，且可能不一致。自那时起，[teler-resources](https://github.com/teler-sh/teler-resources) 数据集可能已有所增加，这可能会影响结果。

- **配置复杂性**：配置 teler-waf 以适应应用程序的特定需求可能较为复杂，且可能需要一定的 Web 安全专业知识。这可能会使不熟悉应用防火墙和 IDS 系统的人难以正确设置和使用 teler-waf。
- **保护有限**：teler-waf 并非完美的安全解决方案，可能无法防御所有可能的攻击类型。与任何安全系统一样，定期监控和维护 teler-waf 以确保其提供所需保护级别至关重要。

#### 已知问题

要查看 teler-waf 的已知问题列表，请通过 [“已知问题”标签](https://github.com/teler-sh/teler-waf/issues?q=is%3Aopen+is%3Aissue+label%3Aknown-issue) 筛选问题。

## 社区

我们使用 Google Groups 作为专用邮件列表。订阅 [teler-announce](https://groups.google.com/g/teler-announce)（通过 [[email protected]](mailto:[email protected])）以获取重要公告，例如新版本的发布。订阅后，您将及时了解与 [teler IDS](https://github.com/teler-sh/teler)、[teler WAF](https://github.com/teler-sh/teler-waf)、[teler Proxy](https://github.com/teler-sh/teler-proxy)、[teler Caddy](https://github.com/teler-sh/teler-caddy) 和 [teler Resources](https://github.com/teler-sh/teler-resources) 相关的重大进展。

任何 [咨询](https://github.com/teler-sh/teler-waf/discussions/categories/q-a)、[讨论](https://github.com/teler-sh/teler-waf/discussions) 或 [问题](https://github.com/teler-sh/teler-waf/issues) 均在 GitHub 上跟踪。我们在此积极管理和处理社区参与的相关事宜。

## 许可协议

本软件包采用双重许可：[Apache License 2.0](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-APACHE) 和 [Elastic License 2.0 (ELv2)](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC)（适用于主包 **teler**）。

您可以在组织内部自由使用它来保护您的应用程序。但是，您不得使用主包创建云服务、托管服务或管理服务，也不得用于任何商业目的，除非您为此获得商业许可——但目前尚不提供此选项。如果您有兴趣获取此商业许可，用于 [ELv2](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC) 未授权的用途，请联系 **@dwisiswant0**。

teler-waf 及其所有贡献版权 © 归 Dwi Siswanto 2022-2024 所有。