## 使用方法

> [!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. teler-wafパッケージをGoコードにインポートします：```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)ディレクトリを参照してください。

`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式内でこれらの変数を活用することで、受信リクエストの属性に効果的にアクセスして操作し、関連する脅威カテゴリを評価できます。これにより、特定のユースケースに合わせたカスタムルール条件<!-- and whitelists-->を作成できます。

#### 利用可能な関数

また、さまざまな関数にアクセスできます。これらの関数は、exprパッケージが提供する[組み込み関数](https://expr.medv.io/docs/Language-Definition#built-in-functions)と、DSLパッケージ内で特別に定義された関数の両方を含みます。関数は、Goの組み込み`strings`パッケージが提供する機能を利用しています。以下に利用可能な関数の詳細なリストを示します。

- `cidr`: 指定されたCIDRの範囲内のすべてのIPアドレスを取得します。
- `clone`: 文字列のコピーを作成します。
- `containsAny`: 文字列が指定された部分文字列のいずれかを含むかどうかを確認します。
- `equalFold`: 2つの文字列を大文字小文字を区別せずに比較します。
- `hasPrefix`: 文字列が指定された接頭辞を持つかどうかを確認します。
- `hasSuffix`: 文字列が指定された接尾辞を持つかどうかを確認します。
- `join`: 指定されたセパレータを使用して複数の文字列を連結します。
- `repeat`: 文字列を指定された回数繰り返します。
- `replace`: 文字列内の部分文字列の出現を置き換えます。
- `replaceAll`: 文字列内の部分文字列のすべての出現を置き換えます。
- `request`: DSL式内でリクエスト固有の情報にアクセスします。
- `threat`: 分析中の脅威カテゴリに関連する情報にアクセスします。
- `title`: 文字列をタイトルケースに変換します。
- `toLower`: 文字列を小文字に変換します。
- `toTitle`: 文字列をタイトルケースに変換します。
- `toUpper`: 文字列を大文字に変換します。
- `toValidUTF8`: 文字列を有効なUTF-8エンコード文字列に変換します。
- `trim`: 文字列から先頭および末尾の空白を削除します。
- `trimLeft`: 文字列から先頭の空白を削除します。
- `trimPrefix`: 文字列から指定された接頭辞を削除します。
- `trimRight`: 文字列から末尾の空白を削除します。
- `trimSpace`: 文字列から先頭および末尾の空白を削除し、連続する空白を1つの空白に圧縮します。
- `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などのさまざまなサードパーティシステムにセキュリティアラートを転送できます。これにより、セキュリティチームはセキュリティの脅威やイベントをリアルタイムで効率的に監視および対応できます。

Falco Sidekickとteler-wafの統合も可能です。`FalcoSidekickURL`オプションを使用することで、teler-wafがイベントをFalco Sidekickに送信するように構成でき、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",
})

最後に、脅威データセットをユーザーレベルのキャッシュディレクトリに保存するのではなく、メモリにロードする必要がある場合もあります。これは、ファイルアクセスが制限されているか遅い可能性があるdistrolessやランタイムイメージでアプリケーションやサービスを実行している場合に特に有用です。このシナリオでは、**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 の既知の問題の一覧を表示するには、["known-issue" ラベル](https://github.com/teler-sh/teler-waf/issues?q=is%3Aopen+is%3Aissue+label%3Aknown-issue) で issue をフィルタリングしてください。

## コミュニティ

私たちは Google Groups を専用のメーリングリストとして使用しています。重要な発表（新しいリリースの可用性など）については、[[email protected]](mailto:[email protected]) から [teler-announce](https://groups.google.com/g/teler-announce) に登録してください。この購読により、[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)、[問題報告](https://github.com/teler-sh/teler-waf/issues) は GitHub で追跡されています。ここで、コミュニティとの関わりのこれらの側面を積極的に管理し、対応しています。

## ライセンス

このパッケージはデュアルライセンスで提供されています。[Apache License 2.0](https://github.com/teler-sh/teler-waf/blob/master/LICENSE-APACHE) および [Elastic License 2.0 (ELv2)](https://github.com/teler-sh/teler-waf/blob/master/LICENSE-ELASTIC) です（メインパッケージ **teler** の場合）。

組織内でアプリケーションを保護するために自由に使用できます。ただし、メインパッケージを使用してクラウド、ホステッド、またはマネージドサービスを作成したり、商業目的で使用したりすることはできません。その場合は商用ライセンスが必要ですが、現在このオプションは利用できません。[ELv2](https://github.com/teler-sh/teler-waf/blob/master/LICENSE-ELASTIC) で許可されていない使用のためにこの商用ライセンスの取得にご興味がある場合は、**@dwisiswant0** までお問い合わせください。

teler-waf およびすべてのコントリビューションは、Dwi Siswanto 2022-2024 © の著作権です。