Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

wforce

Anti-Abuse for servers at authentication time
Project URLRSS FeedReport issues

253 downloads

253 latest version

4.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.4.0 (latest)
released Jun 28th 2023
This version is compatible with:
  • Puppet Enterprise 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'markt-wforce', '0.4.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add markt-wforce
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install markt-wforce --version 0.4.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: authentication, policy, wforce, weakforced, abuse

Documentation

markt/wforce — version 0.4.0 Jun 28th 2023

puppet-wforce

Build Status Puppet Forge Puppet Forge

Table of Contents

  1. Overview
  2. Requirements
  3. Usage
  4. Reference
  5. Development

Overview

This module will setup the weakforced Anti-Abuse server, also known as "wforce".

Requirements

  • Puppet 7 or higher
  • Access to wforce binary packages (either through a subscription or custom builds)

Usage

Beginning with wforce

Basic usage requires only a password for the wforce HTTP server:

class { 'wforce':
    password => 'secretpassword'
}

Furthermore, a number of simple options are available:

class { 'wforce':
    # Add networks to the access control list for the HTTP server.
    acls => [ '172.16.99.0/24', '10.100.200.0/24' ],

    # Change settings of the default databases (or add new databases).
    databases => {
      24HourDB => {
        max_size => 750000,
        v4prefix => 24,
      },
      MyDB => {
        window_size: 900
        num_windows: 32
        max_size: 500000
        field_map: 'default_field_map'
        replication: false
      },
    },

    # Replicate changes to db and blacklist to these hosts.
    siblings     => [ "10.99.0.1:4001:udp", "10.99.0.2:4001:udp", "10.99.0.3:4001:udp" ],
    siblings_key => 'anothersecretpassword',

    # On startup, try to replicate databases from the following host.
    sync_enable   => true,
    sync_host     => '10.99.0.1',
    sync_password => 'secretpassword',
    sync_uptime   => 3600,

    # Whitelist certain IP networks and hosts to avoid accidential blacklisting
    whitelist => [ "10.199.0.0/24", "10.222.0.123/32" ],
}

Test wforce

Use cURL to test if wforce is running and accepting authentication requests:

curl -X POST -H "Content-Type: application/json" --data '{"login":"user@example.com", "remote": "10.12.34.56", "pwhash":"1234"}' http://127.0.0.1:8084/?command=allow -u wforce:SECRETPASSWORD

Dovecot integration

Dovecot will use Basic Authentication when communicating with wforce, so we need to generate a base64 encoded authentication string:

echo -n 'wforce:secretpassword' | base64

Next add the following lines to dovecot.conf and restart dovecot afterwards:

auth_policy_server_url = http://localhost:8084/
auth_policy_hash_nonce = <insert_a_long_random_string_here>
auth_policy_server_api_header = Authorization: Basic <insert_base64_string_here>
auth_policy_server_timeout_msecs = 2000
auth_policy_hash_mech = sha256
auth_policy_request_attributes = login=%{requested_username} pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id} protocol=%s
auth_policy_reject_on_fail = no
auth_policy_hash_truncate = 8
auth_policy_check_before_auth = yes
auth_policy_check_after_auth = yes
auth_policy_report_after_auth = yes

Be sure to check the dovecot log to ensure that dovecot is able to communicate with wforce.

I recommend oxc/puppet-dovecot to manage dovecot.

Custom rules

This module contains the example rules from wforce's source distribution. They are not particular useful to block serious attacks, but they should give you an idea how wforce works.

Once you want to deploy your own rules, simply override the default ones:

wforce::functions:
  report: |+
    if (lt.success)
    then
      sdb:twAdd(lt.login, "countLogins", 1)
      sdb:twAdd(lt.remote, "countLogins", 1)
    end
...

Reference

Classes and parameters are documented in REFERENCE.md.

Development

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.