Caracola.RateLimit (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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.

Summary

Functions

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

Returns true if an address is banned.

The banned addresses, with the milliseconds left.

Removes all the counters and bans of a service.

Removes the ban of an address.

Functions

ban(service, ip, time \\ nil)

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

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

banned?(service, ip)

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

Returns true if an address is banned.

bans(service)

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

The banned addresses, with the milliseconds left.

clear(service)

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

Removes all the counters and bans of a service.

unban(service, ip)

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

Removes the ban of an address.