# `Caracola.RateLimit`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/rate_limit.ex#L1)

Rate limiting and banning of abusive clients: request rate limits per
address and per user, and bans of SIP scanners and of addresses with too
many failed authentications (brute-force attacks).

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.RateLimit, Caracola.Registrar],
    sip: [listen: "sip:all:5060"],
    rate_limit: [per_ip: {50, 1000}, per_user: {10, 1000}, exempt: ["10.0.0.0/8"]]
end
```

Requests are checked in the transport process, as soon as they are
received and before a call process is started for them, so rejecting
them is cheap. For each request:

  1. Requests from `:exempt` addresses are accepted.
  2. Requests from banned addresses are dropped silently.
  3. Requests with the `User-Agent` of a known scanner (`:scanners`) are
     dropped, and their address is banned.
  4. If the address (`:per_ip`) or the user of the From header
     (`:per_user`) sent too many requests, the request is rejected with
     the `:reply` (a 503 with `Retry-After` by default, or `:drop`).

ACKs are never rejected (only dropped if banned) and are not counted.
Limits are given as `{requests, milliseconds}`, and counted in fixed
windows of that time.

Requests whose digest credentials are wrong (`{{:digest, realm}, false}`
in `sip_authorize/3`) count as authentication failures of their
address, which is banned when there are too many of them
(`:auth_failures`). Bans last `:ban_time` milliseconds, see also
`ban/3` and `unban/2`.

Rejections and bans emit the `[:caracola, :rate_limit, :reject]` and
`[:caracola, :rate_limit, :ban]` telemetry events, with a `:count` (or
`:time`) measurement and the `:service`, `:ip` and `:reason` (`:per_ip`,
`:per_user`, `:banned`, `:scanner` or `:auth_failures`) as metadata.

The plugin should be the first one of the service, so that its
`sip_authorize/3` hook sees the result of the authentication before
other plugins.

## Configuration

Under the `:rate_limit` key:

  * `:per_ip` - requests per address, as `{requests, ms}` (default
    `{100, 1000}`), `nil` for no limit.
  * `:per_user` - requests per user of the From header (default `nil`).
  * `:auth_failures` - authentication failures per address before it is
    banned (default `{10, 60_000}`), `nil` for no bans.
  * `:scanners` - fragments of the `User-Agent` of scanners
    (case-insensitive), banned at once. The default list has
    `friendly-scanner`, `sipvicious`, `sipcli` and other common ones;
    `[]` disables it.
  * `:ban_time` - duration of bans, in milliseconds (default 600000).
  * `:exempt` - addresses with no limits nor bans, as `10.0.0.0/8` or
    `192.0.2.1` (default `[]`).
  * `:reply` - reply to the requests over a limit (default a 503 with
    `Retry-After: 5`), or `:drop` to discard them.

# `ban`

```elixir
@spec ban(module(), :inet.ip_address(), pos_integer() | nil) :: :ok
```

Bans an address for `time` milliseconds (the `:ban_time` by default).

# `banned?`

```elixir
@spec banned?(module(), :inet.ip_address()) :: boolean()
```

Returns `true` if an address is banned.

# `bans`

```elixir
@spec bans(module()) :: [{:inet.ip_address(), non_neg_integer()}]
```

The banned addresses, with the milliseconds left.

# `clear`

```elixir
@spec clear(module()) :: :ok
```

Removes all the counters and bans of a service.

# `unban`

```elixir
@spec unban(module(), :inet.ip_address()) :: :ok
```

Removes the ban of an address.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
