## Использование

> [!WARNING]
> **Уведомление о прекращении поддержки**: Исключения угроз (`Excludes`) будут удалены в предстоящем релизе (**v2**). См. [#73](https://github.com/teler-sh/teler-waf/discussions/73) и [#64](https://github.com/teler-sh/teler-waf/issues/64).

Вот пример использования teler-waf в приложении на Go:

1. Импортируйте пакет teler-waf в свой код на Go:```go
import "github.com/teler-sh/teler-waf"

3. Используйте метод `Handler` экземпляра `Teler` для создания `net/http.Handler`. Этот обработчик затем может использоваться в HTTP-маршрутизации вашего приложения для применения мер безопасности teler-waf к определённым маршрутам.```go
handler := waf.Handler(http.HandlerFunc(yourHandlerFunc))

Вот и всё! Вы настроили teler-waf в вашем приложении Go.

**Параметры:**

Для списка параметров, доступных для настройки 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` с фактическим путем к файлу или шаблоном glob, указывающим на расположение ваших пользовательских файлов правил. Например:```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-выражениях, вы можете эффективно получать доступ к атрибутам входящих запросов и управлять ими, а также оценивать соответствующие категории угроз. Это позволяет вам создавать пользовательские условия правил<!--и белые списки-->, настроенные под ваш конкретный случай использования.

#### Доступные функции

Кроме того, у вас есть доступ к различным функциям. Эти функции включают как [встроенные функции](https://expr.medv.io/docs/Language-Definition#built-in-functions), предоставляемые пакетом expr, так и функции, специально определённые в пакете DSL. Функции используют возможности, предоставляемые встроенным пакетом `strings` языка Go. Вот подробный список доступных функций:

- `cidr`: Получить все IP-адреса в диапазоне по заданному CIDR.
- `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}}`: Идентификаторы запросов, позволяющие уникально идентифицировать каждый отклонённый запрос.
* `{{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, который будет получать и обрабатывать их за вас. Для этого просто создайте новый экземпляр типа `Teler` с помощью функции `New` и укажите в опции `FalcoSidekickURL` URL вашего экземпляра Falco Sidekick. Например:```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 или runtime, где доступ к файлам может быть ограничен или медленным. В таком сценарии вы можете установить опцию **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 для удовлетворения специфических потребностей вашего приложения может быть сложной и может требовать определенного уровня экспертизы в веб-безопасности. Это может затруднить правильную настройку и использование teler-waf для тех, кто не знаком с брандмауэрами приложений и системами IDS.
- **Ограниченная защита**: teler-waf не является идеальным решением безопасности и может не защитить от всех возможных типов атак. Как и в случае с любой системой безопасности, важно регулярно отслеживать и обслуживать teler-waf, чтобы убедиться, что он обеспечивает желаемый уровень защиты.

#### Known Issues

Чтобы просмотреть список известных проблем с teler-waf, отфильтруйте проблемы по метке ["known-issue"](https://github.com/teler-sh/teler-waf/issues?q=is%3Aopen+is%3Aissue+label%3Aknown-issue).

## Community

Мы используем 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. Именно здесь мы активно управляем и решаем эти аспекты взаимодействия с сообществом.

## License

Этот пакет предоставляется под двойной лицензией: [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.