# Installation Guide

This guide covers installing OSRipper on different platforms and setting up all required dependencies.

## Prerequisites

- **Python 3.6 or higher** (Python 3.8+ recommended)
- **Git** for cloning the repository
- **Metasploit Framework** (optional, for listeners)
- **Nuitka** (optional, for binary compilation)

## Installation Methods

### Method 1: Standard Installation (Recommended)

```bash
# Clone the repository
git clone https://github.com/SubGlitch1/OSRipper.git
cd OSRipper

# Install dependencies
pip3 install -r requirements.txt

# Install OSRipper as a package
pip3 install -e .
```

After installation, you can use:
- `osripper` - Interactive mode
- `osripper-cli` - Command-line interface

### Method 2: Development Installation

For development or if you want to modify the code:

```bash
# Clone repository
git clone https://github.com/SubGlitch1/OSRipper.git
cd OSRipper

# Install in development mode
pip3 install -e .[dev]

# Or install dependencies manually
pip3 install -r requirements.txt
```

### Method 3: Virtual Environment (Recommended)

Using a virtual environment isolates dependencies:

```bash
# Create virtual environment
python3 -m venv osripper-env

# Activate virtual environment
# On Linux/macOS:
source osripper-env/bin/activate
# On Windows:
osripper-env\Scripts\activate

# Install OSRipper
cd OSRipper
pip3 install -r requirements.txt
pip3 install -e .
```

## Platform-Specific Instructions

### Linux (Ubuntu/Debian)

```bash
# Update package list
sudo apt update

# Install Python and dependencies
sudo apt install python3 python3-pip python3-venv git -y

# Install Metasploit (optional)
sudo apt install metasploit-framework -y

# Install OSRipper
git clone https://github.com/SubGlitch1/OSRipper.git
cd OSRipper
pip3 install -r requirements.txt
pip3 install -e .
```

### macOS

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3 git

# Install OSRipper
git clone https://github.com/SubGlitch1/OSRipper.git
cd OSRipper
pip3 install -r requirements.txt
pip3 install -e .
```

### Windows

```powershell
# Install Python from python.org (ensure "Add to PATH" is checked)

# Install Git from git-scm.com

# Open PowerShell or Command Prompt
git clone https://github.com/SubGlitch1/OSRipper.git
cd OSRipper
pip install -r requirements.txt
pip install -e .
```

## Optional Dependencies

### Nuitka (Binary Compilation)

Required for compiling payloads to standalone binaries:

```bash
# Install Nuitka
pip3 install nuitka

# Verify installation
python3 -m nuitka --version
```

### Ngrok (Dynamic Tunneling)

For dynamic IP addresses and port forwarding:

1. Download from [ngrok.com](https://ngrok.com/)
2. Extract and add to PATH
3. Get free API key from [dashboard.ngrok.com](https://dashboard.ngrok.com/api)

```bash
# Configure ngrok
ngrok config add-authtoken YOUR_AUTH_TOKEN
```

## Verifying Installation

After installation, verify everything works:

```bash
# Check version
osripper-cli --version

# Or
python3 -m osripper --version

# Test interactive mode
osripper

# Test CLI
osripper-cli --help
```

## Common Installation Issues

### Issue: "Command not found: osripper"

**Solution**: Ensure the installation directory is in your PATH, or use:
```bash
python3 -m osripper
```

### Issue: "Module not found" errors

**Solution**: Reinstall dependencies:
```bash
pip3 install -r requirements.txt --force-reinstall
```

### Issue: Permission errors

**Solution**: Use `--user` flag or virtual environment:
```bash
pip3 install -r requirements.txt --user
```

### Issue: Nuitka compilation fails

**Solution**: Ensure all system dependencies are installed:
```bash
# On Ubuntu/Debian
sudo apt install build-essential python3-dev

# On macOS
xcode-select --install
```

## Post-Installation Setup

### 1. Configure Metasploit (Optional)

If using Metasploit for listeners:

```bash
# Initialize Metasploit database
msfdb init

# Start Metasploit
msfconsole
```

### 2. Test Payload Generation

Generate a test payload to verify everything works:

```bash
# Simple reverse shell
osripper-cli reverse -H 127.0.0.1 -p 4444 --output test

# Check if payload was created
ls -la test.py
```

### 3. Start C2 Server (Optional)

Test the web UI:

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

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

## Updating OSRipper

To update to the latest version:

```bash
# Navigate to OSRipper directory
cd OSRipper

# Pull latest changes
git pull origin main

# Reinstall
pip3 install -r requirements.txt --upgrade
pip3 install -e . --upgrade
```

## Uninstallation

To remove OSRipper:

```bash
# Uninstall package
pip3 uninstall osripper

# Remove repository (optional)
rm -rf OSRipper
```

## Next Steps

After installation:

1. Read the [Quick Start Guide](Quick-Start)
2. Explore [Payload Types](Payload-Types)
3. Learn about the [Web UI](Web-UI-Guide)
4. Review [Advanced Features](Advanced-Features)

---

*For troubleshooting, see the [Troubleshooting Guide](Troubleshooting)*