Skip to content

Architecture

Jump to bottom
noah edited this page Nov 15, 2025 · 1 revision

Architecture Overview

Technical architecture and design of OSRipper.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      OSRipper System                         │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌──────────────┐      ┌────────────┐ │
│  │   Generator  │──────▶│ Obfuscator  │──────▶│ Compiler   │ │
│  │   Module     │      │   Module     │      │  (Nuitka)  │ │
│  └──────────────┘      └──────────────┘      └────────────┘ │
│         │                      │                    │         │
│         └──────────────────────┴────────────────────┘         │
│                            │                                   │
│                            ▼                                   │
│                    ┌──────────────┐                           │
│                    │   Payload     │                           │
│                    │   (Binary)    │                           │
│                    └──────────────┘                           │
│                            │                                   │
└────────────────────────────┼───────────────────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   Target System │
                    └─────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   C2 Server      │
                    │   (Web UI)       │
                    └─────────────────┘

Component Overview

Generator Module

Purpose: Creates payload templates and orchestrates generation process.

Components:

  • Payload template generation
  • Variable randomization
  • Code embedding
  • File management

Key Functions:

  • create_bind_payload() - Bind shell generation
  • create_reverse_ssl_tcp_payload() - Reverse shell generation
  • create_doh_payload() - DoH C2 generation
  • create_https_payload() - HTTPS C2 generation
  • create_custom_payload() - Custom script processing

Obfuscator Module

Purpose: Obfuscates code to evade detection.

Components:

  • Standard obfuscator (obfuscator.py)
  • Enhanced obfuscator (obfuscator_enhanced.py)

Techniques:

  • Variable name randomization
  • Code structure obfuscation
  • String encryption
  • Base64 encoding layers
  • Junk code injection (enhanced)
  • Anti-debugging (enhanced)
  • VM detection (enhanced)

Compiler Module

Purpose: Compiles Python payloads to standalone binaries.

Technology: Nuitka

Process:

  1. Source preparation
  2. Nuitka compilation
  3. Icon injection (optional)
  4. Binary output

C2 Server

Purpose: Command & control server with web interface.

Components:

  • Flask web server
  • DoH handler
  • Session manager
  • Command queue
  • Web UI

Architecture:

┌─────────────────────────────────────────┐
│           C2 Server (Flask)            │
├─────────────────────────────────────────┤
│                                         │
│  ┌────────────┐  ┌──────────────┐     │
│  │  Web UI    │  │  DoH Handler │     │
│  │  (Routes)  │  │              │     │
│  └────────────┘  └──────────────┘     │
│         │              │                │
│         └──────┬───────┘                │
│                │                        │
│         ┌──────▼───────┐               │
│         │   Session    │               │
│         │   Manager    │               │
│         └──────┬───────┘               │
│                │                        │
│         ┌──────▼───────┐               │
│         │   Database   │               │
│         │  (SQLite)    │               │
│         └──────────────┘               │
│                                         │
└─────────────────────────────────────────┘

Agent Module

Purpose: Payload execution and C2 communication.

Components:

  • DoH client (doh_client.py)
  • HTTPS client (https_client.py)
  • Stealth module (stealth.py)
  • Executor module (executor.py)
  • Session manager (session.py)

Architecture:

┌─────────────────────────────────────┐
│         Agent (Payload)              │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐  ┌──────────────┐   │
│  │  Stealth │  │   Executor   │   │
│  │  Module  │  │   Module     │   │
│  └──────────┘  └──────────────┘   │
│       │              │              │
│       └──────┬───────┘              │
│              │                      │
│       ┌──────▼───────┐            │
│       │ C2 Client    │            │
│       │ (DoH/HTTPS)  │            │
│       └──────┬───────┘            │
│              │                     │
│       ┌──────▼───────┐            │
│       │   Session    │            │
│       │   Manager    │            │
│       └──────────────┘            │
│                                     │
└─────────────────────────────────────┘

Data Flow

Payload Generation Flow

User Input
    │
    ▼
Generator Module
    │
    ├──▶ Create Payload Template
    │
    ├──▶ Randomize Variables
    │
    ├──▶ Embed Agent Modules
    │
    ▼
Obfuscator Module (if enabled)
    │
    ├──▶ Standard Obfuscation
    │   └──▶ Variable randomization
    │   └──▶ Code encoding
    │
    └──▶ Enhanced Obfuscation (optional)
        └──▶ Anti-debug
        └──▶ VM detection
        └──▶ Junk code
    │
    ▼
Compiler Module (if enabled)
    │
    ├──▶ Nuitka Compilation
    │
    └──▶ Icon Injection (optional)
    │
    ▼
Output File (results/)

C2 Communication Flow

Agent (Target System)
    │
    ├──▶ Beacon Request
    │   └──▶ DoH Query / HTTPS POST
    │
    ▼
C2 Server
    │
    ├──▶ Process Request
    │   └──▶ Check Session
    │   └──▶ Get Command from Queue
    │
    ├──▶ Send Command
    │   └──▶ DNS Response / HTTPS Response
    │
    ▼
Agent
    │
    ├──▶ Execute Command
    │   └──▶ Executor Module
    │
    ├──▶ Format Response
    │   └──▶ STDOUT/STDERR/CWD/Return Code
    │
    ├──▶ Send Response
    │   └──▶ DoH Query / HTTPS POST
    │
    ▼
C2 Server
    │
    ├──▶ Save Response
    │   └──▶ Update Database
    │
    └──▶ Display in Web UI

Database Schema

Sessions Table

CREATE TABLE sessions (
    session_id TEXT PRIMARY KEY,
    hostname TEXT,
    username TEXT,
    platform TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_seen TIMESTAMP,
    deleted INTEGER DEFAULT 0
);

Command History Table

CREATE TABLE command_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT,
    command TEXT,
    response TEXT,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
);

Security Architecture

Encryption

  • Payload Communication: SSL/TLS for reverse shells
  • DoH C2: HTTPS encryption
  • HTTPS C2: HTTPS with certificate pinning
  • Payload Storage: Obfuscated code

Authentication

  • Certificate Pinning: HTTPS C2 uses certificate validation
  • Session IDs: Unique session identifiers
  • Domain Validation: DoH C2 validates domain

Evasion

  • Code Obfuscation: Multi-layer encoding
  • VM Detection: Sandbox evasion
  • Anti-Debugging: Debugger detection
  • Process Masquerading: Legitimate process disguise
  • Stealth Delays: Timing randomization

File Structure

OSRipper/
├── src/
│   └── osripper/
│       ├── __init__.py
│       ├── main.py          # Interactive mode
│       ├── cli.py           # CLI interface
│       ├── generator.py     # Payload generation
│       ├── obfuscator.py    # Standard obfuscation
│       ├── obfuscator_enhanced.py  # Enhanced obfuscation
│       ├── agent/           # Agent modules
│       │   ├── doh_client.py
│       │   ├── https_client.py
│       │   ├── stealth.py
│       │   ├── executor.py
│       │   └── session.py
│       └── c2/              # C2 server
│           ├── server.py
│           ├── doh_handler.py
│           ├── session_manager.py
│           ├── cert_utils.py
│           ├── templates/   # Web UI templates
│           └── static/      # Web UI assets
├── results/                 # Generated payloads
├── tmp/                     # Temporary files
└── wiki/                    # Documentation

Performance Considerations

Payload Size

  • Python Payload: ~10-50 KB
  • Obfuscated Payload: ~20-100 KB
  • Compiled Binary: ~5-20 MB

Generation Time

  • Basic Payload: < 1 second
  • Obfuscated: 1-5 seconds
  • Compiled: 30-120 seconds

C2 Server Performance

  • Concurrent Sessions: 100+ supported
  • Command Queue: In-memory + database
  • Response Time: < 100ms (local)

Scalability

Horizontal Scaling

  • Multiple C2 servers with load balancer
  • Shared database (future: PostgreSQL/MySQL)
  • Session replication (future feature)

Vertical Scaling

  • Increase server resources
  • Optimize database queries
  • Use connection pooling (future)

For implementation details, see the source code and Proof of Concept page.

Clone this wiki locally