Installation

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)

# 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:

# 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:

# 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)

# 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

# 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

# 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:

# 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
2. Extract and add to PATH
3. Get free API key from dashboard.ngrok.com

# Configure ngrok
ngrok config add-authtoken YOUR_AUTH_TOKEN

Verifying Installation

After installation, verify everything works:

# 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:

python3 -m osripper

Issue: "Module not found" errors

Solution: Reinstall dependencies:

pip3 install -r requirements.txt --force-reinstall

Issue: Permission errors

Solution: Use --user flag or virtual environment:

pip3 install -r requirements.txt --user

Issue: Nuitka compilation fails

Solution: Ensure all system dependencies are installed:

# 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:

# Initialize Metasploit database
msfdb init

# Start Metasploit
msfconsole

2. Test Payload Generation

Generate a test payload to verify everything works:

# 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:

# 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:

# 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:

# Uninstall package
pip3 uninstall osripper

# Remove repository (optional)
rm -rf OSRipper

Next Steps

After installation:

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

---

For troubleshooting, see the Troubleshooting Guide