PlugAttack

When a rule triggers a throttle, the data map contains useful information for generating HTTP headers. Specifically:

• data[:limit]: The maximum allowed requests.
• data[:remaining]: The number of requests remaining in the current window.
• data[:expires_at]: The expiration time in Unix time milliseconds. To use this in the standard X-Ratelimit-Reset header, you must convert it to seconds by dividing by 1,000.

defp add_throttling_headers(conn, data) do
  # Convert milliseconds to seconds for the reset header
  reset = div(data[:expires_at], 1_000)
  conn
  |> put_resp_header("x-ratelimit-limit", to_string(data[:limit]))
  |> put_resp_header("x-ratelimit-remaining", to_string(data[:remaining]))
  |> put_resp_header("x-ratelimit-reset", to_string(reset))
end

Add plug_attack to your mix.exs dependencies to use the toolkit in your Elixir project.

def deps do
  [{:plug_attack, "~> 0.4.3"}]
end

Throttling requires a storage backend to be added to your application's supervision tree. PlugAttack.Storage.Ets is a common choice. You can configure a clean_period (in milliseconds) to manage memory by removing stale data.

children = [
  {PlugAttack.Storage.Ets, name: MyApp.PlugAttack.Storage, clean_period: 60_000}
]

To create a custom attack plug, use the PlugAttack module. You define rules using the rule/2 macro, which provides a connection (conn) and allows you to specify conditions for allowing or blocking requests using the allow/1 function.

Note on Proxies: If your application is behind a proxy (e.g., Nginx or Heroku), ensure you use a plug like remote_ip to correctly populate conn.remote_ip from X-Forwarded-For headers before using plug_attack.

defmodule MyApp.PlugAttack do
  use PlugAttack

  rule "allow local", conn do
    allow conn.remote_ip == {127, 0, 0, 1}
  end
end

PlugAttack.Storage.Ets is a storage implementation that uses a local ETS table to track throttling and fail2ban state. To use it, you must add it to your application's supervision tree.

When starting the process, you provide a unique name (an atom) which will be used to identify the ETS table and the registered process. You can also configure the :clean_period to control how often stale data is removed from memory.

Once started, you can pass this storage to various PlugAttack rules using the :storage option in the format: storage: {PlugAttack.Storage.Ets, YourStorageName}.

children = [
  # ...
  {PlugAttack.Storage.Ets, [MyApp.PlugAttackStorage]}
]

To use PlugAttack, include use PlugAttack in your module. This automatically implements the Plug behaviour and provides the rule/2 and rule/3 macros. You can also override the default behaviors for when a request is allowed or blocked by defining allow_action/3 and block_action/3.

defmodule MyApp.PlugAttack do
  import Plug.Conn
  use PlugAttack

  # Define rules here...

  # Optional: Customize what happens when a request is allowed
  def allow_action(conn, _data, _opts), do: conn

  # Optional: Customize what happens when a request is blocked
  def block_action(conn, _data, _opts) do
    conn
    |> send_resp(:forbidden, "Forbidden\n")
    |> halt
  end
end

To throttle requests, use the throttle/2 function within a rule. You must provide a storage backend (typically the ETS storage configured in your supervision tree).

Parameters for throttle/2:

• key: The identifier for the throttle (e.g., conn.remote_ip).
• period: The time window in milliseconds.
• limit: The maximum number of requests allowed within the period.
• storage: A tuple containing the storage module and its name, e.g., {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}.

rule "throttle by ip", conn do
  throttle conn.remote_ip,
    period: 60_000, limit: 10,
    storage: {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}
end

When calling PlugAttack.Storage.Ets.start_link/2, you can provide an options list to configure the cleanup frequency.

• :clean_period - The interval (in milliseconds) at which the ETS table is cleaned of stale data to limit memory consumption. Defaults to 5000 ms.

PlugAttack.Storage.Ets.start_link(MyApp.PlugAttackStorage, [clean_period: 10_000])

The block(value) rule is used to explicitly reject requests. If value is truthy, the request is blocked. If value is falsey, the rule is skipped and the next rule in the chain is evaluated.

PlugAttack.Rule.block(true)