Skip to main content

​
Installation Options

MCRIT can be installed in two ways: using Docker for a complete packaged deployment, or as a standalone installation for more customization.
Recommended: Use docker-mcrit for the easiest deployment with fully compatible versions across all components.
The dockerized deployment includes:
  • MCRIT server and workers
  • MongoDB database with persistence
  • Web frontend (MCRITweb) for browser-based interaction
  • All dependencies pre-configured
1

Clone the Docker Repository

git clone https://github.com/danielplohmann/docker-mcrit.git
cd docker-mcrit
2

Start the Services

docker-compose up -d
This will start:
  • MongoDB on port 27017
  • MCRIT API server on port 8000
  • MCRITweb frontend on port 8080
  • One or more worker containers
3

Verify Installation

Check that all services are running:
docker-compose ps
Access the web interface at http://localhost:8080
The Docker deployment ensures version compatibility across MCRIT, MongoDB, and the web frontend.

​
Standalone Installation

For standalone installation, you’ll need to set up Python dependencies and MongoDB separately. This approach is recommended for:
  • Custom deployment configurations
  • Integration with existing MongoDB instances
  • Development and testing

​
Prerequisites

The following assumes Ubuntu as the host operating system. Adjust commands for other Linux distributions accordingly.

​
System Requirements

  • Python 3.7 or higher
  • MongoDB 5.0 or higher
  • 4GB RAM minimum (8GB+ recommended for larger datasets)
  • Ubuntu 18.04, 20.04, or 22.04

​
Step 1: Install Python and Dependencies

1

Install Python

sudo apt install python3 python3-pip
2

Clone MCRIT Repository

git clone https://github.com/danielplohmann/mcrit.git
cd mcrit
3

Install Python Dependencies

MCRIT requires the following key packages:
pip install -r requirements.txt
Key dependencies include:
  • smda>=1.13.19 - Smart Disassembler for binary analysis
  • pymongo - MongoDB driver
  • falcon>=2.0.0 - REST API framework
  • mmh3>=2.5.1 - MurmurHash3 for hashing
  • numpy<2.0.0 - Numerical computing
  • scipy - Scientific computing for clustering
  • lief>=0.16.0 - Binary parsing (PE, ELF)
  • picblocks>=1.1.2 - PicHash computation
  • gunicorn - Production WSGI server (Linux only)
  • waitress - WSGI server (cross-platform)
4

Install MCRIT Module

Install MCRIT in editable mode for development:
pip install -e .
Or install normally:
pip install .
After installation, MCRIT can be used without an internet connection if desired.

​
Step 2: Install and Configure MongoDB

MongoDB 5.0 is the default and recommended backend for persistent data storage.
1

Install MongoDB Signing Key

sudo apt-get install gnupg
wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -
2

Add MongoDB Repository

Choose the appropriate repository for your Ubuntu version:Ubuntu 22.04 (Jammy):
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
Ubuntu 20.04 (Focal):
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
Ubuntu 18.04 (Bionic):
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
3

Install MongoDB

sudo apt-get update
sudo apt-get install -y mongodb-org
4

Start MongoDB Service

Start MongoDB immediately:
sudo systemctl start mongod
Enable MongoDB to start on system boot:
sudo systemctl enable mongod
5

Verify MongoDB is Running

sudo systemctl status mongod
You should see active (running) in the output.
Ensure MongoDB is running before starting MCRIT server and workers, or they will fail to connect.

​
Step 3: Start MCRIT Components

MCRIT requires both a server and at least one worker to be running.
1

Start the Server

In one terminal session:
mcrit server
The server will start and listen on http://127.0.0.1:8000/ by default.On Linux, MCRIT automatically uses gunicorn for better performance. On Windows, it uses waitress.
2

Start a Worker

In a separate terminal session:
mcrit worker
The worker will connect to MongoDB and begin processing queued jobs.
3

Verify Services

Test the API endpoint:
curl http://127.0.0.1:8000/status
Or use the CLI client:
mcrit client status
You can run multiple workers in parallel to process jobs faster. Each worker should run in its own terminal or as a separate service.

​
Advanced Configuration

​
MongoDB Connection

MCRIT’s MongoDB connection is fully configurable. Configuration options can be set via environment variables or configuration files in mcrit/config/.

​
Server Options

Profiling Mode (for performance analysis): 
mcrit server --profile
Force Gunicorn (Linux only): 
mcrit server --gunicorn

​
Worker Types

MCRIT supports different worker implementations: Standard Worker: 
mcrit worker
Spawning Worker (for better memory management): 
mcrit spawningworker
The spawning worker executes jobs in separate subprocesses, reducing issues with locked memory allocations.

​
API Token Authentication

MCRIT supports API token authentication for secure deployments. Tokens can be set via the server configuration and passed through the apitoken header field.

​
Verification

After installation, verify your setup: 
mcrit client status
Expected output: 
{
  "status": {
    "db_state": 0,
    "storage_type": "mongodb",
    "num_bands": 20,
    "num_samples": 0,
    "num_families": 0,
    "num_functions": 0,
    "num_pichashes": 0
  }
}

​
Troubleshooting

  • Check that MongoDB is running: sudo systemctl status mongod
  • Verify no other service is using port 8000
  • Check server logs for connection errors
  • Ensure MongoDB is accessible on localhost:27017
  • Check MongoDB authentication settings
  • Verify firewall rules aren’t blocking connections
  • Reinstall requirements: pip install -r requirements.txt --force-reinstall
  • Check Python version is 3.7+
  • Use a virtual environment to avoid conflicts
  • Increase system RAM allocation
  • Use spawning worker instead of standard worker
  • Reduce concurrent workers
  • Process smaller batches of samples

​
Next Steps

Quickstart Guide

Now that MCRIT is installed, learn how to submit your first sample and perform analysis.

Build docs developers (and LLMs) love

Get started for freeTalk to us