UMBREN documentation

Overview

UMBREN is DDoS mitigation as a service for infrastructure that other businesses own and run: VPN providers, game server operators, hosting companies and other infrastructure owners.

You register a server address, a protocol and the ports your service listens on. Once you have proven that the infrastructure is yours, UMBREN provisions a protected endpoint on an upstream scrubbing network. Attack traffic is filtered there, and legitimate traffic is forwarded to your origin. You keep control of your service and your customers.

UMBREN is not a VPN service and does not host your service. It defends the address your service is reached on.

This documentation describes how the product behaves. It contains no capacity, coverage, latency or uptime figures. UMBREN does not publish those until they describe verified infrastructure.

Core concepts

• Organization. The account boundary. Members, endpoints, policies, credentials and billing belong to one organization. The data of each organization is isolated from every other.
• Endpoint. A service you register for protection: one origin address, one protocol, and a port or port range.
• Origin. Your server. The address where your service runs and where clean traffic is delivered.
• Protected endpoint. The address reserved for you on an upstream scrubbing network. Your users connect to it in place of the origin.
• Scrubbing provider. An upstream network that filters traffic. UMBREN connects to providers through adapters that share one contract.
• Control plane. The dashboard, the API and the systems behind them. It carries configuration and telemetry. It carries no customer traffic, and protection that is already deployed does not depend on it being available.
• Policy. A versioned description of how traffic to an endpoint is mitigated. It configures six components.
• Incident. A recorded attack: its vector, severity, peak, duration and the mitigation that was applied.

Endpoint registration

An endpoint is registered with the following fields.

The origin address, protocol and ports can only be edited while the endpoint is in DRAFT. A verified combination of origin, protocol and port range can belong to only one endpoint.

Telemetry

Telemetry is what the protection network measured for an endpoint: bandwidth, packets per second, protocol distribution, and allowed versus mitigated traffic. Historical ranges are 1 hour, 24 hours, 7 days and 30 days.

If no telemetry has been reported for an endpoint, the dashboard shows “Awaiting telemetry”. It never shows placeholder traffic.

Plans and allowances

Port allowances, the number of endpoints and some features depend on the plan of the organization. Prices are on the pricing page.

• Single IP. One protected endpoint, defined port allowances and standard monitoring.
• Multi-IP. Multiple endpoints, additional policies and extended analytics.
• Network. Advanced network configuration and higher allowances. Protection for routed infrastructure is planned as part of this plan and is not available yet.
• Enterprise. Contract-based, with custom integration and support.

Onboarding lifecycle

Every endpoint moves through the same states, in order. Nothing is sent to your origin before the testing state, and no user traffic moves before activation.

States outside the main path

Retry after a failure

When an automated step fails the endpoint moves to FAILED. Retry returns it to the last stable checkpoint before the step that failed.

Ownership verification

UMBREN protects infrastructure only for whoever controls it. Entering an IP address is never accepted as proof. There are two ways to verify ownership today, and a third is planned.

Verification agent

1. Start agent verification for the endpoint. The dashboard issues a one-time challenge. It is valid for 24 hours and is shown once. UMBREN stores it only as a hash.
2. Run the agent on the origin server, passing the challenge.
3. The agent makes one outbound HTTPS request that carries the challenge. UMBREN compares the address the request arrives from with the registered origin address. If they match, ownership is verified.

umbren-agent verify --token <challenge>

If the server has more than one address, use --bind to choose the source address of the request.

umbren-agent verify --token <challenge> --bind <origin address>

What the agent does and does not do:

• It makes one outbound HTTPS request. It sends the challenge and nothing else.
• It opens no port, installs nothing, and exits when the request is complete.
• UMBREN never connects to, scans or probes the origin. Verification relies only on the request your server sends.
• Each challenge allows up to 20 attempts.

Manual verification

If the agent cannot be used, submit a manual verification request: a written statement and a reference that supports it, for example an allocation letter or a provider invoice. UMBREN staff review the request.

Hosting-provider integration

Verification through a hosting provider is planned. It is not available yet.

Origin requirements

• A single public address. The origin is one public IPv4 or IPv6 address. Private and reserved ranges are rejected.
• One protocol and a defined port range. UDP or TCP, on a port or port range within the allowance of your plan.
• Outbound HTTPS, for agent verification. The server must be able to make one outbound HTTPS request. No inbound port is needed for verification.
• The request must leave from the registered address. If the server reaches the Internet from a different address than the one registered, for example behind address translation, the addresses will not match. Use --bind where the server holds the address, or use manual verification.
• Firewall and routing ready for clean traffic. The origin must accept clean traffic from the delivery ranges shown on the endpoint page. You confirm this before testing, and it is an activation gate.

Activation gates

Activation is the moment traffic starts to move through the protected endpoint. Every gate below must hold. There is no override.

• Gates are checked again at the moment of activation. A gate that held earlier and no longer holds stops activation.
• Billing status alone never triggers provisioning. A paid subscription does not activate anything by itself.
• Activation is authorized by a person in the dashboard. An API credential cannot authorize it.

Mitigation policies

A mitigation policy decides what happens to traffic for an endpoint. A policy has a scope, a mode and a version history.

• Scope. One endpoint, or the whole organization.
• Mode. In monitor mode the policy is evaluated and its decisions are recorded. It is never deployed. In enforce mode the policy is eligible for deployment.
• Automatic mitigation. Opt-in for each policy. It requires enforce mode.
• Versions. Every change creates a new immutable version.
• Rollback. Rolling back restores an earlier version as a new version. Earlier versions are never altered.
• Validation. Unknown configuration fields are rejected.

Components and settings

A policy configures six components. The table lists every setting, with its default where it has one.

• pps_threshold and bps_threshold are absolute ceilings. baseline_multiplier is relative to the learned baseline. An anomaly must persist for sustain_seconds.
• max_escalation_level caps the automatic response. It does not cap the severity that is reported for an incident.
• Automatically applied rules expire after rule_ttl_minutes. An incident resolves once traffic has stayed normal for quiet_period_minutes.
• Game-specific Protocol Guard profiles are planned. They are not available yet.

Notifications and webhooks

Notifications are sent to channels. A channel is an email address, a Discord webhook or a custom webhook. The event types are listed below.

Custom webhooks

A custom webhook is an HTTPS POST with a JSON body. Three headers describe the delivery: the event type, a delivery identifier and a signature.

POST /your/webhook/path HTTP/1.1
Content-Type: application/json
X-Umbren-Event: incident.detected
X-Umbren-Delivery: <delivery identifier>
X-Umbren-Signature: t=<unix seconds>,v1=<hex>

{
  "id": "...",
  "type": "incident.detected",
  "created_at": "...",
  "organization_id": "...",
  "data": {...}
}

• Origin addresses are never included in payloads.
• Redirects are not followed. Register the final URL of your receiver.
• Deliveries are retried up to 6 attempts, with exponential backoff that starts at 30 seconds and is capped at 1 hour.
• A retried delivery can arrive more than once. Use the event id to make your handler idempotent.

Verifying signatures

Every custom webhook is signed. The signing secret starts with whsec_ and is shown once, when the channel is created. Store it as you would any credential.

The signature header has the form t=<unix seconds>,v1=<hex>. The value of v1 is the HMAC-SHA256 of the string <t>.<raw request body>, keyed with the signing secret and encoded as hexadecimal. To verify a delivery:

1. Read t and v1 from the X-Umbren-Signature header.
2. Reject the request if the timestamp is more than a few minutes old. The examples below allow five minutes.
3. Compute the HMAC over the timestamp, a full stop and the raw request body. Use the bytes you received, not a parsed and re-serialized copy.
4. Compare the result with the received value using a constant-time comparison.

Node.js

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

// rawBody must be the request body exactly as it was received,
// before any JSON parsing or re-serialization.
export function verifyUmbrenSignature(rawBody, signatureHeader, signingSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.trim().split("=", 2)),
  );

  const timestamp = Number(parts.t);
  const fresh =
    Number.isFinite(timestamp) &&
    Math.abs(Date.now() / 1000 - timestamp) <= TOLERANCE_SECONDS;

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(String(parts.t) + ".")
    .update(rawBody)
    .digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");

  return (
    fresh &&
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_umbren_signature(raw_body: bytes, signature_header: str, signing_secret: str) -> bool:
    """raw_body must be the request body exactly as it was received."""
    parts = dict(
        item.strip().split("=", 1) for item in signature_header.split(",") if "=" in item
    )
    timestamp = parts.get("t", "")
    received = parts.get("v1", "")

    if not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(signing_secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

API

The API is REST over HTTPS with JSON request and response bodies. The base URL is https://api.umbren.net/v1. This is the planned production address.

Authentication

Send an API credential as a bearer token with every request.

Authorization: Bearer <API credential>

• Credentials have the form umb_<prefix>_<secret> and are created under Settings, then API credentials.
• A credential is scoped to one organization.
• A credential carries a role: viewer, which is read-only, or engineer.
• The credential is shown once, when it is created.
• API credentials are a plan feature.
• An API credential cannot authorize activation.

Errors

Errors share one shape. Include the request_id when you contact UMBREN about a failed request.

{
  "error": {
    "code": "validation_failed",
    "message": "...",
    "fields": { "origin_ip": "..." },
    "request_id": "..."
  }
}

Routes

The routes below are examples. The complete description of the API is published with it, as an OpenAPI document at /v1/openapi.json.

Examples

In these examples {org} is the identifier of your organization and {id} is the identifier of an endpoint. The credential is read from an environment variable.

List endpoints:

curl https://api.umbren.net/v1/orgs/{org}/endpoints \
  -H "Authorization: Bearer $UMBREN_API_CREDENTIAL"

Register an endpoint. The request body uses these fields:

curl -X POST https://api.umbren.net/v1/orgs/{org}/endpoints \
  -H "Authorization: Bearer $UMBREN_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-tunnel-01",
    "category": "vpn",
    "origin_ip": "203.0.113.10",
    "protocol": "udp",
    "port_start": 51820,
    "port_end": 51820,
    "preferred_region": "auto",
    "connection_requirements": "WireGuard-compatible tunnel endpoint.",
    "protection_profile": "wireguard"
  }'

203.0.113.10 is a documentation address used here as a placeholder. Reserved ranges are rejected, so use your own public address.

Start agent verification for an endpoint:

curl -X POST https://api.umbren.net/v1/orgs/{org}/endpoints/{id}/verification \
  -H "Authorization: Bearer $UMBREN_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{"method":"agent"}'

Read the last 24 hours of telemetry:

curl "https://api.umbren.net/v1/orgs/{org}/telemetry?range=24h" \
  -H "Authorization: Bearer $UMBREN_API_CREDENTIAL"

Roles and permissions

Each member of an organization holds one role.

The data of each organization is isolated. A request for a resource that belongs to another organization returns 404, the same response as for a resource that does not exist.

Account security

• Email verification. An email address must be verified.
• Passwords. At least 12 characters.
• Two-factor authentication. Time-based one-time passwords (TOTP), with one-time recovery codes.
• Sessions. You can list your active sessions and revoke them.
• Audit log. Sensitive actions are recorded in an append-only audit log. Actions taken by UMBREN staff are recorded in it too.

Demo mode and simulated providers

UMBREN keeps real data and example data apart. Three things can look alike and are not the same.

• Awaiting telemetry. A real endpoint for which no telemetry has been reported yet. The dashboard says so and shows no placeholder traffic.
• Demo mode. A separate, clearly labelled mode that shows simulated data, so that you can see how the dashboard works. Nothing shown in demo mode describes your infrastructure.
• Simulated providers. In evaluation environments an endpoint may be staged on a simulated provider. Such an endpoint is labelled “simulated” everywhere it appears. It never counts as protected.

Getting help

For questions about onboarding, manual verification, capacity for your endpoints or an Enterprise agreement, contact us. If your question is about a failed API request, include the request_id from the error.