PlugAttack

https://hexdocs.pm/plug_attack/
Admin
PlugAttack is a plug building toolkit for blocking and throttling abusive requests in Elixir web...
Tokens:4,310
Snippets:42
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### PlugAttack Configuration Example

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

An example of how to configure PlugAttack within a Phoenix application, including defining custom allow and block actions.

```APIDOC
## PlugAttack Configuration Example

This snippet demonstrates how to integrate PlugAttack into your Elixir application by defining custom rules and actions.

### Description

This example shows a basic PlugAttack configuration. It defines a rule to allow requests from the local IP address and custom actions for when a request is allowed or blocked.

### Usage

To use this, you would typically include this module in your Plug pipeline.

### Code
```elixir
defmodule MyApp.PlugAttack do
  import Plug.Conn
  use PlugAttack

  # Define a rule to allow requests from localhost
  rule "allow local", conn do
    allow conn.remote_ip == {127, 0, 0, 1}
  end

  # Custom action when a request is allowed
  def allow_action(conn, _data, _opts), do: conn

  # Custom action when a request is blocked
  def block_action(conn, _data, _opts) do
    conn
    |> send_resp(:forbidden, "Forbidden\n")
    |> halt
  end
end
```
```

--------------------------------

### PlugAttack Rule Definitions

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Documentation on defining rules using the `rule/3` macro, including examples for allow, block, and throttle.

```APIDOC
## PlugAttack Rule Definitions

This section details how to define rules for PlugAttack using the `rule/3` macro.

### Description

The `rule/3` macro allows you to define conditions for allowing, blocking, or throttling requests. A rule is an expression that returns `{:allow, data}`, `{:block, data}`, or `nil`. If a rule matches, the corresponding `allow_action/3` or `block_action/3` callback is invoked.

### Functions

#### `rule(message, var \ quote do _ end, contents)`

- **message** (string) - A descriptive name for the rule.
- **var** (atom) - A variable representing the connection (typically `conn`).
- **contents** (quote do ... end) - The block containing the rule logic.

### Rule Actions

- **`allow(data)`**: Marks the request as allowed. `data` is passed to `allow_action/3`.
- **`block(data)`**: Marks the request as blocked. `data` is passed to `block_action/3`.
- **`throttle(key, opts)`**: Throttles requests based on a `key` (e.g., IP address, user ID) and options.

### Parameters for `throttle/2`

- **key** (term) - The identifier to throttle by (e.g., `conn.remote_ip`).
- **opts** (keyword list) - Options for throttling:
  - **`period`** (integer) - The time period in milliseconds.
  - **`limit`** (integer) - The maximum number of requests allowed within the period.
  - **`storage`** (tuple) - The storage implementation (e.g., `{PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}`).

### Examples

#### Allow Localhost
```elixir
rule "allow local", conn do
  allow conn.remote_ip == {127, 0, 0, 1}
end
```

#### Block Specific IP
```elixir
rule "block 1.2.3.4", conn do
  block conn.remote_ip == {1, 2, 3, 4}
end
```

#### Throttle Per IP
```elixir
rule "throttle per ip", conn do
  throttle conn.remote_ip,
    period: 1_000, limit: 5,
    storage: {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}
end
```

#### Throttle Login Requests
```elixir
rule "throttle login requests", conn do
  if conn.method == "POST" and conn.path_info == ["login"] do
    throttle conn.params["email"],
      period: 60_000, limit: 10,
      storage: {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}
  end
end
```
```

--------------------------------

### PlugAttack.Storage Module

Source: https://hexdocs.pm/plug_attack/index.html

Documentation for the storage backend behaviour and implementations.

```APIDOC
## PlugAttack.Storage

### Description
Behaviour for the storage backend for various rules.

## PlugAttack.Storage.Ets

### Description
Storage solution for PlugAttack using a local ets table.
```

--------------------------------

### PlugAttack.Storage Callbacks

Source: https://hexdocs.pm/plug_attack/PlugAttack.Storage.html

Interface definitions for storage backend implementations.

```APIDOC
## increment(opts, key, inc, expires_at)

### Description
Increments a counter for a given key.

### Parameters
- **opts** (opts()) - Required - Backend options
- **key** (key()) - Required - The storage key
- **inc** (integer()) - Required - The increment value
- **expires_at** (time()) - Required - Expiration time in milliseconds since unix epoch

### Response
- **integer** - The new value of the counter

## read(opts, key, now)

### Description
Reads a value from the storage.

### Parameters
- **opts** (opts()) - Required - Backend options
- **key** (key()) - Required - The storage key
- **now** (time()) - Required - Current time in milliseconds since unix epoch

### Response
- **{:ok, term()} | :error** - Returns the value if found, otherwise :error

## read_sliding_counter(opts, key, now)

### Description
Reads the current value of a sliding window counter.

### Parameters
- **opts** (opts()) - Required - Backend options
- **key** (key()) - Required - The storage key
- **now** (time()) - Required - Current time in milliseconds since unix epoch

### Response
- **non_neg_integer** - The current counter value

## write(opts, key, value, expires_at)

### Description
Writes a value to the storage.

### Parameters
- **opts** (opts()) - Required - Backend options
- **key** (key()) - Required - The storage key
- **value** (term()) - Required - The value to store
- **expires_at** (time()) - Required - Expiration time in milliseconds since unix epoch

### Response
- **:ok** - Success status

## write_sliding_counter(opts, key, now, expires_at)

### Description
Writes a sliding window counter entry.

### Parameters
- **opts** (opts()) - Required - Backend options
- **key** (key()) - Required - The storage key
- **now** (time()) - Required - Current time in milliseconds since unix epoch
- **expires_at** (time()) - Required - Expiration time in milliseconds since unix epoch

### Response
- **:ok** - Success status
```

--------------------------------

### PlugAttack Callbacks

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Documentation for the `allow_action/3` and `block_action/3` callbacks used by PlugAttack.

```APIDOC
## PlugAttack Callbacks

This section describes the callbacks that can be implemented to customize PlugAttack's behavior.

### Description

These callbacks are invoked when a rule matches and results in an allow or block action.

### Callbacks

#### `allow_action(conn, data, opts)`

- **Description**: Action performed when a request is allowed by a rule.
- **Parameters**:
  - `conn` (Plug.Conn.t()) - The current connection.
  - `data` (term) - The data returned from the `allow` macro in the rule.
  - `opts` (term) - Options passed from the plug initialization.
- **Returns**: `Plug.Conn.t()` - The modified connection.

#### `block_action(conn, data, opts)`

- **Description**: Action performed when a request is blocked by a rule.
- **Parameters**:
  - `conn` (Plug.Conn.t()) - The current connection.
  - `data` (term) - The data returned from the `block` macro in the rule.
  - `opts` (term) - Options passed from the plug initialization.
- **Returns**: `Plug.Conn.t()` - The modified connection.

### Default Behavior

- `allow_action/3`: Returns the connection unmodified.
- `block_action/3`: Responds with status 403 Forbidden, body "Forbidden\n", and halts the plug pipeline.
```

--------------------------------

### PlugAttack.Rule Module

Source: https://hexdocs.pm/plug_attack/index.html

Documentation for defining rules within the PlugAttack framework.

```APIDOC
## PlugAttack.Rule

### Description
Defines various rules that can be used inside the `PlugAttack.rule/2` macro.
```

--------------------------------

### PlugAttack Module Overview

Source: https://hexdocs.pm/plug_attack/index.html

Overview of the core PlugAttack module used for building request blocking and throttling logic.

```APIDOC
## PlugAttack

### Description
A plug building toolkit for blocking and throttling abusive requests.
```

--------------------------------

### Supervise PlugAttack.Storage.Ets

Source: https://hexdocs.pm/plug_attack/PlugAttack.Storage.Ets.html

Add the storage worker to your application's supervision tree to initialize the ETS table.

```elixir
children = [
  # ...
  worker(PlugAttack.Storage.Ets, [MyApp.PlugAttackStorage])
]
```

--------------------------------

### Define MyApp.PlugAttack Module

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Defines a custom PlugAttack module for MyApp, including rules for allowing local connections and custom actions for allowed and blocked requests.

```elixir
defmodule MyApp.PlugAttack do
  import Plug.Conn
  use PlugAttack

  # For more rules examples see PlugAttack.rule/2 macro documentation.
  rule "allow local", conn do
    allow conn.remote_ip == {127, 0, 0, 1}
  end

  # It's possible to customize what happens when conn is let through
  def allow_action(conn, _data, _opts), do: conn

  # Or when it's blocked
  def block_action(conn, _data, _opts) do
    conn
    |> send_resp(:forbidden, "Forbidden\n")
    |> halt
  end
end
```

--------------------------------

### PlugAttack Types

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Documentation on the return types for PlugAttack rules.

```APIDOC
## PlugAttack Types

This section describes the types returned by PlugAttack rules.

### Description

Rules in PlugAttack return specific values to indicate their outcome.

### Types

#### `rule()`

- **Description**: The return value of a rule definition.
- **Specs**: `rule() :: {:allow, term()} | {:block, term()} | nil`

- **Possible Values**:
  - `{:allow, term()}`: Indicates the request is allowed. The `term()` is passed to `allow_action/3`.
  - `{:block, term()}`: Indicates the request is blocked. The `term()` is passed to `block_action/3`.
  - `nil`: Indicates the rule did not match, and further rules should be evaluated.
```

--------------------------------

### throttle(key, opts)

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Implements a request throttling algorithm to limit the number of requests per client.

```APIDOC
## throttle(key, opts)

### Description
Implements a request throttling algorithm. If the `key` is falsey, throttling is not performed.

### Parameters
- **key** (term) - Required - Differentiates throttles (e.g., conn.remote_ip).
- **opts** (Keyword.t) - Required - Configuration options.

### Options
- **:storage** (tuple) - Required - PlugAttack.Storage implementation and options.
- **:limit** (integer) - Required - Max requests allowed in a period.
- **:period** (integer) - Required - Length of the period in milliseconds.
```

--------------------------------

### fail2ban(key, opts)

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Implements a fail2ban-inspired algorithm to block abusive clients based on request frequency.

```APIDOC
## fail2ban(key, opts)

### Description
Implements an algorithm inspired by fail2ban to catch misbehaving clients. If the `key` is falsey, the action is skipped.

### Parameters
- **key** (term) - Required - Differentiates clients (e.g., conn.remote_ip).
- **opts** (Keyword.t) - Required - Configuration options.

### Options
- **:storage** (tuple) - Required - PlugAttack.Storage implementation and options.
- **:period** (integer) - Required - Time window for counting abusive requests.
- **:limit** (integer) - Required - Max abusive requests allowed before banning.
- **:ban_for** (integer) - Required - Length of the ban in milliseconds.
```

--------------------------------

### PlugAttack Overview

Source: https://hexdocs.pm/plug_attack/api-reference.html

PlugAttack provides functionalities for request throttling and blocking. It includes modules for defining rules and managing storage backends.

```APIDOC
## PlugAttack Overview

PlugAttack is a plug building toolkit designed for blocking and throttling abusive requests. It offers a flexible way to manage request rates and prevent unwanted traffic.

### Modules

*   **PlugAttack.Rule**: Defines various rules that can be used within the `PlugAttack.rule/2` macro. These rules specify the conditions under which requests should be blocked or throttled.
*   **PlugAttack.Storage**: Defines the behaviour for the storage backend used by PlugAttack to store rule-related data. This allows for different storage implementations.
*   **PlugAttack.Storage.Ets**: A specific storage solution that utilizes a local ETS (Erlang Term Storage) table for efficient data management.
```

--------------------------------

### PlugAttack.Storage.Ets Functions

Source: https://hexdocs.pm/plug_attack/PlugAttack.Storage.Ets.html

Functions for managing the ETS storage table lifecycle and maintenance.

```APIDOC
## start_link(name, opts \\ [])

### Description
Starts the storage table and cleaner process. The process is registered under `name` and a public, named ets table with that name is created as well.

### Parameters
- **name** (atom) - Required - The name to register the process and ETS table under.
- **opts** (keyword list) - Optional - Configuration options.

#### Options
- **:clean_period** (integer) - Optional - How often the ets table should be cleaned of stale data (default: 5000 ms).

## clean(name)

### Description
Forcefully clean the storage.

### Parameters
- **name** (atom) - Required - The name of the storage process to clean.
```

--------------------------------

### Define a rule to allow local connections

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Defines a rule that allows requests originating from the local IP address (127.0.0.1). This is a common pattern for development or internal access.

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

--------------------------------

### Throttle login requests by email

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Throttles login requests based on the 'email' parameter in the request, limiting to 10 requests per minute. This rule only applies to POST requests to the '/login' path.

```elixir
rule "throttle login requests", conn do
  if conn.method == "POST" and conn.path_info == ["login"] do
    throttle conn.params["email"],
      period: 60_000, limit: 10,
      storage: {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}
  end
end
```

--------------------------------

### Define throttle rule

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Implements a request throttling algorithm based on a key and specified period/limit options.

```elixir
throttle(term(), Keyword.t()) :: PlugAttack.rule()
```

--------------------------------

### Define allow rule

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Allows a request if the provided value is truthy.

```elixir
allow(term()) :: PlugAttack.rule()
```

--------------------------------

### Define fail2ban rule

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Implements a fail2ban-inspired algorithm to block abusive clients based on a key and specified limits.

```elixir
fail2ban(term(), Keyword.t()) :: PlugAttack.rule()
```

--------------------------------

### Throttle requests per IP address

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Implements throttling for requests based on the IP address, limiting to 5 requests per second. Requires specifying the storage backend.

```elixir
rule "throttle per ip", conn do
  # throttle to 5 requests per second
  throttle conn.remote_ip,
    period: 1_000, limit: 5,
    storage: {PlugAttack.Storage.Ets, MyApp.PlugAttack.Storage}
end
```

--------------------------------

### allow(value)

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

A rule that allows a request to pass if the provided value is truthy.

```APIDOC
## allow(value)

### Description
The simplest rule that always allows the request to pass. If `value` is truthy the request is allowed, otherwise next rules are evaluated.

### Parameters
- **value** (term) - Required - The value to evaluate for truthiness.
```

--------------------------------

### Define a rule to block a specific IP address

Source: https://hexdocs.pm/plug_attack/PlugAttack.html

Defines a rule to block requests from a specific IP address (1.2.3.4). This is useful for blocking known malicious IPs.

```elixir
rule "block 1.2.3.4", conn do
  block conn.remote_ip == {1, 2, 3, 4}
end
```

--------------------------------

### Define block rule

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

Blocks a request if the provided value is truthy.

```elixir
block(term()) :: PlugAttack.rule()
```

--------------------------------

### block(value)

Source: https://hexdocs.pm/plug_attack/PlugAttack.Rule.html

A rule that blocks a request if the provided value is truthy.

```APIDOC
## block(value)

### Description
The simplest rule that always blocks the request. If `value` is truthy the request is blocked, otherwise next rules are evaluated.

### Parameters
- **value** (term) - Required - The value to evaluate for truthiness.
```
Tokens:
Raw