CrowdSec on AWS User Guide

Overview

This image runs CrowdSec, the free and open source collaborative behavioural security engine. CrowdSec parses logs, detects aggressive and malicious behaviour using a curated library of detection scenarios, and remediates by blocking the offending source IPs. The image is delivered as a ready-to-use host intrusion detection and prevention appliance: the crowdsec agent and the crowdsec-firewall-bouncer are enabled and start on boot, the Linux and SSH detection collections ship installed, and the firewall bouncer is already enforcing the engine's decisions in iptables. The moment an engineer connects over SSH the host is already being protected.

This is a headless security-engine service. There is no web interface. You operate the engine with the cscli command-line tool. The agent tails the system journal and the SSH authentication log, runs the events through the installed parsers and scenarios, and records its verdicts as decisions in an embedded Local API (LAPI). The Local API is bound to loopback only (127.0.0.1:8080), backed by a local database, so it answers on the instance without ever being exposed to the network. The instance security group opens port 22 only.

Every instance generates its own secrets on first boot: the agent's Local API machine credentials and the firewall bouncer's API key are rotated the first time the instance boots, so no shared secret ships in the image. The Local API database and engine state live on a dedicated, independently resizable EBS data volume mounted at /var/lib/crowdsec, so the security-engine database sits on durable storage rather than the operating system disk.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for CrowdSec. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation runs a few seconds after the instance state becomes Running and the status checks pass; it rotates the per-instance Local API and bouncer credentials, then starts the engine and the firewall bouncer.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg CrowdSec Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=crowdsec}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands, and sudo cat /root/crowdsec-info.txt shows the full getting-started notes: what is running, where the per-instance credentials live, and the cscli commands to operate the engine.

Step 4: Verify the Engine and the Bouncer

CrowdSec runs as two system services that are enabled and started on boot: the crowdsec detection agent (which also serves the Local API) and the crowdsec-firewall-bouncer remediation component. Confirm both are active:

systemctl is-active crowdsec crowdsec-firewall-bouncer

That prints active twice. For the full unit status of either service, including the main PID and memory use, use systemctl status crowdsec --no-pager or systemctl status crowdsec-firewall-bouncer --no-pager.

Confirm the installed version, which is pinned to CrowdSec 1.7.8 on this image, and that the agent can authenticate to the Local API:

sudo cscli version
sudo cscli lapi status

cscli version reports v1.7.8, and cscli lapi status reports that you can successfully interact with the Local API, which proves the agent and the embedded API are wired up correctly.

Step 5: The Local API

The agent serves an embedded Local API. On this image it is bound to loopback only (127.0.0.1:8080), so it answers on the instance but is never exposed to the network. Check the health endpoint, which returns HTTP 200 while the engine is healthy:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health

That prints 200. The Local API holds the registered machines and bouncers, the raised alerts and the active decisions, all backed by a local database on the dedicated data volume. You drive it entirely through cscli, so there is no web interface to secure and the API stays private by default. To distribute decisions to bouncers on other hosts, register them against this Local API and expose port 8080 on your own terms.

Step 6: Operate the Engine with cscli

cscli is the command-line interface to the engine. Inspect the acquisition and processing metrics to confirm the pipeline is reading and parsing logs:

sudo cscli metrics show acquisition

You will see the log sources the engine is reading (the SSH journal and the auth log), with lines-read and lines-parsed counters. List the detection collections installed on this image:

sudo cscli collections list

The crowdsecurity/linux and crowdsecurity/sshd collections ship installed, so brute-force and credential-stuffing behaviour against the host is detected out of the box. Each collection bundles the parsers and scenarios for a class of workload.

Step 7: Decisions and the Firewall Bouncer

When a scenario fires, the engine records a decision (typically a ban) in the Local API, and the firewall bouncer enforces it in iptables and ipset. List the active decisions and the registered bouncers:

sudo cscli decisions list
sudo cscli bouncers list

The bouncers list shows the crowdsec-firewall-bouncer registered with its per-instance API key, with a recent Last API pull timestamp that proves it is polling the engine. You can add and remove bans by hand at any time. The following commands add a four-hour ban on an example address and then remove it:

sudo cscli decisions add --ip 192.0.2.10 --duration 4h --reason "manual block"
sudo cscli decisions delete --ip 192.0.2.10

The firewall bouncer picks up the new decision on its next pull and drops traffic from the banned address at the host firewall, then removes the rule when the decision is deleted or expires.

Step 8: Add Detection for Your Workloads

CrowdSec ships a hub of detection collections for web servers, proxies, mail servers, databases and dozens of other applications. Browse the available collections and install the ones that match your workloads. The following installs the nginx collection as an example, then reloads the engine to load it:

sudo cscli collections install crowdsecurity/nginx
sudo systemctl reload crowdsec

To feed the new scenarios, point the engine's log acquisition at your own sources. The acquisition configuration is at /etc/crowdsec/acquis.yaml; on this image it tails the SSH journal and the auth log. Add stanzas for your web server access logs, proxy logs or application logs, then reload the engine with sudo systemctl reload crowdsec. The whitelists in the installed collections keep known-good actors from being banned; add your own management addresses to a whitelist so you are never locked out.

Step 9: The Data Volume

The Local API database and engine state live on a dedicated EBS volume mounted at /var/lib/crowdsec. This keeps the security-engine database off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/crowdsec

The database under /var/lib/crowdsec/data holds the machines, bouncers, alerts and decisions; the hub content the engine uses to parse and detect also lives under this tree. To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Support

This image is published and supported by cloudimg. Support covers log acquisition configuration, collection and scenario selection, parser and whitelist tuning, firewall bouncer deployment, registering bouncers on other hosts, central console enrolment, allowlisting, and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.