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.

  1. Open Network and DDoS in the Cloud group of the back office.

  2. 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
    
  3. Click Generate secret.

  4. Copy the signing secret that appears. Stacklane shows it only once.

  5. Store the secret on the detector host, for example in a file that only the detector can read.

  6. 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:

Body fields#

FieldTypeRequiredMeaning
ipstringYesThe attacked IPv4 or IPv6 address.
actionstringYesWhat happened. See Actions.
attack_typestringNoFor example udp_flood. Default: unknown.
directionstringNoFor example incoming. Default: incoming.
ppsintegerNoPackets per second. Default: 0. Negative values become 0.
bpsintegerNoBits per second. Default: 0. Negative values become 0.
mitigationstringNoHow the attack is handled, for example blackhole. Default: filtered.
idstringNoYour 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#

actionEffect
ban, attack, startStart an attack, or update the attack that is still open for this address.
unban, end, stopEnd 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:

HeaderValue
X-Stacklane-TimestampThe current Unix time in seconds, for example 1795000000.
X-Stacklane-Signaturesha256= 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:

  1. The timestamp must be a whole number.
  2. 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.
  3. Stacklane computes the HMAC-SHA256 of <timestamp>.<body> with the secret and compares it with the signature. The sha256= 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#

StatusMeaning
202 AcceptedThe event was stored.
400 Bad RequestThe body is not valid JSON, ip is not an IP address, or action is unknown.
401 UnauthorizedThe timestamp is missing, not a number or outside the five-minute window, or the signature is wrong.
404 Not FoundNo signing secret has been generated yet.
413 Payload Too LargeThe body is larger than 16 KiB.
429 Too Many RequestsMore than 300 webhook requests from one IP address in five minutes.
503 Service UnavailableStacklane 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.

  1. Save the signing secret in /etc/stacklane-ddos.secret. Make it readable only for the user that runs FastNetMon.

  2. 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
    
  3. Make it executable:

    chmod 755 /usr/local/bin/stacklane-notify.sh
    
  4. In the FastNetMon configuration file, point the notify script to it:

    notify_script_path = /usr/local/bin/stacklane-notify.sh
    
  5. Restart FastNetMon.

How the script matches Stacklane:

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#

  1. Open Network and DDoS.
  2. Click Rotate secret.
  3. Copy the new secret. Stacklane shows it only once.
  4. 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:

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:

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:

ActionLimitCounted per
Sign in30 per 10 minutesIP address
Sign in10 per 15 minutesEmail address and IP address
Failed sign-ins100 per 15 minutes, then sign-in is blockedEmail address
Two-factor codes20 per 10 minutesIP address
Two-factor codes10 per 15 minutesUser
Sign up6 per hourIP address
Ask for a password reset, set a new password, ask for a new confirmation link10 per 15 minutesIP address
Ask for a password reset or a new confirmation link3 per hourEmail address
Change password, turn two-factor on or off, new recovery codes, sign out other sessions, show hosting password10 per 10 minutesUser
New support request20 per hourOrganization
Domain search60 per 10 minutesOrganization
Start a payment20 per 10 minutesOrganization
One-click sign-in to a hosting panel30 per 10 minutesOrganization
Payment and DDoS webhooks300 per 5 minutesIP 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#

LimitValueResponse
Request body256 KiB (16 KiB for DDoS events, 64 KiB for payment webhooks)413
Request time30 seconds408
Requests in progress at the same time1,024503

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#

MethodPathStaff rolesDescription
GET/api/admin/network/settingsowner, adminReturns configured, notify_customers and endpoint.
PUT/api/admin/network/settingsowner, adminBody: {"notify_customers": true, "rotate_secret": false}. With rotate_secret: true, the response contains the new secret once.
GET/api/admin/network/attacksowner, admin, supportThe last 200 attacks.
POST/api/network/v1/ddos/eventsSigned requestReceives detector events.