# Web UI Guide

The OSRipper Web UI provides a modern, browser-based interface for managing C2 operations, generating payloads, and interacting with compromised systems.

## Overview

The Web UI includes:
- **Dashboard** - Overview of all active sessions
- **Session Management** - Detailed session views and command execution
- **Payload Generator** - Generate DoH and HTTPS payloads via web interface
- **Command History** - Track all executed commands and responses

## Accessing the Web UI

### Starting the C2 Server

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

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

# With HTTPS
python -m osripper.c2.server example.com --https

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

### Accessing the Interface

Once the server is running:
- **HTTP**: `http://localhost:5000`
- **HTTPS**: `https://localhost:5000` (if enabled)
- **Remote Access**: `http://your-domain:5000`

## Dashboard

The dashboard provides an overview of all active C2 sessions.

### Features

- **Session List** - View all active sessions in a table
- **Session Count** - Badge showing number of active sessions
- **Quick Actions** - View session details or delete sessions
- **Generate Payload** - Quick access to payload generator

### Session Information

Each session displays:
- **Session ID** - Unique identifier (truncated for display)
- **Hostname** - Target system hostname
- **Username** - Current user on target system
- **Platform** - Operating system information
- **Last Seen** - Last contact timestamp
- **Status** - Active/Inactive status

### Actions

- **View** - Click "View" button to open session details
- **Delete** - Click "Delete" button to terminate session
- **Generate Payload** - Navigate to payload generator

## Session Management

Click on any session to view detailed information and execute commands.

### Session Details Panel

Displays:
- **Full Session ID** - Complete session identifier
- **Hostname** - Target system hostname
- **Username** - Current user
- **Platform** - OS version and details
- **Last Seen** - Last contact time
- **Status** - Current session status

### Command Terminal

Interactive terminal for executing commands on the target system.

#### Sending Commands

1. Enter command in the input field
2. Click "Send" or press Enter
3. Command is queued for the agent
4. Response appears when agent checks in

#### Command Status

- **Sending** - Command being queued
- **Waiting** - Waiting for agent response
- **Complete** - Response received
- **Error** - Error occurred

#### Response Display

Responses are formatted with:
- **CWD** - Current working directory
- **Return Code** - Command exit code (green for 0, red for non-zero)
- **STDOUT** - Standard output
- **STDERR** - Standard error output

### Command History

View all executed commands and their responses:
- Commands are stored in database
- Responses include full output
- History persists across sessions

## Payload Generator

Generate DoH and HTTPS C2 payloads directly from the web interface.

### Accessing Generator

1. Click "Generate Payload" button in navigation
2. Or navigate to `/generate` endpoint

### Payload Types

#### DNS-over-HTTPS C2

**Configuration:**
- **C2 Domain Name** - Domain for DoH communication (e.g., `example.com`)
- **Output Filename** - Name for generated payload
- **Stealth Delay** - Add random startup delay
- **Testing Mode** - Skip VM detection checks
- **Obfuscation** - Enable code obfuscation
- **Enhanced Obfuscation** - Advanced evasion techniques
- **Compile to Binary** - Create standalone executable

**Steps:**
1. Select "DNS-over-HTTPS C2" from dropdown
2. Enter domain name
3. Configure options
4. Click "Generate Payload"
5. Download generated file

#### HTTPS C2 (Certificate Pinning)

**Configuration:**
- **C2 Base URL** - Full HTTPS URL (e.g., `https://example.com`)
- **Certificate Fingerprint** - SHA256 fingerprint (auto-filled if server has HTTPS)
- **Output Filename** - Name for generated payload
- **Stealth Delay** - Add random startup delay
- **Testing Mode** - Skip VM detection checks
- **Obfuscation** - Enable code obfuscation
- **Enhanced Obfuscation** - Advanced evasion techniques
- **Compile to Binary** - Create standalone executable

**Steps:**
1. Select "HTTPS C2 (Certificate Pinning)" from dropdown
2. Enter base URL
3. Certificate fingerprint auto-fills (if server has HTTPS)
4. Configure options
5. Click "Generate Payload"
6. Download generated file

### Certificate Fingerprint

For HTTPS payloads, the certificate fingerprint is automatically retrieved if:
- Server is running with HTTPS enabled
- Certificate is accessible

**Manual Fingerprint:**
```bash
# Get fingerprint from running server
curl http://localhost:5000/api/cert-fingerprint

# Or from URL
curl -X POST http://localhost:5000/api/cert-fingerprint-from-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

### Generation Options

**Common Options:**
- **Output Filename** - Custom name for payload
- **Stealth Delay** - Random 5-15 second delay at startup
- **Testing Mode** - Skip VM detection (for testing in VMs)

**Obfuscation:**
- **Obfuscate Payload** - Enable multi-layer obfuscation
- **Enhanced Obfuscation** - Anti-debug, VM detection, advanced evasion (requires obfuscation)

**Compilation:**
- **Compile to Binary** - Create standalone executable
- **Icon File Path** - Custom icon for compiled binary (.ico file)

### Downloading Payloads

After generation:
- **Python Payload** - `.py` file (or `_or.py` if obfuscated)
- **Binary Payload** - `.bin` file (if compiled)

Files are located in:
- `tmp/` directory for Python files
- `tmp/results/` or `results/` for obfuscated/compiled files

## API Endpoints

The Web UI uses REST API endpoints for functionality.

### Session Endpoints

```bash
# Get all sessions
GET /api/sessions

# Get session details
GET /api/session/<session_id>

# Delete session
DELETE /api/session/<session_id>

# Send command
POST /api/session/<session_id>/command
Body: {"command": "ls -la"}

# Get command history
GET /api/session/<session_id>/history?limit=100
```

### Payload Generation

```bash
# Generate payload
POST /api/generate-payload
Body: {
  "payload_type": "doh",
  "domain": "example.com",
  "obfuscate": true,
  "compile": true,
  ...
}
```

### Certificate

```bash
# Get certificate fingerprint
GET /api/cert-fingerprint

# Get fingerprint from URL
POST /api/cert-fingerprint-from-url
Body: {"url": "https://example.com"}
```

### Downloads

```bash
# Download generated file
GET /api/download/<filename>
```

## Best Practices

### Security

1. **Use HTTPS** - Enable HTTPS for production deployments
2. **Certificate Pinning** - Use certificate pinning for HTTPS payloads
3. **Access Control** - Implement firewall rules to restrict access
4. **Authentication** - Consider adding authentication (future feature)

### Performance

1. **Session Limits** - Monitor number of active sessions
2. **Database Size** - Periodically clean old session data
3. **Response Times** - Use appropriate polling intervals

### Operations

1. **Regular Backups** - Backup session database regularly
2. **Logging** - Monitor server logs for issues
3. **Testing** - Test payloads in controlled environments first

## Troubleshooting

### Web UI Not Loading

- Check if server is running
- Verify port is not in use
- Check firewall settings
- Review server logs for errors

### Sessions Not Appearing

- Verify payload is connecting to correct domain
- Check DNS resolution
- Review agent logs
- Verify database is accessible

### Commands Not Executing

- Check if session is active (last seen timestamp)
- Verify agent is polling for commands
- Review command queue in database
- Check agent logs for errors

### Payload Generation Fails

- Verify all required fields are filled
- Check server logs for errors
- Ensure write permissions in tmp/ directory
- Verify dependencies are installed

## Advanced Usage

### Custom Domain Setup

1. **DNS Configuration**: Point domain to server IP
2. **Port Forwarding**: Forward port 5000 (or custom port)
3. **SSL Certificate**: Use Let's Encrypt or custom certificate
4. **Firewall Rules**: Allow incoming connections

### Database Management

```bash
# View database
sqlite3 c2_sessions.db

# Backup database
cp c2_sessions.db c2_sessions_backup.db

# Clean old sessions (manual)
sqlite3 c2_sessions.db "DELETE FROM sessions WHERE last_seen < datetime('now', '-30 days');"
```

### Custom Configuration

Edit server configuration:
- Port: `--port` flag
- Database: `--db` flag
- HTTPS: `--https` flag
- Certificate: `--cert` and `--key` flags

---

*For more information, see the [C2 Server Guide](C2-Server-Guide) and [Troubleshooting](Troubleshooting) pages.*