PhoenixDDoS

High performance application-layer DDoS protection for Elixir Phoenix.

Hex DocsCI StatusHex VersionApache 2 License

Table of contents

NoteYou are currently on unreleased branch. Latest stable release documentation is here

Features

Usage

phoenix_ddos is a high performance application-layer DDoS protection for Elixir Phoenix.

Installation

  1. Add :phoenix_ddos to your list of dependencies in mix.exs: 
def deps do
  [
    {:phoenix_ddos, "~> 1.1"},
    # Highly recommended, this will makes sure we get the correct remote_ip
    {:remote_ip, "~> 1.1"}
  ]
end
  1. Add the PhoenixDDoS plug to your app's Endpoint, after the excellent RemoteIp plug (optional but highly recommended !). 
defmodule MyApp.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app

  # put as high in the order as possible
  plug RemoteIp, headers: ["x-forwarded-for"]
  plug PhoenixDDoS

  # ...

end

Configuration

config :phoenix_ddos,
  safelist_ips: ["1.2.3.4", "5.6.7.0"],
  blocklist_ips: ["11.12.13.0"],
  protections: [
    # ip rate limit
    {PhoenixDDoS.IpRateLimit, allowed: 500, period: {2, :minutes}},
    {PhoenixDDoS.IpRateLimit, allowed: 10_000, period: {1, :hour}},
    # ip rate limit on specific request_path
    {PhoenixDDoS.IpRateLimitPerRequestPath,
     request_paths: ["/graphql"], allowed: 20, period: {1, :minute}},
    {PhoenixDDoS.IpRateLimitPerRequestPath,
     request_paths: [{:post, "/login"}], allowed: 5, period: {30, :seconds}}
  ]
Type Option Default Description
bool enabled true set false to disable
int jail_time {15, minutes} time an ip is fully blocked if caught by a protection. set nil to disable thus blocking instead
bool raise_on_reject false raise when we reject a connexion instead of returning an http code error
int http_code_on_reject 429 http code returned when we reject a connexion
list protections [] @see Protections examples
list safelist_ips [] bypass all protections ips
list blocklist_ips [] always blocked ips
bool on_jail_alert_to_sentry false notify slack when an ip get jailed

The configuration is per node you run, rate_limits are not shared (yet), but it gives you the best performance in case of an attack.

Examples with protection PhoenixDDoS.IpRateLimit

  1. 500 per minute max, if triggered ip will be in jail for 15 minutes 

    [{PhoenixDDoS.IpRateLimit, allowed: 500, period: {1, :minute}}]

  2. disable jail, ip will be throttle to 500 per minute 

    [{PhoenixDDoS.IpRateLimit, allowed: 500, period: {1, :minute}, jail_time: nil}]

Examples with protection PhoenixDDoS.IpRateLimitPerRequestPath

  1. single route /graphql with a 20 per minute max, if triggered ip will be in jail for 15 minutes 

     [{PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: ["/graphql"], allowed: 20, period: {1, :minute}}]

  2. you can also give a phoenix-like path 

     [{PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: ["/admin/:id/dashboard"], allowed: 20, period: {1, :minute}}]

  3. you can also specify method 

     [
   {PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: [{:post, "/login"}, {:post, "/logout"}], allowed: 5, period: {1, :minute}},
   {PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: [{:get, "/login"}], allowed: 100, period: {5, :minute}}
 ]

  4. multiple route consuming same quota 

     [{PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: ["/graphql", "/graphiql"], allowed: 20, shared: true, period: {1, :minute}}]

  5. multiple route consuming independent quota 

     [{PhoenixDDoS.IpRateLimitPerRequestPath,
  request_paths: ["/graphql", "/graphiql"], allowed: 20, period: {1, :minute}}]

is equivalent to:

  [
   {PhoenixDDoS.IpRateLimitPerRequestPath,
    request_paths: ["/graphql"], allowed: 20, period: {1, :minute}},
   {PhoenixDDoS.IpRateLimitPerRequestPath,
    request_paths: ["/graphiql"], allowed: 20, period: {1, :minute}}
  ]

Community

Slack: join elixir-lang and join channel #phoenix_ddos

FAQ

Why would I need this compared to a system like cloudflare or a reverse proxy with a fail2ban ?

The best ddos protection is like any protection: you have to have multiple layers of protection, each layer having its own advantage or disadvantage. In that matter, to maximize protection you should use one system per layer.

Also we have to keep in mind that a lot of projects don't have the capability (running in a PaaS like heroku for instance) or the will to have all these systems in place. Since phoenix_ddos is a plug-and-play (pun intended) library with minimum configuration, it is a great value for a minimum of effort.

What is a multi-layer ddos protection and why this is important ?

phoenix_ddos is the application layer, running in the application itself. It advantage is that is knows the inside of the application and its limits and can act on the details, where a cloudflare or a ngnix fail2ban would manage most of the load, but the traffic that still access your application may still kill it, this is then the responsability of phoenix_ddos.

Example of a phoenix application cluster: e.g. 10 pods running each the same phoenix application:

Other layers will protect the entire cluster and phoenix_ddos will protect each phoenix application individually.

Since one phoenix application have its own limits, it is best to have a throttle at this layer.

If the cluster scale up or down (switching to 3 pods or 30 pods), other layers will never adapt their throttle values, but phoenix_ddos will scale its protection gracefully.

Comparaison with an home electrical installation:

In home installation, you have 2 layers of protection doing the exact same thing:

Next in roadmap

Later in roadmap

Contributing

Create issues on github for any bug or issue.

To contribute on the code, please clone and use following tools:

run tests

mix test

run release code validation

mix ci