Phx2Ban (Phx2Ban v0.2.2)

This module defines the supervision tree that contains all of the Phx2Ban components. By adding this to your application's own supervision tree prior to your Phoenix endpoint module, you will be able to start analyzing inbound traffic for malicious requests. You can either configure Phx2Ban by passing your configuration options to the supervisor, or you can define the configuration options in your config.exs file. If you have options defined in both places, the options passed to the supervisor take precedence. You can see all of the supported options by looking at the Phx2Ban.FirewallConfig moduledocs.

As an example so you can see how you can configure the via the supervisor entry, let's pretend that you want to adjust the block duration for a requesting IP address and also the threshold for when IP addresses are blocked. You could do something like the following in your application.ex file:

def start(type, args) do
  children = [
    ...

    # Start Phx2Ban before you start your Endpoint.
    {Phx2Ban, router: MyAppWeb.Router, block_duration: 86_400, malicious_req_threshold: 5},
    MyAppWeb.Endpoint
  ]
end

Be sure to take a look at all of the available options in Phx2Ban.FirewallConfig and tune Phx2Ban to your specific needs.

Summary

Types

ip_address_query()
ip_address_status()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

ip_address_status(remote_ip)

This function returns the status of the provided IP address. If the provided IP address has made malicious requests but has not hit the block threshold, this function will return the following tuple: {:warning, <malicious_request_count>}. If the IP address is banned, the function will return {:blocked, <block_time_remaining_in_seconds>}. If the IP address does not exist on the block list, the function will return :safe. If an invalid IP address is provided, then :invalid_ip_address is returned.

manually_block_ip_address(remote_ip)

If your application has some other way of profiling bad actors and you would like to manually add IPv4 addresses to the block list, you can use this function to do so. The same rules will apply to this entry as with other entries. For example, when the manually added entry hits the configured :block_duration then it will be cleared out from the block list.

Types

Link to this type

ip_address_query()

@type ip_address_query() :: String.t() | Plug.Conn.t() | tuple()
Link to this type

ip_address_status()

@type ip_address_status() ::
  {:blocked, non_neg_integer()}
  | {:warning, non_neg_integer()}
  | :safe
  | {:error, :missing_ip_address}
  | {:error, :invalid_ip_address}

Functions

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

ip_address_status(remote_ip)

@spec ip_address_status(ip_address :: ip_address_query()) :: ip_address_status()

This function returns the status of the provided IP address. If the provided IP address has made malicious requests but has not hit the block threshold, this function will return the following tuple: {:warning, <malicious_request_count>}. If the IP address is banned, the function will return {:blocked, <block_time_remaining_in_seconds>}. If the IP address does not exist on the block list, the function will return :safe. If an invalid IP address is provided, then :invalid_ip_address is returned.

Link to this function

manually_block_ip_address(remote_ip)

@spec manually_block_ip_address(ip_address :: ip_address_query()) ::
  :ok | {:error, :invalid_ip_address}

If your application has some other way of profiling bad actors and you would like to manually add IPv4 addresses to the block list, you can use this function to do so. The same rules will apply to this entry as with other entries. For example, when the manually added entry hits the configured :block_duration then it will be cleared out from the block list.