dragon-lady/netward-standaloneUser-space bot and DDoS deflection for small HTTP services
A user-space deception layer that turns DDoS and bot abuse into wasted effort.
Net Ward sits in front of your HTTP service as a reverse proxy. Real traffic passes through untouched. Known probes and floods get harmless mirror responses that burn bot effort and never reach your app — no kernel hooks, no payloads, no retaliation, fail-open by design.
Built and maintained by Dragon Lady — github.com/Dragon-Lady · X: @answerislove2 Independent security researcher tracking live supply-chain and bot-abuse campaigns in the wild.
Website: dragon-lady.github.io/netward-standalone
python -m pip install --upgrade "netward>=0.4.12"
python -m netward --config example_config.json
Version 0.4.12 or newer is the recommended baseline for new installations and upgrades. Older releases remain available for reproducibility; new deployments should use the current release.
Or from source:
git clone https://github.com/Dragon-Lady/netward-standalone
cd netward-standalone
pip install -e .
Net Ward listens on listen_address and forwards clean traffic to upstream_target.
Copy the example config and edit the upstream target:
cp example_config.json config.json
Point upstream_target at a real HTTP service before you start Net Ward. If
the upstream is unreachable, unmatched requests return a default mirror response
instead of exposing a raw proxy error.
Required fields:
| Field | Meaning |
|---|---|
node_id | Stable name for this Net Ward instance |
upstream_target | HTTP service being protected |
listen_address | Host and port Net Ward binds |
Optional fields control mirror intensity, local storage, mesh placeholders, alert channels, upstream timeouts, and probe-log retention. A pattern match or the start of a request flood records an alert in SQLite. Alerts are deduplicated by kind, source, and pattern for five minutes. An empty alert_channels list sends to stdout; select any combination of stdout, email, slack, and ntfy for explicit delivery. Outbound delivery runs in the background and retries failed channels. Recent undelivered alerts are retried on startup.
Email requires alert_email, alert_smtp_host, and alert_smtp_from. Set alert_smtp_port and alert_smtp_security (starttls, ssl, or none); none is permitted only for a loopback SMTP server. If authentication is needed, set alert_smtp_username and alert_smtp_password_env to the name of an environment variable containing the password. Slack requires alert_slack_webhook. ntfy requires alert_ntfy_topic (a topic on ntfy.sh or a full self-hosted topic URL); for a protected topic, set alert_ntfy_token_env to the name of an environment variable containing its bearer token. HTTP destinations must use HTTPS except on loopback. alert_timeout_secs defaults to five seconds. Net Ward checks requested destinations at startup and stores successful delivery receipts in the alerts table. Alert messages contain the source IP, pattern ID, and classification; they do not include raw request bodies or headers.
| Optional field | Default | Meaning |
|---|---|---|
upstream_timeout_total | 10 | Whole-request budget for the upstream call, in seconds |
upstream_timeout_connect | 3 | Connect (DNS + TCP + TLS) timeout, in seconds |
upstream_timeout_sock_read | 5 | Idle time between upstream socket reads, in seconds |
upstream_max_concurrency | 64 | In-flight upstream requests |
upstream_max_body_bytes | 8388608 | Max buffered upstream response body (8 MiB). Larger bodies fail-open to the default mirror |
probe_retention_secs | 604800 | Probe-log TTL (7 days) |
probe_max_rows | 10000 | Max probe-log rows after purge-on-write |
alert_timeout_secs | 5 | Per-channel timeout for outbound alert delivery, in seconds |
python -m netward --config config.json
Example topology:
| Component | Address |
|---|---|
| Net Ward | 127.0.0.1:8080 |
| Upstream app | http://127.0.0.1:9000 |
| Storage | netward.db |
Point your load balancer or web server at Net Ward. Keep the upstream app reachable only from the host or trusted network when possible.
Set listen_address to 0.0.0.0:<port> only when you intentionally want Net Ward reachable beyond localhost.
On Linux/macOS, keep storage_path non-world-writable. Example: chmod 600 netward.db, or chmod 644 netward.db only if you intentionally need read access for monitoring.
Net Ward sustains its documented per-box capacity continuously, but Python runtime memory pools may retain working-set state after sustained heavy load. Operators running Net Ward under continuous heavy traffic should monitor process resource usage and restart the daemon periodically, for example weekly or when RSS exceeds 2x baseline. v0.5 will refine this guidance based on operator feedback and local test observations, not automatic telemetry.
Clean request should reach upstream:
curl -i http://127.0.0.1:8080/
Known probe should be mirrored:
curl -i http://127.0.0.1:8080/wp-admin/
The WordPress probe returns a fake login page. The upstream service does not receive the request.
With the example topology above, a healthy first run should look like this:
127.0.0.1:9000.127.0.0.1:8080./ through Net Ward and confirm the upstream response comes back./wp-admin/ through Net Ward and confirm a mirror response comes back instead.Expected result: normal traffic reaches the upstream app, while the known probe is handled by Net Ward's mirror layer. This is the simplest signal that the proxy path, pattern match, and mirror response are all working.
Install or refresh the bundled vendor pattern set:
python -m netward.cli --db netward.db install-patterns
python -m netward.cli --db netward.db install-patterns --force
List active patterns:
python -m netward.cli --db netward.db list-patterns
Read a probe report without writing the database. The report is aggregate
counts: which probe families fired, which request-path totals those families
hit, and how many sources were involved. It does not print raw IP addresses
or geography. --send delivers that same digest — path counts included,
never raw IPs. Output files are owner-only (0600).
python -m netward.cli --db netward.db report
python -m netward.cli --db netward.db report --since 7d --format md --output report.md
python -m netward.cli --db netward.db report --format html --output report.html
python -m netward.cli --db netward.db report --family wordpress --top 10
python -m netward.cli --db netward.db report --send --config config.json