Minexus - Distributed Command & Control System

Minexus is a Remote Administration Tool (RAT) first used as a faster alternative to ansible. It consists of a central Nexus server, one or more Minion clients, and a Console client for administration tasks. You can use it:

• for remote deployment/execution tool (like ansible)
• for monitoring purposes
• for monitoring purposes
• ... (tell us!)

Example of currently implemented commands: Tag Management:

• tag-set <minion-id> <key>=<value> [...] - Set tags for a minion (replaces all)
• tag-update <minion-id> +<key>=<value> -<key> [...] - Update tags for a minion
• tag-list, lt - List all available tags

Command management:

• command-send all <cmd> - Send command to all minions
• command-send minion <id> <cmd> - Send command to specific minion
• command-send tag <key>=<value> <cmd> - Send command to minions with tag
• command-status all - Show status breakdown of all commands
• command-status minion <id> - Show detailed status of commands for a minion
• command-status stats - Show command execution statistics by minion
• result-get <cmd-id> - Get results for a command ID

Where <cmd> can be:

• Any shell command ⚠️ This command is not filtered in any way, and may be deprecated in future release for security reason ⚠️
• A built-in file command (get, copy, move, info)
• A built-in system command (os, status)
• A built-in docker-compose command (ps, up, down)
• A built-in logging command (level, increase, decrease)
• ...

Its current features include:

• gRPC Communication: High-performance, cross-platform RPC
• TLS Encryption: Secure communication between all components
• Web Interface: User-friendly HTTP dashboard and REST API
• Tag-based Targeting: Flexible minion selection using tags
• Real-time Command Streaming: Live command delivery to minions
• Command Result Tracking: Complete audit trail of command execution
• Auto-discovery: Minions automatically register with Nexus
• Zero-config Defaults: Works immediately without configuration
• Flexible Configuration: Multiple configuration methods
• Database Persistence: Command history and minion registry

We have focused on modularity and extensibility to make it easy to add new commands. (more info in adding_commands.md)

Why Minexus

Although I was very satisfied with ansible for deployment, I found it not practical for remote admistration and monitoring:

• Ansible is too slow
• Handling multiple outputs in Ansible is not convenien
• Limited monitoring capabilities (no built-in state management), currently requiring external tools like Telegraf or Grafana.

Additionally, I planned to create a security agent for various purposes, so I decided to design this agent (Minion) alongside its server (Nexus). I started by implementing the basic architecture for remote administration and then incrementally added features, aiming for Minexus to handle administration, monitoring, and security needs in a unified system.

Quick Start

1. Setup Nexus Server

Create an .env.prod file:

cp env.sample .env.prod

Modify the .env.prod (DON'T KEEP the default password unchanged...)

Then launch the nexus:

MINEXUS_ENV=prod make compose-run

2. Install Minion Clients

Once Nexus is running, visit the web dashboard at http://yournexus.address.com:8086 to see quick installation commands with copy buttons.

Alternatively, use these commands directly:

Linux/macOS:

curl -sSL http://yournexus.address.com:8086/install_minion.sh | sh

Windows PowerShell:

iwr -useb http://yournexus.address.com:8086/download/minion/windows-amd64.exe -OutFile minion.exe; .\minion.exe

Options:

• For systemd installation on Linux: curl -sSL http://yournexus.address.com:8086/install_minion.sh | sh -s -- --systemd
• For Windows with custom environment variables:

  $env:NEXUS_SERVER="yournexus.address.com"
  $env:NEXUS_MINION_PORT="11972"
  .\minion.exe
  

The installation script automatically detects your OS and architecture, downloading the appropriate minion binary.

Project Structure

minexus/
├── .github/               # GitHub Actions workflows and issue templates
│   ├── ISSUE_TEMPLATE/    #   Issue templates
│   └── workflows/         #   CI/CD workflows
├── cmd/                   # Application entry points
│   ├── console/           #   Console client main
│   ├── minion/            #   Minion client main
│   └── nexus/             #   Nexus server main
├── config/                # Configuration files
│   └── docker/            #   Docker configuration
│       └── initdb/        #     Database initialization scripts
├── documentation/         # Project documentation
├── internal/              # Internal packages
│   ├── certs/             #   TLS certificate generation and management
│   ├── command/           #   Command implementations for minions
│   ├── config/            #   Configuration system
│   ├── logging/           #   Logging infrastructure
│   ├── minion/            #   Minion client implementation
│   ├── nexus/             #   Nexus server implementation
│   └── version/           #   Version handling
├── makefiles/             # Modular Makefile components
│   └── host_detection.mk  #   Host platform and architecture detection
├── proto/                 # Protocol buffer definitions
├── protogen/              # Generated protobuf code
├── CODE_OF_CONDUCT.md     # Code of Conduct for contributors
├── Dockerfile.*           # Dockerfiles for different components
├── LICENSE                # Project license information
├── Makefile               # Build and development tasks
├── README.md              # Project overview and documentation
├── docker-compose.yml     # Docker Compose configuration
└── env.sample             # Sample environment file

Configuration

Configuration Priority

The configuration system follows this priority order (highest to lowest):

1. Command Line Flags (highest priority)
2. Environment Variables
3. Environment-Specific Configuration Files (.env.prod, .env.test)
4. Default Values (lowest priority)

Environment-Specific Configuration

Minexus uses the MINEXUS_ENV environment variable to determine which configuration file to load:

• MINEXUS_ENV=test (default) → loads .env.test
• MINEXUS_ENV=prod → loads .env.prod

Important: Environment-specific configuration files are required and the application will fail to start if the appropriate file is missing.

For detailed configuration options, see documentation/configuration.md.

For detailed version handling information, see documentation/version.md.

TLS Configuration

Minexus supports TLS encryption for secure communication between all components. TLS can be enabled using configuration files, environment variables, or command-line flags.

TLS Certificates (Embedded at Build Time)

TLS encryption is mandatory for all Minexus components. Certificates are embedded directly into the binaries at build time for security and simplicity.

Generating TLS Certificates for Development

For development builds, certificates are embedded from internal/certs/. Use OpenSSL to generate them:

# Certificate generation is handled by the certificate generation script
# See documentation/certificate_generation.md for details

# Rebuild binaries to embed the new certificates
make build

Important: For production environments, replace the certificates in internal/certs/ with certificates signed by a trusted Certificate Authority (CA) before building.

Security Notes

• Certificate Management: In production, use certificates from a trusted CA
• Private Key Security: Protect private key files with appropriate file permissions (chmod 600)
• Certificate Rotation: Plan for regular certificate renewal and rotation

Architecture

┌─────────────┐    gRPC     ┌─────────────┐    PostgreSQL    ┌──────────────┐
│   Console   │◄───────────►│    Nexus    │◄─────────────────│   Database   │
│   Client    │   (mTLS)    │   Server    │                  │              │
└─────────────┘   :11973    │             │                  └──────────────┘
                             │  Triple-    │
┌─────────────┐    HTTP      │  Server     │
│ Web Browser │◄───────────►│ Architecture│
│  Dashboard  │   :8086     │             │
└─────────────┘             └─────────────┘
                                   ▲
                              gRPC │ (TLS)
                                   │ :11972
                     ┌─────────────┼─────────────┐
                     │             │             │
                     ▼             ▼             ▼
              ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
              │   Minion    │ │   Minion    │ │   Minion    │
              │  Client 1   │ │  Client 2   │ │  Client N   │
              └─────────────┘ └─────────────┘ └─────────────┘

Triple-Server Architecture

The Nexus server runs three concurrent services:

• Minion Server (port 11972): TLS gRPC server for minion connections
• Console Server (port 11973): mTLS gRPC server for console connections
• Web Server (port 8086): HTTP server for web interface and REST API

Documentation

More documentation is a