Getting Started - JamesOwenHall/bfp GitHub Wiki

BFP is a tool designed to help recognize brute force attacks on the web. To get started download one of the pre-built binaries from the release page and place it on your server. In your download, you'll find an executable named bfp (bfp.exe on Windows) as well as a configuration file named config.json.

Configuration

In order for BFP to detect attacks, it needs to know which data it should track. Every different type of data you want to track is called a "direction". The application tracks each direction independently and notifies your web app whenever any value in any direction is being abused.

The most common directions to track are usernames, passwords and IP addresses. You can set these up by changing the "directions" array in the config.json file as follows.

  "directions": [
    {
      "name": "username",
      "type": "string",
      "window size": 10,
      "max hits": 3
    },
    {
      "name": "password",
      "type": "string",
      "window size": 3,
      "max hits": 3
    },
    {
      "name": "ip address",
      "type": "string",
      "window size": 10,
      "max hits": 3
    }
  ]

This configuration sets up BFP to track the three directions. Notice that each direction has a setting for window size and max hits. This defines how sensitive BFP will be to repeated requests. For the username direction, we're saying that we allow up to 3 requests for a username in any 10 second window. Similarly, we're saying that we want to allow no more than 3 requests in a 3 second window for the password direction.

Using it in your App

Before you can use BFP in your app, you need to download the API for the language you're using. Refer to the libs/ directory for the list of supported languages. Download the API for your language to use it in your app.

All of the APIs differ in their own way to best fit the target language, but they all have expose a function named hit. You call this function on every request that you want to track and it will return a boolean indicating if the request is safe or not. What you do with a flagged request is up to you. BFP does not enforce any countermeasures, it's merely a detection system. The most common course of action is requiring the user to complete a CAPTCHA before processing the request.