## Uso

> [!WARNING]
> **Aviso de descontinuação**: As exclusões de ameaças (`Excludes`) serão descontinuadas na próxima versão (**v2**). Veja [#73](https://github.com/teler-sh/teler-waf/discussions/73) & [#64](https://github.com/teler-sh/teler-waf/issues/64).

Aqui está um exemplo de como usar o teler-waf em uma aplicação Go:

1. Importe o pacote teler-waf no seu código Go:```go
import "github.com/teler-sh/teler-waf"

3. Use o método `Handler` da instância `Teler` para criar um `net/http.Handler`. Este handler pode então ser usado no roteamento HTTP da sua aplicação para aplicar as medidas de segurança do teler-waf a rotas específicas.```go
handler := waf.Handler(http.HandlerFunc(yourHandlerFunc))

Isso é tudo! Você configurou o teler-waf em sua aplicação Go.

**Opções:**

Para uma lista das opções disponíveis para personalizar o teler-waf, veja a estrutura [`teler.Options`](https://pkg.go.dev/github.com/teler-sh/teler-waf#Options).

### Exemplos

Aqui está um exemplo de como personalizar as opções e regras para o 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]
> Por favor, note que os parâmetros `condition`, `method` e `element` são opcionais. Os valores padrão atribuídos a eles são os seguintes: `condition` é definido como **or**, `method` é definido como **ALL** e `element` é definido como **ANY**. Portanto, se desejado, você pode deixar esses parâmetros vazios. O parâmetro `pattern` é obrigatório, a menos que você especifique uma expressão `dsl`. Nesses casos, quando uma expressão `dsl` é fornecida, o teler-waf ignorará quaisquer valores atribuídos a `method` e `element`, mesmo que estejam definidos. Para ver alguns exemplos, consulte o diretório [`tests/rules/`](https://github.com/teler-sh/teler-waf/tree/master/tests/rules/valid).

Você pode especificar a opção `CustomsFromFile` com o caminho real do arquivo ou padrão glob apontando para a localização dos seus arquivos de regras personalizadas. Por exemplo:```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",
})

Verifique se o método da requisição recebida é "GET":```sql
request.Method == "GET"

Verifique se o endereço IP da solicitação recebida é do localhost:```sql
request.IP in ["127.0.0.1", "::1", "0.0.0.0"]

Verifique se o corpo da requisição recebida contém 'foo':```sql
request.Body contains "foo"

Esses exemplos fornecem uma visão sobre as capacidades expressivas das expressões DSL, permitindo definir condições intrincadas com base em vários atributos da requisição. Ao aproveitar essas expressões, você pode efetivamente definir os critérios para avaliar requisições recebidas e adaptar suas regras personalizadas ou listas de permissão de acordo, possibilitando um controle refinado sobre o comportamento da sua aplicação.

#### Variáveis disponíveis

Ao trabalhar com expressões DSL, você tem acesso a várias variáveis que fornecem informações valiosas sobre as requisições recebidas e a categoria de ameaça que está sendo analisada. Aqui está uma descrição detalhada das variáveis disponíveis:

- **Categoria de ameaça**

	Todos os identificadores constantes do tipo `threat.Threat` podem ser usados como variáveis válidas. Esses identificadores representam diferentes categorias de ameaça relevantes para sua análise.

- **`request`**

	A variável `request` representa a requisição recebida e fornece acesso aos seus campos e valores correspondentes. As seguintes subvariáveis estão disponíveis dentro da variável `request`:

  - `request.URI`: Representa a URI da requisição recebida, incluindo caminho, consultas, parâmetros e fragmentos.
  - `request.Headers`: Representa os cabeçalhos da requisição recebida, apresentados em várias linhas.
  - `request.Body`: Representa o corpo da requisição recebida.
  - `request.Method`: Representa o método da requisição recebida.
  - `request.IP`: Representa o endereço IP do cliente associado à requisição recebida.
  - `request.ALL`: Representa todos os valores de string dos campos de requisição mencionados acima em uma fatia.

- **`threat`**

	A variável `threat` representa a categoria de ameaça que está sendo analisada. Ela é do tipo `threat.Threat` e permite avaliar e tomar decisões com base na categoria de ameaça específica associada à requisição.

Ao utilizar essas variáveis em suas expressões DSL, você pode efetivamente acessar e manipular os atributos das requisições recebidas e avaliar as categorias de ameaça relevantes. Isso permite criar condições de regras personalizadas<!-- e listas de permissão--> adaptadas ao seu caso de uso específico.

#### Funções disponíveis

Além disso, você tem acesso a uma variedade de funções. Essas funções abrangem tanto as [funções internas](https://expr.medv.io/docs/Language-Definition#built-in-functions) fornecidas pelo pacote expr quanto aquelas especificamente definidas dentro do pacote DSL. As funções utilizam as funcionalidades oferecidas pelo pacote `strings` embutido do Go. Aqui está uma lista detalhada das funções disponíveis:

- `cidr`: Obter todos os endereços IP em um intervalo com determinado CIDR.
- `clone`: Criar uma cópia de uma string.
- `containsAny`: Verificar se uma string contém alguma das substrings especificadas.
- `equalFold`: Comparar duas strings de maneira que não diferencie maiúsculas de minúsculas.
- `hasPrefix`: Verificar se uma string possui um prefixo especificado.
- `hasSuffix`: Verificar se uma string possui um sufixo especificado.
- `join`: Concatenar várias strings usando um separador especificado.
- `repeat`: Repetir uma string um número especificado de vezes.
- `replace`: Substituir ocorrências de uma substring dentro de uma string.
- `replaceAll`: Substituir todas as ocorrências de uma substring dentro de uma string.
- `request`: Acessar informações específicas da requisição dentro da expressão DSL.
- `threat`: Acessar informações relacionadas à categoria de ameaça que está sendo analisada.
- `title`: Converter uma string para o formato de título.
- `toLower`: Converter uma string para minúsculas.
- `toTitle`: Converter uma string para o formato de título.
- `toUpper`: Converter uma string para maiúsculas.
- `toValidUTF8`: Converter uma string para uma string codificada em UTF-8 válida.
- `trim`: Remover espaços em branco no início e no final de uma string.
- `trimLeft`: Remover espaços em branco no início de uma string.
- `trimPrefix`: Remover um prefixo especificado de uma string.
- `trimRight`: Remover espaços em branco no final de uma string.
- `trimSpace`: Remover espaços em branco no início e final e colapsar espaços em branco consecutivos dentro de uma string.
- `trimSuffix`: Remover um sufixo especificado de uma string.

Para mais detalhes abrangentes sobre operadores e funções internas, consulte a [documentação do Expr](https://expr.medv.io/docs/Getting-Started). Ela fornece um guia completo para utilizar operadores e explorar as funções internas disponíveis em suas expressões DSL.

### Gerenciamento de Configuração Simplificado

Para uma configuração eficaz, é essencial definir uma gama de configurações, incluindo listas de permissão, definições de regras personalizadas, preferências de registro e outros parâmetros. O pacote [`option`](https://pkg.go.dev/github.com/teler-sh/teler-waf/option) simplifica esse fluxo de trabalho de configuração ao permitir que você deserialize ou carregue eficientemente dados de configuração dos formatos JSON e YAML em um formato que o teler-waf possa compreender e implementar prontamente.```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)

### Logs

Aqui está um exemplo de como as linhas de log se pareceriam se o teler-waf detectasse uma ameaça em uma requisição:```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":""}}

// Using Status, HTML, or HTMLFile options
waf := teler.New(teler.Options{
    // ...
    Response: &teler.Response{
        Status: 418,
        HTML:   "<html><body><h1>I'm a teapot</h1></body></html>",
    },
})
``````go
// Create a new instance of the Teler middleware
telerMiddleware := teler.New(teler.Options{
	// Customize the response for rejected requests
	Response: teler.Response{
		Status: 403,
		HTML: "Your request has been denied for security reasons. Ref ID: {{ID}}.",
		// Alternatively, you can use HTMLFile to point to a custom HTML file
		HTMLFile: "/path/to/custom-403.html",
	},
})

Depois de configurar essa integração, todas as ameaças detectadas pelo teler-waf serão enviadas para o Falco Sidekick, que poderá então tomar as ações adequadas com base na configuração definida. Por exemplo, você pode configurar o Falco Sidekick para enviar automaticamente alertas para sua equipe de resposta a incidentes.

<a href="#"><img src="https://assets.kitploit.com/production/public/readmes/6952/c5ac9fbaf071322c4981c45c53a1fe81d2b2c58f11d567c8ca148badbd38a9df.png" alt="Evento do Falco Sidekick do teler-waf" width="400px"></a>

#### **Evento**

O evento encaminhado para a instância do Falco Sidekick inclui as seguintes informações:

* **`output`**: Representa a mensagem de alerta.
* **`priority`**: A prioridade é consistentemente denotada como **aviso**, uma alusão à urgência associada a eventos relacionados à segurança.
* **`rule`**: Indica a regra específica _(mensagem)_ que correspondeu à requisição associada.
* **`time`**: Timestamp de geração do evento.
* Campos de saída:
	* **`teler.caller`**: Identifica a fonte da aplicação que invocou o teler-waf.
	* **`teler.id`**: Representa um identificador único para a requisição rejeitada.
	* **`teler.threat`**: Especifica a categoria da ameaça.
  * **`teler.listen_addr`**: Denota o endereço de rede no qual o teler-waf está escutando requisições recebidas.
	* **`request.body`**: Contém o corpo da requisição associada.
	* **`request.headers`**: Lista os cabeçalhos da requisição associada.
	* **`request.ip_addr`**: Revela o endereço IP da requisição associada.
	* **`request.method`**: Informa o método HTTP empregado na requisição associada.
	* **`request.path`**: Refere-se ao caminho da requisição associada.

No geral, o Falco Sidekick é uma ferramenta versátil que pode ajudar a automatizar seu processo de resposta a incidentes e melhorar sua postura geral de segurança. Ao aproveitar seus recursos, você pode garantir que suas aplicações nativas em nuvem estejam seguras e protegidas contra ameaças potenciais.

### Wazuh

Você pode aprimorar seu monitoramento de segurança integrando os logs do teler WAF ao Wazuh. Para fazer isso, utilize as [regras personalizadas](https://documentation.wazuh.com/current/user-manual/ruleset/rules/custom.html) disponíveis no diretório [`extras/`](https://github.com/teler-sh/teler-waf/blob/HEAD/extras).

Adicione o bloco do elemento `localfile` abaixo dentro do elemento `ossec_config` no arquivo de [configuração local](https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/index.html):```xml
<ossec_config>
  <!-- ... -->
  <localfile>
    <log_format>syslog</log_format>
    <location>/path/to/your/teler.log</location>
  </localfile>
</ossec_config>

Finalmente, podem haver casos em que é necessário carregar o conjunto de dados de ameaças na memória em vez de salvá-lo em um diretório de cache no nível do usuário. Isso pode ser particularmente útil se você estiver executando o aplicativo ou serviço em uma imagem distroless ou de runtime, onde o acesso a arquivos pode ser limitado ou lento. Nesse cenário, você pode definir uma opção chamada **InMemory** como `true`, o que carregará o conjunto de dados de ameaças na memória para acesso mais rápido.```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]
> Os resultados de benchmarking podem variar e podem não ser consistentes. O conjunto de dados [teler-resources](https://github.com/teler-sh/teler-resources) pode ter aumentado desde então, o que pode impactar os resultados.

- **Complexidade de configuração**: Configurar o teler-waf para atender às necessidades específicas da sua aplicação pode ser complexo e pode exigir um certo nível de especialização em segurança web. Isso pode dificultar que aqueles que não estão familiarizados com firewalls de aplicação e sistemas IDS configurem e usem corretamente o teler-waf.
- **Proteção limitada**: o teler-waf não é uma solução de segurança perfeita e pode não ser capaz de proteger contra todos os tipos possíveis de ataques. Como em qualquer sistema de segurança, é importante monitorar e manter regularmente o teler-waf para garantir que esteja fornecendo o nível de proteção desejado.

#### Problemas Conhecidos

Para visualizar uma lista de problemas conhecidos com o teler-waf, filtre as issues pela [etiqueta "known-issue"](https://github.com/teler-sh/teler-waf/issues?q=is%3Aopen+is%3Aissue+label%3Aknown-issue).

## Comunidade

Nós utilizamos o Google Groups como nossa lista de e-mails dedicada. Inscreva-se no [teler-announce](https://groups.google.com/g/teler-announce) através do [[email protected]](mailto:[email protected]) para anúncios importantes, como a disponibilidade de novas versões. Esta inscrição manterá você informado sobre desenvolvimentos significativos relacionados ao [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) e [teler Resources](https://github.com/teler-sh/teler-resources).

Quaisquer [dúvidas](https://github.com/teler-sh/teler-waf/discussions/categories/q-a), [discussões](https://github.com/teler-sh/teler-waf/discussions) ou [problemas](https://github.com/teler-sh/teler-waf/issues) são rastreados aqui no GitHub. É aqui que gerenciamos e abordamos ativamente esses aspectos do nosso engajamento com a comunidade.

## Licença

Este pacote é disponibilizado sob uma licença dupla: a [Apache License 2.0](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-APACHE) e a [Elastic License 2.0 (ELv2)](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC) (para o pacote principal, **teler**).

Você pode usá-lo livremente dentro da sua organização para proteger suas aplicações. No entanto, você não pode usar o pacote principal para criar um serviço em nuvem, hospedado ou gerenciado, nem para qualquer finalidade comercial, pois precisaria de uma licença comercial para isso – embora esta opção não esteja disponível atualmente. Se você estiver interessado em obter essa licença comercial para usos não autorizados pela [ELv2](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC), entre em contato com **@dwisiswant0**.

o teler-waf e quaisquer contribuições são direitos autorais © de Dwi Siswanto 2022-2024.