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:
If Python is not installed, download it from python.org.

​
pip package manager

Verify pip is installed:

​
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:
Alternatively, download a specific release from the releases page.
2

Install dependencies

Install the required Python packages:
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:
You should see the Somnium ASCII art banner and the main menu:
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:
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:
Somnium timestamps all log entries, so accurate time is critical for correlation.

​
Troubleshooting

​
ModuleNotFoundError

If you see ModuleNotFoundError: No module named 'requests' or similar:

​
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

​
Python version issues

If python3 is not found but you have Python 3 installed:

​
Next steps

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