Skip to content

Docker

Jump to bottom
Peter Manev edited this page Jul 30, 2023 · 94 revisions

Installation

Requirements

The installation and configuration procedure described here has been tested and confirmed on Debian, Fedora, CentOS (Stream 8/9), RedHat, Ubuntu LTS.

The installaton can also work on other Linux OSs that support docker but it may need local adjustments. Feedback is welcome as well.

Minimum working setup:

  • 2 cores
  • 10 GB of free RAM
  • minimum 10 GB of free disk space (actual disk occupation will mainly depend of the number of rules and the amount of traffic on the network). 200GB+ SSD grade is recommended.
  • git, curl
  • docker > 17.06.0 (will be installed during SELKS initial setup)
  • docker-compose > 1.27.0 (compose v2 will be installed during SELKS initial setup if docker compose is not found)

Basic installation

NOTE: For CentOS Stream 8 users - it may be needed to remove the follwoing packages before the install - dnf remove podman buildah

NOTE: For RedHat users - docker needs to be installed via the instructions of the CentOS offical documentation

git clone https://github.com/StamusNetworks/SELKS.git
cd SELKS/docker/
./easy-setup.sh
sudo -E docker compose up -d

Once the containers are up and running, you should just point your browser to https://your.selks.IP.here/ If you chose to install Portainer during the installation, you must visit https://your.selks.IP.here:9443 to set portainer's admin password

If the setup script fails, please take a look at the Manual Docker install and Report an issue

Credentials and log in

In order to access scirius, you will need following credentials:

  • user: selks-user
  • password: selks-user

Understanding the setup script

The easy-setup.sh does the following :

  1. Checking that docker and docker compose are properly installed and available to the user, and installing them if needed
  2. Generating SSL certificates for nginx that will secure the Scirius web interface
  3. Generating secret key for the underlying Django
  4. Creating a .env file containing environment variables deduced from the user inputs
  5. Pull the containers

In order to change the options you defined, just run easy-setup.sh again

Production setup

Deployment

For production setups Elasticsearch can be assigned to use 32/64GB RAM pending you have that available on the host. It is also recommended to automatically start the containers at boot (on host restart):

./easy-setup.sh  --non-interactive -i eno1 --iA --restart-mode always --es-memory 64G 
sudo -E docker compose up -d

Elasticsearch data and log rotation

For indexes/data retention and policies it is recommended to use the Elasticsearch's own ILM https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html

Data on Host

Any Suricata logs and or pcap capture data from Suricata are logged into the host as well in the current docker folder :

containers-data/suricata/logs/

It is recommended for production installs to have some sort of log rotation for those files configured.

Reading pcap

The docker installation is design to easily read/digest pcaps too for teaching,training or research and analysis scenarios.
To get help:

./scripts/readpcap.sh -h

Pcap reading script through Suricata
Usage: scripts/readpcap.sh [-c|--(no-)cleanup] [-a|--(no-)autofp] [-s|--set-rulefile <arg>] [-S|--set-rulefile-exclusive <arg>] [-h|--help] [--] <path>
	<path>: Path to the pcap file to read. If <path> specifies a directory, all files in that directory
		will be processed in order of modified time maintaining flow state between files.
	-c, --cleanup, --no-cleanup: Remove all previous data from elasticsearch and suricata. (off by default)
	-a, --autofp, --no-autofp: Run in autofp mode instead of single mode. (off by default)
	-s, --set-rulefile: Set a file with signatures, which will be loaded together with the rules set in the yaml. (no default)
	-S, --set-rulefile-exclusive: Set a file with signatures, which will be loaded exclusively, regardless of the rules set in the yaml. (no default)
	-h, --help: Prints help

To read a pcap:

./scripts/readpcap.sh /path/to/file.pcap

To read a pcap but clear/delete all previous data:

./scripts/readpcap.sh -c /path/to/file.pcap

To read a pcap(using all available CPUs for reading), clear/delete all previous data:

./scripts/readpcap.sh -ac /path/to/file.pcap

To read multiple pcaps into the so called tenant mode:

./scripts/readpcap.sh /path/to/file.pcap ; \
./scripts/readpcap.sh /path/to/file2.pcap ; \
./scripts/readpcap.sh /path/to/file3.pcap

Now each pcap will populate with its own file name in the Hunt interface that can be easily selected and zoomed into for investigation or teaching. That way providing an easy way to separately analyse the different cases and compare one case to another or investigate separately.

Clear data

To delete and remove all data:

./scripts/cleanup.sh

Resetting Dashboards

SELKS comes by default with more than 400 visualizations and 28 dashboards for Suricata that serve a wide range of purposes - from network troubleshooting and visibility to threat detection and threat hunting.
To reset the Kibana dashboards use the following procedure:

  1. Log in to Scirius
  2. From the right upper corner switcher , go to Administration.
  3. Select System Settings form the left upper corner drop down menu.
  4. Click the Reset button under Reset SN dashboards

Log rotation

Log rotation can be defined via the cron log container

dir -1   SELKS/docker/containers-data/cron-jobs/
15min
1min
daily
hourly
monthly
README.md
weekly

Daily log rotation is setup by default:

cat    SELKS/docker/containers-data/cron-jobs/daily/suricata-logrotate.sh 
#! /bin/sh
#
# Example of rotating the logs within the Suricata container.
#
# Add -v for verbose output.
# Add -f to force rotation.

echo "Rotating Suricata logs"
docker exec suricata logrotate -v /etc/logrotate.d/suricata $@ && echo "done." || echo "ERROR"

The log rotation config file is located here:

cat   SELKS/docker/containers-data/suricata/logrotate/suricata 
/var/log/suricata/*.log /var/log/suricata/*.json {
    daily
    missingok
    rotate 3
    nocompress
    sharedscripts
    postrotate
        suricatasc -c reopen-log-files
    endscript
}

PCAP logrotation is set in the helper selks.yaml file:

https://github.com/StamusNetworks/SELKS/blob/master/docker/containers-data/suricata/etc/selks6-addin.yaml#L515
In the installation directory, the file is located in the folder docker/containers-data/suricata/etc/selks6-addin.yaml

Rulesets and threat intel update

There is a default daily cronjob setup that will update any rulesets and threat intel:

cat    SELKS/docker/containers-data/cron-jobs/daily/scirius-update-suri-rules.sh 
#! /bin/sh

echo "Updating Suricata rules from Scirius"
docker exec scirius python /opt/scirius/manage.py updatesuricata && echo "done." || echo "ERROR"

It can be further modified or moved to another sequence - hourly for example to do it every hour.

Manually force update the rulesets and threat intel

If needed, the rulests and threat intel can be manually force updated:
In Scirius , Suricata tab -> click Ruleset actions (left hand side panel) -> select Update,Build, Push -> click on Apply

Suppression and threshold

The /etc/suricata/rules/threshold.conf file inside the suricata docker contains all the alert suppression and thresholding configuration done through Scirius with respect to Suricata.

For example to list current suppression or thresholds:

docker exec suricata cat /etc/suricata/rules/threshold.config
threshold gen_id 1, sig_id 2028765, type both, track by_src, count 1, seconds 60
threshold gen_id 1, sig_id 2028766, type both, track by_src, count 1, seconds 60
threshold gen_id 1, sig_id 2028772, type both, track by_src, count 1, seconds 60
threshold gen_id 1, sig_id 2028800, type both, track by_src, count 1, seconds 60

If by mistake you have chosen to install the package maintainers version - no worries - just build,update and push the ruleset again from Scirius. (Suricata tab -> click Ruleset actions (left hand side panel) -> select Update,Build, Push -> click on Apply).

Advanced features

Help

./easy-setup.sh --help

Using your own SSL certificate

Put your existing SSL certificate and private key in SELKS/docker/containers-data/nginx/ssl as scirius.crt and scirius.key before running the easy-setup.sh script.

Running the install script without user interaction

The script provides several command line options to avoid being prompted. This can be useful to automate SELKS deployment. Refer to the help

./easy-setup.sh --non-interactive

Another example:

The bellow command will setup the SELKS docker instillation:

  • in noninteractive mode
  • install all containers (elasticsearch/suricata/ngingx/logstash/kibana/scirius/evebox/portainer)
  • use interface eno1 as sniffing interface
  • use 6GB of RAM for Elasticsearch
  • start up the installation (docker compose)
./easy-setup.sh  --non-interactive -i eno1 --iA  --es-memory 6G 
sudo -E docker compose up -d

Changing ELK stack version

./easy-setup.sh --elk-version <version-number>

The version will be the same for Elasticsearch, Kibana and Logstash. It is not possible (and not recommended) to set them individually with different versions each.

Changing scirius version

./easy-setup.sh --scirius-version <version>

The version can be a branch name, a tag, a release number or a git sha

Dummy sniffing interface

This case is useful for replaying specific pcap investigation cases for fast Security analysis. Sometimes it is useful to setup a dummy interface for sniffing to be sure that no other traffic will be mixed in with the specific pcap replay:

ip link add tppdummy0 type dummy && \
ip link set tppdummy0 up && \
ifconfig tppdummy0 mtu 1572

Then spin up SELKS:

./easy-setup.sh -i tppdummy0 
sudo -E docker compose up -d

Check Suricata version and enabled/build features

To check Suricata build info and version:

docker exec suricata suricata --build-info

How to adjust configurations

If configuration adjustments are needed, please follow the guides below.

Suricata config

In order to tweak suricata config, edit the following file :
SELKS/docker/containers-data/suricata/etc/selks6-addin.yaml
and restart the container :
sudo docker compose restart suricata

The default suricata.yaml can be edited but it resides inside the container and any changes would be overwritten upon upgrade.

Elasticsearch config

The configuration file for elasticsearch resides inside the container and should not be modified directly, as those changes would not be permanent. Instead, you can set specifics settings in the environment subsection on the elasticsearch section of docker-compose.yml. You can set individual Elasticsearch configuration parameters using Docker environment variables. You can use the setting name directly as the environment variable name.
For example:

    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false

Alternative approach

If you cannot do the above, due to for example because your orchestration platform forbids periods in environment variable names, then you can use an alternative style by converting the setting name as follows:

  1. Change the setting name to uppercase
  2. Prefix it with ES_SETTING_
  3. Escape any underscores (_) by duplicating them
  4. Convert all periods (.) to underscores (_)

For example, -e bootstrap.memory_lock=true becomes -e ES_SETTING_BOOTSTRAP_MEMORY__LOCK=true.

Logstash config

If needed , to change the logstash configuration, please refer to Elasticsearch config. It is done the exact same way just in the logstash subsection of docker-compose.yml.

Password change

Changing the default password is highly recommended! To do so - from the Scirius Administration interface, in the right upper corner click on the selks-user user, select Account settings, on the left hand side panel click Change password.

Password reset

A password change and a reset can also be done from the command line:

Attach to the Scirius docker

docker exec -it scirius bash
python3 /opt/scirius/manage.py changepassword selks-user

Useful commands

Most docker compose commands will have the following form docker compose COMMAND [container-name] If no container-name is provided, it will be applied to all SELKS containers Those commands must be run from the SELKS/docker/ directory

Stopping containers

docker compose stop [container-name]

Starting containers

docker compose start [container-name]

Restarting containers

docker compose restart [container-name]

Displaying logs

docker compose logs [container-name]

Removing containers along with their data

docker compose down -v

Recreating containers

docker compose up [container-name] --force-recreate

Updating containers

docker compose down [container-name]
docker compose pull [container-name]
docker compose up [container-name] --force-recreate

Upgrade all containers

If you are already running SELKS on docker, you can upgrade SELKS and the containers to a fixed version. To do so, simply run from the docker directory:

 git pull
 docker compose pull
 docker compose stop
 sudo -E docker compose up -d

Getting Help

To get help

Report an issue

If you've encoutered an issue please let us know: Report Issue

Clone this wiki locally