Brute Force Protection

This feature allows you to define brute force buckets. A bucket is a container on Redis that will collect failed login attempts from remote clients. Each time a client fails the authentication process, the buckets are updated. If a bucket is full, a client is rejected directly without validating the credentials against password database backends.

A bucket has an expiration time stamp. As long as failed logins are stored, a bucket will be refreshed. A bucket will be removed from Redis, if no requests trigger the bucket and the TTL is expired.

You can define as many buckets as you want. A bucket has a name, a period, an indicator, if the bucket handles IPv4 or IPv6 IPs and a maximum allowed failed requests counter.

These buckets are independent of a user login name. They will count strictly each failed login request. Features like the realtime_blackhole_lists feature (and others) will also update the buckets directly.

If the brute_force feature recognizes a misconfigured MUA, it will not block the client forever!

Recommendation

If you define chains of buckets, user lower TTLs for buckets that hold IPs with a smaller IP range. Use higher TTLs for networks. See the example below.

Configuration Options

brute_force::buckets

Default: empty list

This section lists chains of buckets. Here is the definition of a bucket:

Field name	Description
name	A user friendly name for the bucket
period	The TTL after which an unused bucket is removed from Redis
cidr	The network mask of an IP address
ipv4	Boolean that enables the bucket for IPv4 support
ipv6	Boolean that enables the bucket for IPv6 support
failed_requests	Threshold value unitl a client will be blocked directly without asking authentication backends
filter_by_protocol	Optional list of protocols for which this bucket should be used (available from version 1.7.5)
filter_by_oidc_cid	Optional list of OIDC Client IDs for which this bucket should be used (available from version 1.7.5)

brute_force::ip_whitelist

Default: empty list

You can define a list of IPs and networks that are whitelisted from the brute_force feature.

brute_force:
  ip_whitelist:
    - 127.0.0.0/8
    - ::1
    - 192.168.0.0/16

brute_force::learning

By default, Nauthilus does not learn from features such as relay_domains or RBLs, as this could lead to incorrect learning. However, in environments where false positives can be ruled out, Nauthilus can also count violations in the buckets.

The learning parameter can include the following strings to enable learning:

• realtime_blackhole_lists
• cleartext_networks
• relay_domains
• brute_force
• lua

brute_force:
  learning:
    - realtime_blackhole_lists
    - lua

brute_force::tolerate_percent

Default: 0

This setting defines the percentage of failed login attempts that should be tolerated before blocking a client. This is useful for clients that might occasionally fail due to misconfiguration or user error.

brute_force:
  tolerate_percent: 20

brute_force::tolerate_ttl

Default: 24h

This setting defines the time-to-live for toleration entries. After this period, the toleration will expire.

brute_force:
  tolerate_ttl: 48h

brute_force::custom_tolerations

This section allows you to define custom toleration settings for specific IP addresses or networks.

brute_force:
  custom_tolerations:
    - ip_address: 192.168.1.0/24
      tolerate_percent: 30
      tolerate_ttl: 72h
    - ip_address: 10.0.0.5
      tolerate_percent: 50
      tolerate_ttl: 24h

Neural Network Configuration

brute_force::neural_network

This section configures the neural network machine learning system for brute force detection.

The machine learning approach enhances the traditional rule-based brute force detection by:

1. Learning from historical login patterns
2. Considering multiple features beyond just failed attempt counts
3. Adapting to different user behaviors
4. Potentially detecting attacks earlier based on subtle patterns

The system uses a weighted decision approach that combines both the traditional rule-based checks and the ML predictions:

• Static rule result is converted to a score (0.0 for not triggered, 1.0 for triggered)
• ML prediction provides a probability between 0.0 and 1.0
• These scores are weighted and combined (configurable weights)
• If the weighted score exceeds a threshold, the attempt is blocked

brute_force::neural_network::max_training_records

Default: 10000

This setting defines the maximum number of training records to keep for the neural network.

brute_force:
  neural_network:
    max_training_records: 20000

brute_force::neural_network::hidden_neurons

Default: 10

This setting defines the number of hidden neurons in the neural network.

brute_force:
  neural_network:
    hidden_neurons: 12

brute_force::neural_network::activation_function

Default: "sigmoid"

This setting defines the activation function to use in the neural network. Valid values are "sigmoid", "tanh", "relu", and "leaky_relu".

brute_force:
  neural_network:
    activation_function: "tanh"

brute_force::neural_network::static_weight

Default: 0.4

This setting defines the weight for static rules in the weighted decision.

brute_force:
  neural_network:
    static_weight: 0.5

brute_force::neural_network::ml_weight

Default: 0.6

This setting defines the weight for machine learning in the weighted decision.

brute_force:
  neural_network:
    ml_weight: 0.5

brute_force::neural_network::threshold

Default: 0.7

This setting defines the threshold for the weighted decision.

brute_force:
  neural_network:
    threshold: 0.8

brute_force::neural_network::learning_rate

Default: 0.01

This setting defines the learning rate for the neural network.

brute_force:
  neural_network:
    learning_rate: 0.005

Example Configuration

brute_force:
  ip_whitelist:
    - 127.0.0.0/8
    - ::1
    - 192.168.0.0/16
    - 172.16.0.0/12
    - 10.0.0.0/8
    - fd00::/8
    - 169.254.0.0/16
    - fe80::/10

  buckets:
    - name: b_1min_ipv4_32
      period: 60
      cidr: 32
      ipv4: true
      failed_requests: 10

    - name: b_1min_ipv6_128
      period: 60
      cidr: 128
      ipv6: true
      failed_requests: 10

    - name: b_1h_ipv4_24
      period: 3600
      cidr: 24
      ipv4: true
      failed_requests: 15

    - name: b_1h_ipv6_64
      period: 3600
      cidr: 64
      ipv6: true
      failed_requests: 15

    - name: b_1d_ipv4_24
      period: 86400
      cidr: 24
      ipv4: true
      failed_requests: 25

    - name: b_1d_ipv6_64
      period: 86400
      cidr: 64
      ipv6: true
      failed_requests: 25

    - name: b_1w_ipv4_24
      period: 604800
      cidr: 24
      ipv4: true
      failed_requests: 40

    - name: b_1w_ipv6_64
      period: 604800
      cidr: 64
      ipv6: true
      failed_requests: 40

    # Example of a protocol-specific bucket (available from version 1.7.5)
    - name: b_1h_imap_ipv4_24
      period: 3600
      cidr: 24
      ipv4: true
      failed_requests: 5
      filter_by_protocol:
        - imap
        - imaps

    # Example of an OIDC Client ID-specific bucket (available from version 1.7.5)
    - name: b_1h_oidc_client_ipv4_24
      period: 3600
      cidr: 24
      ipv4: true
      failed_requests: 3
      filter_by_oidc_cid:
        - my-oidc-client-id
        - another-client-id