Skip to content
RedSideSecurityPublic

About

htop for web servers, built for incident response: live clients, requests, web-spawned processes, dropped webshells and reverse shells, tied to the client IP. One stdlib Python file, TUI + web dashboard.

Topics

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

RedSide WebTop

tests python dependencies license

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.

WebTop attack chains: scanner, upload, dropped webshell, commands, then a reverse shell to 203.0.113.66:4444, all tied to the client IP

  • One file, nothing to install. webtop.py is Python 3 standard library only. Copy it to a suspect server and run it. No pip, 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.

Quick start

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.py

or clone the repository (tests, labs and the dashboard source included):

git clone https://github.com/RedSideSecurity/WebTop.git
cd WebTop

Run WebTop on the server itself (the host), not inside a web container: from the host it sees every container too.

Recipe A: who is on my site right now? (10 seconds)

sudo ./webtop.py
  1. The Overview opens: traffic for the last hour, status codes, top clients / URLs / countries and the latest serious alerts.
  2. Press 4 for Chains: one tree per suspicious IP, from the first request to every file and process it caused. Rows marked ● LIVE are happening right now.
  3. 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.

Recipe B: I think there is a webshell on this server

sudo ./webtop.py --scan-existing 30 --backfill 20000 --alert-log /root/webtop-alerts.jsonl
  1. --scan-existing 30 sweeps 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.
  2. --backfill 20000 reads the last 20,000 lines of every log at start (default 300), so requests from before you started are analysed too.
  3. 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.
  4. Every alert is also appended to /root/webtop-alerts.jsonl (one JSON object per line) for your case notes or SIEM.

Recipe C: use your own log file (-l)

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 combined and vhost_combined, nginx default, either of them with an X-Forwarded-For field at the end, and Docker json-file logs.
  • logs:1/1 in 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"

Recipe D: web dashboard, step by step

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 open http://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+B then D; back: tmux attach -t webtop).
  • --web 0.0.0.0:8800 listens on all addresses (plain HTTP, token-protected). Only on a trusted network or with the firewall open to your own IP.

Recipe E: countries and networks, without sending IPs anywhere

# 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 offline

WebTop 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.

Behind a proxy, CDN or load balancer (--trust-xff)

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.

Common problems

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)

Why this exists

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.

Terminal UI

1 Overview: the last hour of traffic, status codes, security summary, top clients / URLs / countries.

Overview: requests per minute for the last hour, status codes, security summary, top clients, URLs and 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).

Connections: the reverse shell to 203.0.113.66:4444 at the top, then live client sessions

7 Procs: every process the web server started, alive or exited, with the client IP and its parents.

Processes started by the web server, with client IP and parent chain

9 Alerts: all detections, newest first, with repeat counters.

Alerts: reverse-shell, web-outbound, web-spawn, repeated-post-script

Web dashboard (--web)

How to open it: Recipe D.

Dashboard overview: KPI tiles, requests per minute and per second, status codes, top clients, URLs and countries

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.

Attack graph: client IPs, URLs, processes, the dropped file and the outbound endpoint, live edges animated

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.

Detail drawer for 198.51.100.7: location, attack chain, live connection, in-flight request

More: attack chains in the browser, light theme

Attack chains in the browser

Light theme

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:8800 only 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)

How it works

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

Which client caused this process or file?

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.

Dropped-file watcher

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.

Process and network detections

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)

Request (log) detections

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.

All options

-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

What WebTop touches

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-log writes only the file you name)
  • it sends HTTP GET /server-status to 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-Agent webtop/<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 online only: client IPs are sent to ip-api.com

Glossary

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

Testing

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

Limits (honest)

  • 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-proxy or a CDN the socket IP is the proxy: log X-Forwarded-For and use --trust-xff.
  • Not a WAF or a blocker: deliberately read-only.

Roadmap

  • procsnap.py webtop subcommand in ProcSnap, and the --once JSON snapshot in ProcSnap's case collection
  • CloudLinux LVE / CageFS per-user context
  • optional eBPF exec capture where available

License

MIT © RedSide Security. See LICENSE and SECURITY.md.

About

htop for web servers, built for incident response: live clients, requests, web-spawned processes, dropped webshells and reverse shells, tied to the client IP. One stdlib Python file, TUI + web dashboard.

Topics

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages