htop for web servers, built for incident response.
See live who is on your site (IP, country, network), what they request, and what the web
server does because of it: the processes it starts, the files that get dropped into the web
root and the connections it opens. Webshells and reverse shells stand out, tied to the client
IP and the request that caused them.
- One file, nothing to install.
webtop.pyis Python 3 standard library only. Copy it to a suspect server and run it. Nopip, no agent, no config. - Finds everything itself. Apache, nginx, LiteSpeed / OpenLiteSpeed and php-fpm, their access logs and web roots, including inside Docker containers. Or point it at your own log file.
- Terminal UI and a web dashboard (
--web) with an interactive attack graph. - Hands off. It never changes, kills or deletes anything. Its only footprint: it reads the Apache / php-fpm status pages (see What WebTop touches).
All screenshots come from web01, a synthetic demo server in a throwaway container
(docs/demo/): documentation IP ranges, made-up countries, and a stand-in "webshell" that only
runs id; uname -a; sleep 4. No real system or visitor data.
You need Linux, Python 3.8+ (already installed on every current distribution) and root:
always start it with sudo. Without root WebTop cannot see other users' processes, sockets
or logs, and shows a red NOT ROOT box. Nothing else is installed.
Get the tool (one file):
curl -fLO https://raw.githubusercontent.com/RedSideSecurity/WebTop/main/webtop.py
chmod +x webtop.pyor clone the repository (tests, labs and the dashboard source included):
git clone https://github.com/RedSideSecurity/WebTop.git
cd WebTopRun WebTop on the server itself (the host), not inside a web container: from the host it sees every container too.
sudo ./webtop.py- The Overview opens: traffic for the last hour, status codes, top clients / URLs / countries and the latest serious alerts.
- Press 4 for Chains: one tree per suspicious IP, from the first request to every file
and process it caused. Rows marked
● LIVEare happening right now. - Press Enter on any row for details, h for help (it also explains every label on screen), q to quit.
| Key | View | Key | View |
|---|---|---|---|
| 1 | Overview | 6 | Conns: live connections, reverse shells and C2 first |
| 2 | Live: every request as it is logged | 7 | Procs: everything the web server started |
| 3 | Clients: one row per IP, activity sparkline | 8 | Files: scripts dropped into web roots |
| 4 | Chains: attack chain per attacker IP | 9 | Alerts: all detections, newest first |
| 5 | Now: requests still running (exact URL) | / filter · s sort · x expand · p pause |
Red boxes in the top line are problems to fix first, for example NOT ROOT: run with sudo,
NO LOG: ... or --trust-xff but no X-Forwarded-For in the log.
sudo ./webtop.py --scan-existing 30 --backfill 20000 --alert-log /root/webtop-alerts.jsonl--scan-existing 30sweeps the web roots once for scripts changed in the last 30 days that look like webshells, sit in upload folders, or were written by the web-server user. Hits appear in 8 Files and 9 Alerts.--backfill 20000reads the last 20,000 lines of every log at start (default 300), so requests from before you started are analysed too.- Leave it running. When someone uses the webshell, 4 Chains shows the client IP, the
request, the commands it ran (
sh,id,curl, ...) and any connection they opened. - Every alert is also appended to
/root/webtop-alerts.jsonl(one JSON object per line) for your case notes or SIEM.
WebTop finds the access logs itself (from the Apache / nginx / LiteSpeed configs on the host
and inside containers, plus the standard paths). To read only specific logs, name them with
-l: a file, a folder or a pattern.
sudo ./webtop.py -l /var/log/apache2/mysite_access.log # one file
sudo ./webtop.py -l /var/log/apache2/site1.log /var/log/nginx/site2.log
sudo ./webtop.py -l /var/log/apache2/ # a folder
sudo ./webtop.py -l '/home/*/logs/*access*.log' # a pattern: keep the quotes
sudo ./webtop.py -l /usr/local/apache/domlogs/example.com --backfill 100000 # cPanel, full history- With
-l, only the named logs are read. Processes, connections and dropped files are still watched as usual. - Error logs, rotated (
access.log.1) and compressed (.gz) logs are skipped automatically. - Formats: Apache
combinedandvhost_combined, nginx default, either of them with anX-Forwarded-Forfield at the end, and Docker json-file logs. logs:1/1in the top line = 1 log found, 1 readable. A log that cannot be read is named in a red box with the reason.
A container that logs to stdout (the official php, httpd and nginx images do) has no log
file inside; Docker keeps it on the host. WebTop finds it by itself; to name it:
sudo ./webtop.py -l "/var/lib/docker/containers/$(docker inspect -f '{{.Id}}' mycontainer)/*-json.log"Add --web to any command. The dashboard listens on the server's 127.0.0.1 only, so nobody
on the internet can reach it; you open it through an SSH tunnel.
# 1. on your PC (PowerShell, cmd, macOS or Linux terminal): open the tunnel, keep this window open
ssh -L 8800:127.0.0.1:8800 user@SERVER_IP
# 2. in that SSH session, on the server: start WebTop with the dashboard
sudo ./webtop.py --web # terminal UI + dashboard
sudo ./webtop.py --no-tui --web # dashboard only (run it in tmux / screen to keep it going)
# it prints: http://127.0.0.1:8800/?t=<token>
# 3. on your PC: open exactly that link (with ?t=...) in Chrome / Firefox- The token is new on every start. For a link that stays the same, choose it yourself:
--web-token MySecret123, then openhttp://127.0.0.1:8800/?t=MySecret123. - Another port:
--web 8801, and use the same number in the tunnel (-L 8801:127.0.0.1:8801). If the port is busy WebTop says so and suggests the next one. - In the terminal UI, press h to see the dashboard link again.
- Keep it running after you log out:
tmux new -s webtop 'sudo ./webtop.py --no-tui --web --web-token MySecret123'(detach:Ctrl+BthenD; back:tmux attach -t webtop). --web 0.0.0.0:8800listens on all addresses (plain HTTP, token-protected). Only on a trusted network or with the firewall open to your own IP.
# on a machine with internet: free DB-IP Lite databases (CC-BY), updated monthly
curl -fLO "https://download.db-ip.com/free/dbip-country-lite-$(date +%Y-%m).mmdb.gz"
curl -fLO "https://download.db-ip.com/free/dbip-asn-lite-$(date +%Y-%m).mmdb.gz"
gunzip dbip-*.mmdb.gz
ssh root@server mkdir -p /etc/webtop
scp dbip-*.mmdb root@server:/etc/webtop/
# on the server: looked up locally, nothing leaves the host
sudo ./webtop.py --geo offlineWebTop also finds MaxMind GeoLite2 files in /usr/share/GeoIP and /var/lib/GeoIP, or use
--geoip-db FILE.... --geo online asks ip-api.com instead: it sends client IPs to a third
party, only when you pass it, and fails cleanly when outbound traffic is blocked.
Then every client looks like the proxy (127.0.0.1, 172.17.0.1, a Cloudflare IP ...). The
real client IP is in the X-Forwarded-For header, but only if the server logs it. Add it at
the end of the log line:
# Apache: replace the existing "LogFormat ... combined" line (Debian / Ubuntu: /etc/apache2/apache2.conf),
# then: systemctl reload apache2
LogFormat "%h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\" \"%{X-Forwarded-For}i\"" combined# nginx (http { } block, use it with: access_log /var/log/nginx/access.log main;), then: nginx -s reload
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" "$http_x_forwarded_for"';then sudo ./webtop.py --trust-xff. Requests then show the real client, and a process started
by such a request is credited to it too, labelled <= proxy socket <proxy-ip> + X-Forwarded-For
(the connection belongs to the proxy; the client IP comes from the header). Only use it when
every request really comes through your proxy. X-Forwarded-For is just a header: a client that reaches the server directly can put
any IP in it and get someone else blamed. If --trust-xff is on but the log has no XFF field,
WebTop shows a red box.
| What you see | Fix |
|---|---|
NOT ROOT: run with sudo |
start it with sudo. Fix this first: it causes most of the problems below |
NO ACCESS LOG FOUND / logs:0/0 |
check sudo first, then name the logs: -l /var/log/apache2/ (see Recipe C) |
NO LOG: <name> / N log(s) unreadable |
a log you named cannot be read; press h for the path and reason (wrong path, or no sudo) |
NO LOG: error.log ... skipped |
-l named only error / rotated / compressed logs: name the access log instead |
NO LOG FILE: this server logs to stdout |
you started WebTop inside a container: run it on the host instead |
exec-mon:poll(container) |
same: inside a container only /proc polling works, very short commands can be missed |
every client is 127.0.0.1 / 172.17.0.1 |
behind a proxy: see --trust-xff |
fpm:0ok/1no-status |
add pm.status_path = /fpm-status to the php-fpm pool and reload php-fpm (no web-server change needed) |
port 8800 is already in use |
another WebTop (or service) has it: --web 8801 |
no XFF in log (--trust-xff but no X-Forwarded-For in the log) |
the log format has no XFF field yet: see --trust-xff |
geo: no .mmdb |
--geo offline found no database: see Recipe E |
dashboard answers 401 |
open the exact link printed at start (with ?t=), or set your own token: --web-token SECRET |
<= socket (URL ~guess ...) / spawn:sh? |
the client IP is proven, but it sent several requests at once and WebTop cannot prove which URL started the process. Check them all (Enter on the IP) |
a row says upload?(answered 404: unlikely) |
the only POST near the new file was rejected by the server: the file probably came another way (FTP, SSH, a process) |
When a site is hacked, the first questions are always the same: who is in, what did they
upload, what are they running, and are they still connected? The answers are spread over
the access log, the process list, ss and the file system, and attackers count on nobody
joining them up in time. WebTop joins them up live:
- a request in the access log →
- the file it wrote into the web root (inotify) →
- the process the web server started (netlink proc connector) →
- the connection that process opened (
/proc/net/tcp),
each link labelled with the evidence behind it, so you know what is proven and what is a guess.
1 Overview: the last hour of traffic, status codes, security summary, top clients / URLs / countries.
6 Conns: OUT = connections opened from web-server context (reverse shell / C2, always on
top), IN = client sessions. Closed ones stay visible for a few seconds (--linger).
7 Procs: every process the web server started, alive or exited, with the client IP and its parents.
9 Alerts: all detections, newest first, with repeat counters.
How to open it: Recipe D.
Attack graph: IP → URL → process / file → remote endpoint. Repeated commands fold into one
node (x5), live edges move. Drag, zoom, click any node for details.
Detail drawer: click any IP, process, file or alert. For a client: location, its attack chain (requests, dropped files, processes, connections), live connections, requests in flight.
Also: live requests, clients, in-flight requests, connections, processes, dropped files and
alerts as sortable, filterable tables; pause; dark / light theme (◐); works on a phone. Problems
(no root, no log ...) appear as a red bar at the top. Deep links: #graph,
#chains&open=ip:203.0.113.66, &light.
The dashboard shows attacker-controlled text, so it is built defensively:
- binds to 127.0.0.1 by default (use an SSH tunnel);
--web 0.0.0.0:8800only on purpose - a random token per run (or
--web-token), exchanged for an HttpOnly, SameSite=Strict session cookie; the token is removed from the URL and is never the cookie value - every attacker-controlled value is HTML-escaped and a strict Content-Security-Policy
with a per-run nonce (
default-src 'none', no inline handlers) means a missed escape still cannot run script. Tested in headless Chromium and real Chrome with<img onerror>,<svg onload>and<script>payloads in the URL and User-Agent X-Frame-Options: DENY,no-referrer,no-store, read-only API, fully self-contained (no CDN or web fonts, so it works on servers without internet)
| Source | Used for |
|---|---|
Access logs, found from Apache CustomLog, nginx access_log, LiteSpeed accessLog (host and containers) + standard paths; or -l file / glob / folder |
who, what, status. Formats: combined, vhost_combined, nginx with X-Forwarded-For, Docker json-file (containers that log to stdout) |
/proc/<pid>/net/tcp{,6} per network namespace + /proc/*/fd |
live connections (host and containers) and the process that owns each socket |
netlink proc connector (cn_proc) |
every exec in real time; a two-stage pipeline keeps the full command line even of sub-millisecond commands. Falls back to polling /proc |
inotify on web roots (Apache / nginx / LiteSpeed docroots, cPanel public_html, Plesk, container docroots via /proc/<pid>/root) |
scripts, .htaccess and .user.ini written or moved in; content signatures; owner |
Apache mod_status (auto: http://127.0.0.1/server-status) |
requests in flight; at exec time it asks which URL the spawning worker is serving |
| php-fpm status over raw FastCGI to each pool socket (also inside containers) | in-flight URL and script per worker, asked at exec time. Needs only pm.status_path in the pool |
lsphp process name (lsphp:/path/script.php), LiteSpeed .rtreport |
the exact script being run, per-vhost load |
/proc/<pid>/environ |
REMOTE_ADDR / REQUEST_URI for CGI / suEXEC children |
Every link shows its evidence (<= ... in the TUI, the Evidence column on the web):
| Evidence | Meaning | Servers |
|---|---|---|
socket |
the web-server worker that started the process holds that client's TCP connection: the IP is proven. If that client sent several requests at the same moment, the URL is marked URL ~guess |
Apache mod_php, CGI |
mod_status uri / php-fpm uri |
the worker was serving exactly this URL at exec time; matched to the log line | Apache, php-fpm (nginx, Apache + fpm, cPanel ea-php) |
lsphp script |
the LiteSpeed worker is named after the script; matched by path in LiteSpeed's own logs | LiteSpeed / OpenLiteSpeed |
env |
REMOTE_ADDR in the process environment |
CGI / suEXEC |
proxy socket … + X-Forwarded-For |
with --trust-xff: the worker holds the proxy's connection, the client IP comes from the logged header (spoofable if clients can bypass the proxy) |
any, behind a proxy |
parent sh(1234) |
child of a process that is already attributed (sh → sleep) |
any |
log / ~guess |
timing only, clearly marked; used only when nothing better exists | any |
Apache logs the time a request started and nginx the time it ended. WebTop knows this, so a process is tied to the request that was running when it started, and a request cannot be blamed for a file or process that appeared before it.
New or moved-in *.php|phtml|phar|inc|jsp|asp(x)|cgi|pl|py|sh, x.php.jpg, .htaccess,
.user.ini, php.ini.
| Severity | Why |
|---|---|
| CRIT | content signatures: eval(base64_decode(...)), system($_GET...), $_REQUEST['f'](...), fsockopen + proc_open reverse shells, known families (WSO, b374k, c99, r57, FilesMan, Alfa, IndoXploit, ...) |
| HIGH | script in an upload / static / cache folder; written by the web-server user; .htaccess / .user.ini handler tricks (AddHandler ... php, auto_prepend_file); obfuscated blobs; file uploaders |
| MED / LOW | double extensions; other new scripts. Mass changes (CMS update, deploy) fold into one INFO line |
The uploader is the POST / PUT that ran in the same seconds (flagged upload?; a request the
server rejected with 4xx / 5xx is marked as unlikely). This is timing, not proof. The first
request to the new file raises dropped-file-accessed: someone just used what was dropped.
| Severity | Rule |
|---|---|
| CRIT | reverse-shell: a shell or interpreter whose stdin / stdout / stderr is a TCP socket |
| CRIT | netcat-session: nc / ncat / socat / telnet / openssl with a live connection plus a child shell or -e / exec: |
| CRIT | web-spawn with a reverse-shell command line (/dev/tcp, sh -i, mkfifo, pty.spawn, ...) |
| HIGH | web-spawn: shell, interpreter, network tool or recon command started by the web server (sendmail, ImageMagick and similar are allowlisted) |
| HIGH | web-outbound: a process started by the web server connected out |
| HIGH | web-exe-tmp: web-context binary running from /tmp, /dev/shm or deleted |
| MED | worker-outbound: the PHP worker itself connected to an unusual port (PHP-native reverse shell / C2) |
script-in-upload-dir, webshell-filename, command-parameter (?cmd=id), php-code-in-url,
os-cmd-injection, log4shell, php-wrapper, path-traversal, sqli, sensitive-file,
scanner-ua, repeated-post-script (N POSTs a minute to one script = someone driving a
webshell), login-bruteforce, 404-scan, tool-ua (curl, wget, python-requests, Go and
similar clients). HIGH is downgraded when the server answered 4xx / 5xx.
Flags on a request in the chains: spawn:sh (this request started a process; spawn:sh? = this
client did, but which of its requests is not proven), dropped-file (it hit a file that appeared
while WebTop ran), upload? (probable uploader of a dropped file).
Rate rules alert once per client (per tool for scanners). In the chains, scanner noise folds
into one row per kind (GET /backup23.zip ... /backup0.zip -> 404 x24, 24 URLs), and a
webshell driven in a loop folds into one row with a counter.
-l PATH... access log file(s), glob or folder (default: from server configs + standard paths)
--web [HOST:]PORT web dashboard (default 127.0.0.1:8800) --web-token T fixed token (default random)
--no-tui headless (with --web / --alert-log / --stream)
--geo off|offline|online|auto --geoip-db MMDB... (default off; auto never goes online)
--watch DIR... extra web roots to watch --no-watch --watch-max N (20000) --scan-existing DAYS
--trust-xff client = X-Forwarded-For (behind CDN / load balancer / docker-proxy)
--linger S keep closed connections visible (5) --refresh S (1.0) --backfill N lines (300)
--status-url URL Apache mod_status --no-status --no-fpm --no-exec --full-fds
--ports 80,443,... extra ports that count as web ports (listeners of the web server are added automatically)
--post-burst N (8) --min-sev LOW|MED|HIGH|CRIT --alert-log FILE.jsonl --stream alerts|requests|all
--once --duration S print one JSON snapshot and exit (for scripts / ProcSnap)
--version print the version
WebTop never writes to, changes, kills or deletes anything on the server. To be exact about its footprint:
- it reads logs,
/proc, and inotify events (--alert-logwrites only the file you name) - it sends HTTP GET
/server-statusto the local Apache (only when Apache runs): every 15 s, every 2 s while the Now view or the dashboard is open, and once when a process is started. Apache logs these requests (User-Agentwebtop/<version> (local status poller); WebTop hides them from its own views). Turn it off with--no-status, or keep them out of the log:SetEnvIf User-Agent "^webtop/" dontlog+CustomLog ... combined env=!dontlog - it asks each php-fpm pool for its status page over FastCGI (straight to the pool socket; the web server does not see or log it)
--geo onlineonly: client IPs are sent to ip-api.com
| Term | In one line |
|---|---|
| webshell | a script an attacker uploads to the site to run commands through the browser |
| reverse shell | a shell on the server whose input / output is a network connection to the attacker |
| attribution / evidence | how WebTop knows which client caused a process or file, and how sure it is |
| netlink proc connector | a Linux kernel feature that reports every new process instantly (root only) |
| inotify | a Linux kernel feature that reports new files in a folder instantly |
| mod_status | Apache's status page: which worker serves which client and URL right now |
| php-fpm status | the same for php-fpm pools (pm.status_path) |
| lsphp | LiteSpeed's PHP worker; its process name contains the script it runs |
| X-Forwarded-For (XFF) | header in which a proxy / CDN passes on the real client IP |
| backfill | reading the last N lines of a log at start, so earlier requests are analysed too |
python3 -m unittest -v tests/test_unit.py # 85 tests; a few need root, the rest run anywhere
sudo python3 tests/check_sim.py 3 # end-to-end against the safe simulator (18 checks)
sudo tests/lab/apache_lab.sh up; sudo tests/lab/nginx_lab.sh up; sudo tests/lab/ols_lab.sh up
sudo python3 tests/check_labs.py # end-to-end against REAL Apache / nginx+php-fpm / OpenLiteSpeed (20)The labs and the simulator use fixed, harmless pages only (spawn.php runs date; sleep 3,
slow.php sleeps) plus files written by www-data: the same signals a webshell produces,
without one. tests/simulate.py fakes a php-fpm worker and a reverse-shell-shaped bash
(stdin = loopback socket, it only runs sleep). GitHub Actions runs the unit tests on Python
3.8 to 3.13 and the root tests (netlink + simulator) on every push.
Verified 2026-11-04 (Ubuntu 24.04, kernel 6.8, Docker):
| Area | Result |
|---|---|
| Unit tests | 85/85 on Python 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13: log parsing (combined / vhost / nginx + XFF / docker-json / IPv6), every rule, no false positives on 19 normal WordPress / app URLs, webshell signatures (no hits on benign PHP), inotify, log rotation, php-fpm config + FastCGI, LiteSpeed report, .mmdb reader, attribution, chains, dashboard auth / CSP / API |
Real servers (check_labs.py) |
20/20 in every run (3 in a row for this version): log discovery on the host and in containers, php-fpm status, LiteSpeed report, inotify; in-flight requests from mod_status / php-fpm / lsphp; exact attribution on Apache mod_php (socket + mod_status URL), nginx + php-fpm (php-fpm URI + XFF), OpenLiteSpeed (lsphp script); dropped files on the host and in a container, first access → right IP; chains for every attacker |
Simulator (check_sim.py) |
18/18 × 3 rounds: CRIT reverse shell, worker outbound, short-lived commands, allowlist, all log rules |
| Exec capture | 294 of 300 sub-millisecond commands in a burst captured with the full command line |
Demo server (docs/demo) |
the full story in a container: scan → upload → dropped file → commands → reverse-shell-shaped bash to 203.0.113.66:4444, every step tied to the right client; it produced the screenshots above |
| Dashboard | headless Chromium: all views render (dark / light / 420 px phone), XSS payloads stay text, no inline event handlers |
| TUI | all 9 views, popups, filter, sort, resize from 30×8 to 260×70, clean exit, with --web running |
| Performance | ~38 ms per refresh with everything on (116 processes, 10 network namespaces, 9 logs, 94 watched folders); ~12k log lines/s through all rules; ~85 MB RSS after 20k requests / 8.8k clients |
- Not yet tested on a real CloudLinux / cPanel / LiteSpeed Enterprise server. LiteSpeed was tested with OpenLiteSpeed; cPanel domlogs and ea-php pools are supported from their known layouts. CloudLinux LVE / CageFS statistics are not read yet.
- No real webshell or reverse shell was run during development: the simulator, the labs and the demo use fixed, harmless commands that produce the same signals.
- Exec capture is very good but not guaranteed under extreme bursts (~98%). Use auditd or eBPF if you need every single exec.
- HTTPS URLs come from the logs (no TLS decryption). Requests still in flight have a URL only
through mod_status, php-fpm or lsphp. nginx without php-fpm status falls back to timing
(
~guess). - Behind
docker-proxyor a CDN the socket IP is the proxy: logX-Forwarded-Forand use--trust-xff. - Not a WAF or a blocker: deliberately read-only.
procsnap.py webtopsubcommand in ProcSnap, and the--onceJSON snapshot in ProcSnap's case collection- CloudLinux LVE / CageFS per-user context
- optional eBPF exec capture where available
MIT © RedSide Security. See LICENSE and SECURITY.md.









