crowdsec

Management of a crowdsec infrastructure using puppet.

Table of Contents

1. Description
2. Setup - The basics of getting started with crowdsec
   • What crowdsec affects
   • Setup requirements
   • Beginning with crowdsec
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

bzed-crowdsec installs and manages crowdsec. The current state is: deep in development. Some basic functions, more to come. Send patches!

Setup

Beginning with crowdsec

FIXME

Usage

FIXME

Reference

An html version of the reference is available here: https://bzed.github.io/bzed-crowdsec/ There is also a markdown version in REFERENCE.md

Limitations

THIS MODULE IS FAR FROM FINISHED

Development

Please use the github issue tracker and send pull requests. Make sure that your pull requests keep pdk validate/test unit happy!

For a release:

• Update gh_pages:

  bundle exec rake strings:gh_pages:update
  

• Update REFERENCE.md:

  puppet strings generate --format markdown --out REFERENCE.md
  

• Release:

  pdk build
  

• Bump version number: bump/change the version in metadata.json.

Support and help

There is no official commercial support for this puppet module, but I'm happy to help you if you open a bug in the issue tracker. Please make sure to add enough information about what you have done so far and how your setup looks like. I'm also reachable by email. Use GPG to encrypt confidential data:

ECA1 E3F2 8E11 2432 D485  DD95 EB36 171A 6FF9 435F

If you are happy, I also have an amazon wishlist :)

Reference

Table of Contents

Classes

• crowdsec: Install and manage crowdsec
• crowdsec::local_api: A short summary of the purpose of this class
• crowdsec::params: The params class defines some basic defaults for crowdsec.
• crowdsec::sources: configure crowdsec repositories

Defined types

• crowdsec::local_api::register: Registers a machine at the local apu
• crowdsec::module: Install crowdsec modules from the hub.

Data types

• Crowdsec::Module_name
• Crowdsec::Module_type

Classes

crowdsec

The whole config part that should go into config.yaml.local. $config['api']['server']['enable'] is overwritten in case $local_api_puppet_certname is set and == $trusted['certname']

Setup apt sources from the crowdsec repositories. Defaults to true.

The local api url crowdsec should connect to. Defaults to http://127.0.0.1:8080

The login/user used to authenticate against the local api server.

The password used to login on the local api server.

Use a hash over fqdn and password instead of the puppet certname. This sounds weird, but it makes sure that we update user/password in case the password changes. There is not way to verify an existing password unfortunately. Don't disable if you plan to connect to the central API.

If this option is set and matches $trusted['certname'], enable the local api and collect host registrations exported for that certname.

Nobody reads the documentation. If you actually did so, raise this number: 0 Pull requests for it are fine!

Set this to true if you really want to run the local api server without TLS. Absolutely not recommended.

Register machine automatically if $local_api_url and $local_api_puppet_certname is configured properly.

Configure crowdsec to run as LAPI server

Defaults to true, when false we configure a user/group for crowdsec.

Update packages from the crowdsec hub automatically. Defaults to true.

Base directory for all crowdsec config files.

Name of the service used to control the crowdsec daemon.

Remove modules/configs that are not installed by puppet. Keep in mind that this will break collections - you will have to list everything contained by a collection manually.

Either the name of the module or an array, containing the module name and all the params to pass to crowdsec::module to install the module.

See parsers

See parsers

See parsers

See parsers

See parsers

See parsers

Examples

include crowdsec

Parameters

The following parameters are available in the crowdsec class:

• config
• manage_sources
• local_api_url
• local_api_login
• local_api_password
• use_anonymous_api_logins
• local_api_puppet_certname
• force_local_api_no_tls
• register_machine
• enable_local_api
• run_as_root
• automatic_hub_updates
• config_basedir
• service_name
• manage_modules
• parsers
• postoverflows
• scenarios
• contexts
• appsec_configs
• appsec_rules
• collections

config

Data type: Hash

Default value: {}

manage_sources

Data type: Boolean

Default value: true

local_api_url

Data type: Stdlib::HTTPUrl

Default value: 'http://127.0.0.1:8080'

local_api_login

Data type: String

Default value:

if $use_anonymous_api_logins {
    sha256("${trusted['certname']} ${local_api_password}")
  } else {
    $trusted['certname']

local_api_password

Data type: Sensitive[String]

Default value:

Sensitive(
    fqdn_rand_string(
      32,
      undef,
      $facts['networking']['mac'],
    )
  )

use_anonymous_api_logins

Data type: Boolean

Default value: true

local_api_puppet_certname

Data type: Optional[Stdlib::Fqdn]

Default value: undef

force_local_api_no_tls

Data type: Boolean

Default value: false

register_machine

Data type: Boolean

Default value: ($local_api_url != 'http://127.0.0.1:8080') and $local_api_puppet_certname

enable_local_api

Data type: Boolean

Default value: $local_api_puppet_certname and $local_api_puppet_certname == $trusted['certname']

run_as_root

Data type: Boolean

Default value: !$enable_local_api

automatic_hub_updates

Data type: Boolean

Default value: true

config_basedir

Data type: Stdlib::Absolutepath

Default value: $crowdsec::params::config_basedir

service_name

Data type: String

Default value: $crowdsec::params::service_name

manage_modules

Data type: Boolean

Default value: false

parsers

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

postoverflows

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

scenarios

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

contexts

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

appsec_configs

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

appsec_rules

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value: []

collections

Data type: Tuple[Variant[Crowdsec::Module_name, Tuple[Crowdsec::Module_name, Hash, 2, 2]], 0]

Default value:

[
    'crowdsecurity/linux',
    'crowdsecurity/sshd',
  ]

crowdsec::local_api

A description of what this class does

Examples

include crowdsec::local_api

crowdsec::params

The params class defines some basic defaults for crowdsec.

Examples

include crowdsec::params

crowdsec::sources

setup apt sources lists and necessary keys.

Examples

include crowdsec::sources

Parameters

The following parameters are available in the crowdsec::sources class:

• keyring_source
• include_sources

keyring_source

Data type: String

Default value: 'puppet:///modules/crowdsec/crowdsec-archive-keyring.gpg'

include_sources

Data type: Boolean

Default value: false

Defined types

crowdsec::local_api::register

Registering machines at the local api is done using puppetdb_query, so we only collect exported ressources. Don't try to use this define directly.

Examples

@@crowdsec::local_api::register { 'namevar':
  password => 'mysecret',
}

Parameters

The following parameters are available in the crowdsec::local_api::register defined type:

• password
• machine_id

password

Data type: String

machine_id

Data type: String

Default value: $name

crowdsec::module

This rather generic defined_type allows to install all the different crowdsec parts that come directly from the crowdsec hub.

• parsers
• postoverflows
• scenarios
• contexts
• appsec-configs
• appsec-rules
• collections

Required parameter to specify the type of module to install from the hub (parsers, collections, .....)

Set to 'present' to install, 'absent' to uninstall.

Hash to specify necessay install options like API keys for the hub. { 'foo' => 'bar' } results in --foo bar being pass as option to cscli .... install.

Defaults to $name. Sets the name of the hub module to install/uninstall.

Module is not from the hub, use this source as source for the file.

Module is not from the hub, use this content for the file.

"module_subtype" of the module, for example s01-parse to install in crowdsec/parsers/s01-parse

Examples

crowdsec::module { 'crowdsecurity/ssh-bf':
  type => 'collections',
}

Parameters

The following parameters are available in the crowdsec::module defined type:

• module_type
• ensure
• install_options
• module
• source
• content
• module_subtype

module_type

Data type: Crowdsec::Module_type

ensure

Data type: Enum['present', 'absent']

Default value: 'present'

install_options

Data type: Hash[Pattern[/[a-z]+/], String]

Default value: {}

module

Data type: Crowdsec::Module_name

Default value: $name

source

Data type: Optional[String]

Default value: undef

content

Data type: Optional[String]

Default value: undef

module_subtype

Data type: Optional[String]

Default value: undef

Data types

Crowdsec::Module_name

The Crowdsec::Module_name data type.

Alias of Pattern[/[a-z0-9_-]+\/[a-z0-9_-]+/]

Crowdsec::Module_type

The Crowdsec::Module_type data type.

Alias of Enum['parsers', 'postoverflows', 'scenarios', 'contexts', 'appsec-configs', 'appsec-rules', 'collections']

Changelog

All notable changes to this project will be documented in this file.

Release 0.0.1

First release, far far far far from complete. Published to show the world that this project exists.

Yet another puppet.run conference release.