# 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

```sql
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

```sql
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](Proof-Of-Concept) page.*