EtherReaper includes a full PTY-backed bash terminal accessible from within the browser. The shell runs as your regular user in the app directory (etherreaper/), persists across page navigations and reconnects, and stores per-session command history.
Navigate to TOOLS → Shell in the sidebar.
Features
- Persistent sessions — the bash process keeps running if you navigate away and reconnect. The session is keyed by a
session_id so the same terminal resumes on reconnect.
- Full PTY support — terminal size (rows/cols) is synchronized via
TIOCSWINSZ. Colors, readline, and interactive tools (htop, vim) work normally.
- Per-session history — command history is stored in
data/.shell_hist_<session_id> and persisted via HISTFILE and PROMPT_COMMAND="history -a". Up to 5000 commands.
- Snippets library — a pre-loaded library of common pentest commands (Nmap, netexec, Impacket, Responder, hashcat) available as one-click paste.
WebSocket interface
The shell is served over a WebSocket:
WS /ws/shell/{session_id}
session_id is a UUID generated by the frontend and reused on reconnect. The first connection spawns a new bash process with a custom .bashrc that sets up the history file. Subsequent connections with the same session_id reattach to the existing process (if still alive) or start a new one.
Snippets
GET /api/shell/snippets
Returns all available command snippets.
curl http://localhost:8000/api/shell/snippets
{
"snippets": [
{
"id": 1,
"name": "Quick Scan",
"command": "nmap -T4 -F {target}",
"category": "Nmap",
"source": "file"
}
]
}
POST /api/shell/snippets
Create a custom snippet.
curl -X POST http://localhost:8000/api/shell/snippets \
-H "Content-Type: application/json" \
-d '{
"name": "My Scan",
"command": "nmap -sV {target}",
"category": "Custom"
}'
PUT /api/shell/snippets/
Update an existing snippet.
DELETE /api/shell/snippets/
Delete a snippet.
Command history
GET /api/shell/history
Retrieve recent command history for a session.
curl "http://localhost:8000/api/shell/history?session_id=<uuid>&limit=100"
limit commands (default 100) from the session’s history file.
GET /api/shell/history/export
Download the full history as a plain text file.
curl "http://localhost:8000/api/shell/history/export?session_id=<uuid>"
DELETE /api/shell/history
Clear history for a session.
curl -X DELETE "http://localhost:8000/api/shell/history?session_id=<uuid>"
Pre-loaded snippet categories
The snippets table is seeded at startup from data/commands.json (generated from the commands/ directory). Built-in categories include:
| Category | Commands |
|---|
| Nmap | Quick Scan, Service Scan, Full Port Scan, UDP Top 100 |
| Masscan | Masscan Fast, Masscan All Ports |
| NetExec | SMB Null, SMB Auth, SMB Shares, SMB Signing Check, LDAP DC List, Pass Policy, Kerberoast, ASREPRoast, BloodHound, RID Brute, Delegation, MAQ, GMSA, Pre2K |
| Responder | Responder (analyze), Responder (capture), mitm6 |
| Impacket | GetTGT, SecretsDump, PSExec, WMIExec, SMBExec |
| Cracking | Crack NTLM (hashcat -m 1000), Crack NTLMv2 (hashcat -m 5600) |
| Recon | Ping Sweep, ARP Scan, Netdiscover |
{target}, {user}, {password}, {domain}, {interface}, and {dc_ip} placeholder tokens. The UI replaces these with values from the Network Info bar before pasting into the terminal.
Session persistence details
When the WebSocket connects:
- If
session_id exists in SHELL_SESSIONS and the bash PID is still alive → reattach to the existing PTY file descriptor.
- If the session is gone (process exited, app restarted) → spawn a new bash process with
pty.fork() and a fresh RC file.
The RC file (data/.shell_rc_<session_id>) configures history before the prompt appears and is deleted 1 second after startup. History is continuously flushed to disk via PROMPT_COMMAND="history -a".
The shell runs with your regular user’s environment and in the etherreaper/ app directory. The venv/ and all tools installed by setup.sh are accessible. Run source venv/bin/activate if you need to use Python packages directly.