Skip to main content

​
Prerequisites

Before installing Somnium, ensure you have the following:

​
Python 3.x

Somnium requires Python 3.6 or later. Check your Python version: 
python3 --version
If Python is not installed, download it from python.org.

​
pip package manager

Verify pip is installed: 
pip3 --version

​
Network access

Somnium requires outbound internet access to:
  • Download threat intelligence feeds
  • Connect to malicious IPs and domains for testing
Important security considerations:
  • Only run Somnium in isolated test environments
  • Obtain approval before generating malicious traffic
  • Configure firewall logging to capture all connection attempts
  • Never run on production networks without explicit authorization

​
Installation steps

1

Clone the repository

Download Somnium from GitHub:
git clone https://github.com/asluppiter/Somnium.git
cd Somnium
Alternatively, download a specific release from the releases page.
2

Install dependencies

Install the required Python packages:
pip3 install -r requirements.txt
This installs the following dependencies:
  • requests - HTTP library for downloading threat feeds and testing URLs
  • tqdm - Progress bar visualization for tests
  • art - ASCII art generation for the CLI interface
  • colorama - Cross-platform colored terminal output
The requirements file is named requierements.txt (note the spelling) in the repository.
3

Verify installation

Test that Somnium runs successfully:
python3 main.py
You should see the Somnium ASCII art banner and the main menu:
#1 Test connection with known bad IPs.
#2 Test connection with known Phishing URLs.
#3 Test connection to TOR Exits Nodes.
#4 Test connection to live Malware distribution Urls
#5 Test connection to known Cryptomining domains.
#6 Test connection to Domain-Generated-Algorithm Domains.
#7 Test connection to Remote Desktop Management.(Anydesk,etc.)
#8 Test connection using known bad user agents.
#9 Generate DNS queries using DoH
#0 Exit.
Choice:
Enter 0 to exit and confirm the installation works.

​
System requirements

  • Operating System: Linux, macOS, or Windows
  • Python: 3.6 or higher
  • RAM: 512MB minimum
  • Disk Space: 100MB for dependencies and logs
  • Network: Outbound internet access (HTTP/HTTPS)

​
Permissions

Somnium creates log files in the current working directory:
  • IP_Results.txt - Known bad IP connection tests
  • URL_Results.txt - Phishing URL tests
  • TOR_Results.txt - TOR exit node tests
  • Malware_Results.txt - Malware distribution URL tests
  • Mining_Results.txt - Cryptomining domain tests
  • DGA_Results.txt - Domain Generation Algorithm tests
  • RAT_Results.txt - Remote access tool connection tests
  • Agent_Results.txt - Bad user-agent tests
  • DoH_Results.txt - DNS over HTTPS tests
Ensure you have write permissions in the directory where you run Somnium.

​
Network configuration

1

Configure logging

Enable logging on your security devices before running tests:
  • Firewall: Enable connection logging for denied and allowed traffic
  • IDS/IPS: Configure alerts for signature matches
  • Proxy: Enable URL filtering logs
  • SIEM: Ensure you’re ingesting logs from all security devices
2

Note the test system IP

Identify the IP address of the system running Somnium:
# Linux/macOS
ip addr show
# or
ifconfig

# Windows
ipconfig
You’ll use this IP to filter logs and correlate test activity.
3

Sync time

Ensure the test system and security devices have synchronized clocks:
# Linux - check current time
date

# Sync with NTP if needed
sudo ntpdate pool.ntp.org
Somnium timestamps all log entries, so accurate time is critical for correlation.

​
Troubleshooting

​
ModuleNotFoundError

If you see ModuleNotFoundError: No module named 'requests' or similar: 
# Ensure you're using pip3 with Python 3
pip3 install -r requirements.txt

# Or install packages individually
pip3 install requests tqdm art colorama

​
Connection timeouts

Many malicious IPs and URLs in threat feeds are offline. This is expected behavior. Somnium logs both successful and failed connections - the goal is to verify your security tools detect the attempts.

​
Permission denied writing logs

# Ensure write permissions in current directory
ls -la

# Or run from your home directory
cd ~
python3 /path/to/Somnium/main.py

​
Python version issues

If python3 is not found but you have Python 3 installed: 
# Try using python instead
python --version
python main.py

​
Next steps

Now that Somnium is installed, proceed to the Quickstart guide to run your first security test.

Build docs developers (and LLMs) love

Get started for freeTalk to us