teler-waf

teler-waf 是一个面向基于 Go 的 Web 应用程序的综合性安全解决方案。它作为一个 HTTP 中间件，提供了将 teler IDS 的 IDS 功能集成到现有 Go 应用程序中的易用接口。通过使用 teler-waf，您可以有效防御多种基于 Web 的攻击，例如跨站脚本（XSS）和 SQL 注入。

该包自带标准的 net/http.Handler，便于集成到应用程序的路由中。当客户端请求访问由 teler-waf 保护的路由时，请求会首先通过 teler IDS 进行检测，以识别已知的恶意模式。如果未检测到恶意模式，请求才会被放行进行后续处理。

除了提供针对 Web 攻击的防护外，teler-waf 还能提升应用程序的整体安全性和完整性。它具有高度可配置性，可根据应用程序的具体需求进行定制。

另请参阅：

• teler-sh/teler：实时 HTTP 入侵检测。
• teler-sh/teler-proxy：teler 代理，实现与 teler WAF 的无缝集成。
• teler-sh/teler-caddy：teler Caddy，将 teler WAF 的强大安全功能集成到 Caddy Web 服务器中。

特性

teler-waf 提供了一系列强大的功能，旨在增强 Go Web 应用程序的安全性：

• 适用于 Go Web 应用程序的 HTTP 中间件。
• 集成 teler IDS 功能。
• 使用 teler IDS 检测已知恶意模式。
  • 常见 Web 攻击，例如跨站脚本（XSS）和 SQL 注入等。
  • CVE，涵盖已知漏洞和利用。
  • 恶意 IP 地址，例如与已知恶意行为者或僵尸网络关联的 IP。
  • 恶意 HTTP 引用来源，例如基于应用程序 URL 结构不应出现的引用来源，或已知与恶意行为者关联的引用来源。
  • 恶意爬虫，涵盖来自已知恶意爬虫或抓取工具的请求，这些请求可能导致性能问题或试图提取应用程序中的敏感信息。
  • 目录暴力破解攻击，例如通过尝试常见目录名或使用字典攻击。
• 提供更高的灵活性，用于创建您自己的 自定义规则。
• 提供配置选项，可根据 URL 或标头对特定类型的请求进行 白名单 放行。
• 易于与多种框架 集成。
• 高度可配置，以适应应用程序的具体需求。

总的来说，teler-waf 为基于 Go 的 Web 应用程序提供了全面的安全解决方案，有助于防御基于 Web 的攻击，并提升应用程序的整体安全性和完整性。

安装

依赖项：

• 需要安装并配置 gcc（GNU 编译器套件）以编译 teler-waf。

要在 Go 应用程序中安装 teler-waf，请运行以下命令以下载并安装 teler-waf 包：```console go get github.com/teler-sh/teler-waf

## 使用方法

> [!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"

2. 使用 New 函数创建 Teler 类型的新实例。该函数接受多种可选参数，可用于配置 teler-waf 以适配应用的特定需求。```go waf := teler.New()

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

4. 在你的应用的 HTTP 路由中使用 handler，以便对特定路由应用 teler-waf 的安全措施。```go http.Handle("/path", handler)

就这样！你已经在你的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)
}

关于如何使用 teler-waf 或将其与任何框架集成的更多示例，请查看 examples/ 目录。

自定义规则

[!TIP] 如果你想探索配置、深入定制规则和编写 DSL 表达式，可以使用 teler WAF 游乐场 进行练习并获得实践经验。在这里，你还可以模拟定制化的请求，以满足应用程序的特定需求。

要将自定义规则集成到 teler-waf 中间件中，你有两个选择：Customs 和 CustomsFromFile。这些选项提供了灵活性，可以创建你自己的安全检查，或覆盖 teler-waf 提供的默认检查。

• Customs 选项

你可以直接使用 Customs 选项定义自定义规则，如上方的示例所示。

在 Customs 选项中，你提供一个 teler.Rule 结构数组。每个 teler.Rule 代表一个自定义规则，具有唯一的名称和一个指定规则中各条件如何评估（or 或 and）的条件。该规则由一个或多个 teler.Condition 结构组成，每个结构定义一个要检查的具体条件。条件可以基于 HTTP 方法、元素（headers、body、URI 或 any）以及要匹配的正则表达式模式或 DSL 表达式。

• CustomsFromFile 选项