stratosphereips/slips_macos repository overview

⁠

Slips v0.9.6

⁠

Documentation⁠ — Features⁠ — Installation⁠ — Authors⁠ — Contributions⁠

⁠Repo Stars Over Time

⁠Slips: Behavioral Machine Learning-Based Intrusion Prevention System

Slips is a behavioral intrusion prevention system that uses machine learning to detect malicious behaviors in network traffic. Slips focus on targeted attacks, detection of command and control channels, and providing a good visualization for the analyst. It can analyze network traffic in real-time, network captures such as pcap files, and network flows produced by Suricata, Zeek/Bro, and Argus. Slips processes the input data, analyzes it, and highlights suspicious behavior that needs the analyst's attention.

⁠Modules

Slips is written in Python and is highly modular. Each module performs a specific detection in the network traffic. The complete documentation of Slips' internal architecture and instructions on how to implement a new module is available here⁠.

The following table summarizes all active modules in Slips, their status, and their purpose:

⁠Installation

There are two ways to run Slips: i. using Docker, which is our preferred option, and i. bare metal installation on Linux. This section guides you through how to get started with Slips.

⁠Running Slips Using Docker

The easiest way to run Slips is using Docker. The latest Slips docker image stratosphereips/slips:latest can analyze multiple types of network data, including pcaps, Zeek flows, Argus flows, and others. In Linux systems, it is possible to use the docker image to analyze real-time traffic from the host's interface. Check the documentation⁠ for a more detailed usage explanation.

Follow the next steps to perform a Slips test-run:

• Create a new container from the latest Slips docker image: docker run -it -d --name slips stratosphereips/slips:latest
• Access the container: docker container exec -ti slips /bin/bash
• Run Slips on a sample pcap to test things work as expected: python3 slips.py -e 1 -f dataset/hide-and-seek-short.pcap
• Checking Slips output files: cd output/hide-and-seek-short.pcap_<ts>/ && cat alerts.log

To download the Slips docker image, spawn a new container in daemon mode and run Slips on a test pcap in one command from your host computer:

    docker run -it -d --name slips stratosphereips/slips ./slips.py -e 1 -f dataset/hide-and-seek-short.pcap

⁠Run Slips sharing files between the host and the container

The following instructions will guide you on how to run a Slips docker container with file sharing between the host and the container.

    # create a directory to load pcaps in your host computer
    mkdir ~/dataset
    
    # copy the pcap to analyze to the newly created folder
    cp <some-place>/myfile.pcap ~/dataset
    
    # create a new Slips container mapping the folder in the host to a folder in the container
    docker run -it --rm --net=host --name slips -v $(pwd)/dataset:/StratosphereLinuxIPS/dataset stratosphereips/slips:latest
    
    # run Slips on the pcap file mapped to the container
    ./slips.py -c slips.conf -f dataset/myfile.pcap

⁠Run Slips with access to block traffic on the host network

In Linux OS, the Slips can be used to analyze and block network traffic on the host network interface. To allow the container to see the host interface traffic and block malicious connections, it needs to run with the option --cap-add=NET_ADMIN. This option enables the container to interact with the network stack of the host computer. To block malicious behavior, run Slips with the parameter -p.

    # run a new Slips container with the option to interact with the network stack of the host
    docker run -it --rm --net=host --cap-add=NET_ADMIN --name slips stratosphereips/slips:latest
    
    # run Slips on the host interface `eno1` with active blocking `-p`
    ./slips.py -c slips.conf -i eno1 -p

⁠Build Slips from the Dockerfile

You can build the Docker of Slips, but consider that system requirements vary depending on the operating system, primarily because of TensorFlow. TensorFlow accesses the hardware directly, so Docker will not always work well. For example, in macOS M1 computers, the use of TensorFlow from inside Docker is still not supported.

⁠Building a Docker For macOS

To build a Docker image of Slips for macOS follow the next steps:

    # clone the Slips repository in your host computer
    git clone https://github.com/stratosphereips/StratosphereLinuxIPS.git
    
    # access the Slips repository directory
    cd StratosphereLinuxIPS/
    
    # build the MacOS image from the recommended Dockerfile
    docker build --no-cache -t slips -f docker/macos-image/Dockerfile .

To use Slips with files already inside the Docker you can do;

    # run a new Slips container from the freshly built local image
    docker run -it --rm --net=host --name slips slips
    
    # run Slips using the default configuration in one of the provided test datasets
    ./slips.py -c slips.conf -f dataset/test3.binetflow

To use Slips with files shared with the host, run:

    # run a new Slips container from the freshly built local image
    docker run -it --rm --net=host --name slips -v $(pwd)/dataset:/StratosphereLinuxIPS/dataset slips

    # Optionally put a new file
    cp yourfile.pcap $(pwd)/datasets/
    
    # run Slips using the default configuration in one of the provided test datasets
    ./slips.py -c slips.conf -f dataset/yourfile.pcap

To use Slips with packets from the host interface, run the following. BUT beware that the big limitation of using Docker in macOS for interface capture is that until 2022/06/28, Docker for macOS does not entirely pass all packets to the container when run in mode --cap-add=NET_ADMIN.

    docker run -it --rm --net=host --cap-add=NET_ADMIN --name slips slips

⁠Building a Docker For Linux

To build a Docker image of Slips for Linux follow the next steps:

    # clone the Slips repository in your host computer
    git clone https://github.com/stratosphereips/StratosphereLinuxIPS.git
    
    # access the Slips repository directory
    cd StratosphereLinuxIPS/
    
    # build the docker image from the recommended Dockerfile
    docker build --no-cache -t slips -f docker/ubuntu-image/Dockerfile .
    
    # run a new Slips container from the freshly built local image
    docker run -it --rm --net=host --name slips slips
    
    # run Slips using the default configuration in one of the provided test datasets
    ./slips.py -c slips.conf -f dataset/test3-mixed.binetflow

⁠First run

Be aware that the first time you run Slips it will start updating all the databases and threat intelligence files in the background. However, it will give you as many detections as possible while updating. You may have more detections if you rerun Slips after the updates. Slips behaves like this, so you don't have to wait for the updates to finish to have some detections.

Depending on the remote sites, downloading and updating the DB may take up to 4 minutes. Slips stores this information in a cache Redis database, which is kept in memory when Slips stops. Next time Slips runs, it will read from this database. The information in the DB is updated periodically according to the configuration file (usually one day).

You can check if the DB is running this by looking at your processes:

    ps afx|grep redis
    9078 ?        Ssl    1:25 redis-server *:6379

You can destroy this database by running:

    ./slips.py -k
    Choose which one to kill [0,1,2 etc..]
    [0] Close all servers
    [1] conn.log - port 6379

⁠Limitations

The main limitation of running Slips in a Docker is that every time the container stops, all files inside the container are deleted, including the Redis database of cached data, and you lose all your Threat Intelligence (TI) data and previous detections. Next time you run Slips, it will start making detections without all the TI data until downloading the data again. The only solution is to keep the container up between scans.

⁠Slips Bare Metal Installation

To install Slips in your host computer there are three core things needed:

• installing Python dependencies

• installing Redis

• installing zeek (formerly bro) for network analysis.

You can install Slips using out install.sh using:

chmod +x install.sh
./install.sh

or manually using the following steps.

⁠Clone Slips repository

The first step is to clone the Slips repository to your host computer:

    # clone repository
    git clone https://github.com/stratosphereips/StratosphereLinuxIPS.git
    
    # access the Slips directory
    cd StratosphereLinuxIPS

⁠Installing Python dependencies

We recommend using Conda⁠ for the Python environment management:

    # create conda environment and download all Python dependencies
    conda env create -f conda-environment.yaml
    
    # activate the conda environment
    conda activate slips 

There's also a pip requirements.txt for pip users:

pip3 install -r requirements.txt

⁠Installing Zeek for pcap analysis

Additionally, you may need to install either zeek or bro in order to have the capability to analyze pcap files. Follow the official installation guide from Zeek Website⁠.

⁠Installing Redis

Slips needs Redis >= 7.0.4 for interprocess communication. Redis can be installed directly in the host computer or can be run using Docker.

Starting, stopping managing of redis DBs is done automatically by Slips.

Check the documentation⁠ for more detailed installation instructions.

⁠Run Slips

After all dependencies are installed and Redis is running, you are ready to run Slips. Copy pcap files or other flow files in the ./dataset/ directory and analyze them:

    # run Slips with the default configuration
    # use a sample pcap of your own
    ./slips.py -c slips.conf -f dataset/myfile.pcap

⁠Viewing Slips Output

You can view Slips output using kalipso in your terminal using:

./kalipso.sh

Or use Slips' web interface by using:

./webinteface.sh

Then navigate to http://localhost:55000/ from your browser.

⁠P2P Module

The peer to peer system os Slips is a highly complex automatic system to find other peers in the network and share data on IoC automatically in a balanced, trusted way. You just have to enable the P2P system. Please check the documentation here⁠

You can use Slips with P2P directly in a special docker image by doing:

    # download the Slips P2P docker image
    docker pull stratosphereips/slips_p2p
    
    # run Slips on the local network
    docker run --name slipsp2p -d -it --rm --net=host --cap-add=NET_ADMIN stratosphereips/slips_p2p

⁠Train The Machine Learning Models With Your Data

Slips' machine learning models can be extended by running Slips in training mode with the user network traffic, leading to a improvement in the detection.

To use this feature you need to modify the configuration file slips.conf to add in the [flowmldetection] section:

    mode = train

The machine learning model needs a label for this new traffic to know what type of traffic will it learn from. Add the following label:

    label = normal

Run Slips normally in your data, interface or any input file, and the machine learning model will be updated automatically.

To use the new model, reconfigure Slips to run in test mode by updating the slips.conf file with:

    mode = train

⁠Slips in the Media

• 2022 BlackHat USA Arsenal, Slips: A Machine-Learning Based, Free-Software, Network Intrusion Prevention System [web⁠]
• 2021 BlackHat Europe Arsenal, Slips: A Machine-Learning Based, Free-Software, Network Intrusion Prevention System [slides⁠] [web⁠]
• 2021 BlackHat USA Arsenal, Slips: A Machine-Learning Based, Free-Software, Network Intrusion Prevention System [web⁠]
• 2021 BlackHat Asia Arsenal, Slips: A Machine-Learning Based, Free-Software, Network Intrusion Prevention System [web⁠]
• 2020 Hack In The Box CyberWeek, Android RATs Detection With A Machine Learning-Based Python IDS [video⁠]
• 2019 OpenAlt, Fantastic Attacks and How Kalipso can Find Them [video⁠]
• 2016 Ekoparty, Stratosphere IPS. The free machine learning malware detection [video⁠]

⁠People Involved

Founder: Sebastian Garcia, [email protected]⁠, [email protected]⁠.

Main authors: Sebastian Garcia, Alya Gomaa, Kamila Babayeva

Contributors:

• Veronica Valeros
• Frantisek Strasak
• Dita Hollmannova
• Ondrej Lukas
• Elaheh Biglar Beigi
• Maria Rigaki
• kartik88363
• arkamar

⁠Contribute to Slips

All contributors are welcomed! How you can help?

• Read our contributing⁠ guidelines.
• Run Slips and report bugs, make feature requests, and suggest ideas.
• Open a pull request with a solved GitHub issue and new feature.
• Open a pull request with a new detection module. The instructions and a template for new detection module here⁠.
• Join our community at Discord⁠, ask questions, suggest new features or give us feedback.

⁠Acknowledgments

Slips was funded by the following organizations.

• NlNet Foundation, https://nlnet.nl/⁠
• AIC Group, Czech Technical University in Prague, https://www.aic.fel.cvut.cz/⁠
• Avast Software, https://www.avast.com/⁠
• CESNET, https://www.cesnet.cz/⁠