Network protection
Stacklane does not detect attacks itself. It receives attack reports from your DDoS detector, for example FastNetMon, through a signed webhook. It links each report to the customer's instance, shows the attack history in the portal and can email the customer. This page also explains the limits that protect the panel itself.
Set up the webhook#
Only staff with the owner or admin role can change these settings.
-
Open Network and DDoS in the Cloud group of the back office.
-
Copy the Webhook endpoint. It is your public URL followed by
/api/network/v1/ddos/events, for example:https://panel.example.com/api/network/v1/ddos/events -
Click Generate secret.
-
Copy the signing secret that appears. Stacklane shows it only once.
-
Store the secret on the detector host, for example in a file that only the detector can read.
-
Configure your detector to sign and send events as described below.
Until a secret exists, the endpoint answers every request with 404.
Request format#
Send one event per request:
- Method:
POST - Path:
/api/network/v1/ddos/events - Body: a JSON object, at most 16 KiB
- Headers:
Content-Type: application/json,X-Stacklane-TimestampandX-Stacklane-Signature
Body fields#
| Field | Type | Required | Meaning |
|---|---|---|---|
ip | string | Yes | The attacked IPv4 or IPv6 address. |
action | string | Yes | What happened. See Actions. |
attack_type | string | No | For example udp_flood. Default: unknown. |
direction | string | No | For example incoming. Default: incoming. |
pps | integer | No | Packets per second. Default: 0. Negative values become 0. |
bps | integer | No | Bits per second. Default: 0. Negative values become 0. |
mitigation | string | No | How the attack is handled, for example blackhole. Default: filtered. |
id | string | No | Your own ID for the attack. Stacklane stores it with a new attack. |
In attack_type, direction and mitigation, Stacklane keeps only letters, digits, _, - and spaces, and at most 40 characters. If nothing is left, it uses the default.
Example:
{"ip":"203.0.113.10","action":"ban","attack_type":"udp_flood","pps":1200000,"bps":9000000000}
Actions#
action | Effect |
|---|---|
ban, attack, start | Start an attack, or update the attack that is still open for this address. |
unban, end, stop | End all open attacks for this address. |
Any other value returns 400.
When an attack is still open for the address, a new start event updates it. Stacklane keeps the highest pps and the highest bps, and replaces the attack type and mitigation with the new values. When no attack is open, Stacklane creates a new one.
Stacklane links a new attack to the instance that has the address in an IPv4 pool, and to the organization that owns that instance. An attack on an address that belongs to no instance is still recorded, without a customer.
Signing#
Every request must carry two headers:
| Header | Value |
|---|---|
X-Stacklane-Timestamp | The current Unix time in seconds, for example 1795000000. |
X-Stacklane-Signature | sha256= followed by the HMAC-SHA256 of the message, as lowercase hexadecimal. |
The message is the timestamp, a dot and the exact request body:
<timestamp>.<body>
The HMAC key is the signing secret, used as a text string exactly as Stacklane showed it. Do not decode it.
Stacklane checks the request like this:
- The timestamp must be a whole number.
- The timestamp must be at most 300 seconds (five minutes) before or after the server time. Keep the clocks of the detector and the panel in sync, for example with NTP.
- Stacklane computes the HMAC-SHA256 of
<timestamp>.<body>with the secret and compares it with the signature. Thesha256=prefix is optional. The comparison takes constant time.
Sign the body bytes that you send. If your tool changes the body after signing, for example by adding a newline, the signature does not match.
Shell example#
ENDPOINT="https://panel.example.com/api/network/v1/ddos/events"
SECRET="$(cat /etc/stacklane-ddos.secret)"
BODY='{"ip":"203.0.113.10","action":"ban","attack_type":"udp_flood","pps":1200000,"bps":9000000000}'
TS="$(date +%s)"
SIG="$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')"
curl -sS -X POST "$ENDPOINT" \
-H "Content-Type: application/json" \
-H "X-Stacklane-Timestamp: $TS" \
-H "X-Stacklane-Signature: sha256=$SIG" \
--data-binary "$BODY"
Python example#
import hashlib
import hmac
import json
import time
import urllib.request
endpoint = "https://panel.example.com/api/network/v1/ddos/events"
secret = open("/etc/stacklane-ddos.secret").read().strip()
body = json.dumps(
{"ip": "203.0.113.10", "action": "ban", "attack_type": "udp_flood", "pps": 1200000},
separators=(",", ":"),
).encode()
timestamp = str(int(time.time()))
signature = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
request = urllib.request.Request(
endpoint,
data=body,
method="POST",
headers={
"Content-Type": "application/json",
"X-Stacklane-Timestamp": timestamp,
"X-Stacklane-Signature": "sha256=" + signature,
},
)
urllib.request.urlopen(request, timeout=10)
Responses#
| Status | Meaning |
|---|---|
202 Accepted | The event was stored. |
400 Bad Request | The body is not valid JSON, ip is not an IP address, or action is unknown. |
401 Unauthorized | The timestamp is missing, not a number or outside the five-minute window, or the signature is wrong. |
404 Not Found | No signing secret has been generated yet. |
413 Payload Too Large | The body is larger than 16 KiB. |
429 Too Many Requests | More than 300 webhook requests from one IP address in five minutes. |
503 Service Unavailable | Stacklane could not store the event. Send it again. |
The responses have no body.
FastNetMon#
FastNetMon can run a script when it bans or unbans an address. The script below sends the event to Stacklane with a correct signature.
FastNetMon passes the attacked IP address, the direction, the packet rate and the action as the first four arguments of the script. Check the FastNetMon documentation for your version, because these details can differ between versions.
-
Save the signing secret in
/etc/stacklane-ddos.secret. Make it readable only for the user that runs FastNetMon. -
Save this script as
/usr/local/bin/stacklane-notify.sh:#!/bin/sh ENDPOINT="https://panel.example.com/api/network/v1/ddos/events" SECRET="$(cat /etc/stacklane-ddos.secret)" IP="$1" DIRECTION="$2" PPS="$3" ACTION="$4" case "$ACTION" in ban|unban) ;; *) exit 0 ;; esac case "$PPS" in ''|*[!0-9]*) PPS=0 ;; esac case "$DIRECTION" in incoming|outgoing) ;; *) DIRECTION=incoming ;; esac BODY="$(printf '{"ip":"%s","action":"%s","direction":"%s","pps":%s}' "$IP" "$ACTION" "$DIRECTION" "$PPS")" TS="$(date +%s)" SIG="$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')" curl -sS --max-time 10 -X POST "$ENDPOINT" \ -H "Content-Type: application/json" \ -H "X-Stacklane-Timestamp: $TS" \ -H "X-Stacklane-Signature: sha256=$SIG" \ --data-binary "$BODY" > /dev/null -
Make it executable:
chmod 755 /usr/local/bin/stacklane-notify.sh -
In the FastNetMon configuration file, point the notify script to it:
notify_script_path = /usr/local/bin/stacklane-notify.sh -
Restart FastNetMon.
How the script matches Stacklane:
- It only forwards the actions
banandunban, which Stacklane understands. It ignores other calls. - It sends
ppsas a JSON number. A value that is not a whole number would make the JSON invalid, so the script sends 0 instead. - It signs exactly the body it sends.
--data-binarysends the body unchanged. openssl dgstprints lowercase hexadecimal.awk '{print $NF}'takes the last field of the output, which is the hash.
To test the script without an attack, run it by hand with an address of one of your instances:
/usr/local/bin/stacklane-notify.sh 203.0.113.10 incoming 1000 ban
/usr/local/bin/stacklane-notify.sh 203.0.113.10 incoming 0 unban
The attack appears under Recent attacks in the back office, and on the Networking tab of the instance.
Rotate the secret#
- Open Network and DDoS.
- Click Rotate secret.
- Copy the new secret. Stacklane shows it only once.
- Put the new secret on every detector host.
The old secret stops working at once. Events signed with the old secret are rejected with 401 until the detectors use the new secret. Plan the rotation so that you can update the detectors right away.
Each rotation writes the audit event admin.network.settings with "rotated": true.
Customer notifications#
Turn on Email customers when an attack on their server starts and click Save.
When this is on, Stacklane sends an email to every active administrator of the organization that owns the attacked instance. The email says that an attack is being filtered and links to the instance list.
Stacklane sends the email:
- when a new attack starts on the address of an instance;
- again when a later start event for the same open attack reports a packet rate equal to or higher than the highest rate so far.
It does not send an email for an address without an instance, or when the attack ends.
What customers see#
On the Networking tab of an instance, customers see:
- DDoS protection: "Protected" when a signing secret is configured;
- "Under attack, filtering active" while an attack is open;
- the last 20 attacks on the instance with the start time, attack type, peak traffic, mitigation and status.
Recent attacks#
The card Recent attacks on the Network and DDoS page lists the last 200 attacks on all addresses, with the start time, address, organization ID, attack type, peak traffic and status. Staff with the owner, admin or support role can read this list through GET /api/admin/network/attacks.
Protection of the panel#
Stacklane protects its own API with these limits. They are built in and cannot be changed in the settings.
Request limits#
All API requests from one IP address share a limit of 1,200 requests per minute. Above that, Stacklane answers 429 with the error code throttled.
Some actions have their own, lower limits:
| Action | Limit | Counted per |
|---|---|---|
| Sign in | 30 per 10 minutes | IP address |
| Sign in | 10 per 15 minutes | Email address and IP address |
| Failed sign-ins | 100 per 15 minutes, then sign-in is blocked | Email address |
| Two-factor codes | 20 per 10 minutes | IP address |
| Two-factor codes | 10 per 15 minutes | User |
| Sign up | 6 per hour | IP address |
| Ask for a password reset, set a new password, ask for a new confirmation link | 10 per 15 minutes | IP address |
| Ask for a password reset or a new confirmation link | 3 per hour | Email address |
| Change password, turn two-factor on or off, new recovery codes, sign out other sessions, show hosting password | 10 per 10 minutes | User |
| New support request | 20 per hour | Organization |
| Domain search | 60 per 10 minutes | Organization |
| Start a payment | 20 per 10 minutes | Organization |
| One-click sign-in to a hosting panel | 30 per 10 minutes | Organization |
| Payment and DDoS webhooks | 300 per 5 minutes | IP address |
The counters are kept in memory. A restart of Stacklane resets them.
When Stacklane runs behind a reverse proxy, set server.behind_proxy = true so that it reads the client IP address from X-Forwarded-For or X-Real-IP. Without it, all requests seem to come from the proxy and share one limit. See Configuration.
Size, time and load limits#
| Limit | Value | Response |
|---|---|---|
| Request body | 256 KiB (16 KiB for DDoS events, 64 KiB for payment webhooks) | 413 |
| Request time | 30 seconds | 408 |
| Requests in progress at the same time | 1,024 | 503 |
When 1,024 requests are already in progress, Stacklane does not queue new requests. It answers them with 503 Service Unavailable at once. This is called load shedding. It keeps the panel responsive under a flood of requests.
API endpoints#
| Method | Path | Staff roles | Description |
|---|---|---|---|
GET | /api/admin/network/settings | owner, admin | Returns configured, notify_customers and endpoint. |
PUT | /api/admin/network/settings | owner, admin | Body: {"notify_customers": true, "rotate_secret": false}. With rotate_secret: true, the response contains the new secret once. |
GET | /api/admin/network/attacks | owner, admin, support | The last 200 attacks. |
POST | /api/network/v1/ddos/events | Signed request | Receives detector events. |