# Warden: How it works

When you use our Anti-DDoS solutions, it's important to understand listings and how they are used.

The section explains the purpose and use of whitelisting, greylisting, and blacklisting in Anti-DDoS solutions. Whitelisting allows only trusted IPs, greylisting temporarily blocks potential threats for verification, and blacklisting denies access to known malicious IPs.

These methods help manage and prevent DDoS attacks by filtering traffic based on its origin.

## Traffic filtering techniques

{% tabs %}
{% tab title="Blacklisting" %}
Blocks traffic from harmful or suspicious IP addresses or domains. Once blacklisted, their traffic is automatically denied to prevent attacks from known threats.
{% endtab %}

{% tab title="Greylisting" %}
Greylisting is only used as a buffer during the authentication period. Warden allows you to connect, even though you are not whitelisted, requiring extra checks before allowing access. Warden will start limiting traffic in a greylist (and dropped) if you are in the middle of a DDoS attack, where traffic from unauthenticated IP addresses can be dropped as a safety measure.

{% hint style="warning" %}
**Per-IP enforcement:** The `tcp-gl-pps` and `udp-gl-pps` values you configure on an armor are applied **independently to each individual IP address** within the protected prefix — not shared across the prefix as a whole. For example, a /24 armor (256 IPs) with `udp-gl-pps: 50000` allows up to 50,000 PPS per IP from greylisted sources, not 50,000 PPS total. If your armor covers a subnet, review your greylist PPS values to ensure they reflect the per-IP exposure you intend.
{% endhint %}
{% endtab %}

{% tab title="Whitelisting" %}
Creates a list of approved IP addresses or domains allowed to access the network or service. Whitelisted traffic is not rate limited.
{% endtab %}
{% endtabs %}

## How Warden works

Our system verifies the protocol type, determining if it is TCP or UDP. TCP (Transmission Control Protocol) and UDP (User Datagram Protocol).

In Anti-DDoS strategies:

* **TCP** provides reliable, ordered, and error-checked delivery of streams of data between applications. It's essential for ensuring that traffic flows as intended without disruptions.
* **UDP** offers a simpler transmission model with no handshakes, suitable for time-sensitive communications like gaming or streaming, where speed is prioritized over reliability.

**Using Transmission Control Protocol**

1. First, Warden will check to see if the player IP address is blacklisted by you. If it is, then they are dropped and denied access to the network.
2. Based on your list of approved IP addresses, Warden will check to see if the player IP address is whitelisted. If it is, then the IP address is approved and the player is allowed access to the network, bypassing all port restrictions and PPS limits.
3. If the player IP address is not whitelisted (greylisted), then Warden verifies if the destination port is allowed. If it isn't, the packet is dropped.
4. If the destination port is valid, then the packet goes through rate-limiting. If the PPS is below the configured threshold, then the packet is allowed. Otherwise, it is dropped.

**Using User Datagram Protocol**

1. Warden will check to see if the player IP address is blacklisted. If it is, the player IP address is dropped and denied access to the network.
2. If the player's IP address is already whitelisted, the player bypasses all port restrictions and PPS limits. Warden then performs bytematching (if enabled in the Armor). There are 2 scenarios that can occur afterwards:
   1. If it passes bytematching, or in the absence of bytematching rules, the packet is allowed into the network.
   2. If the packet fails bytematching, then it is denied access into the network.
3. If the player's IP is not whitelisted (greylisted), Warden verifies if the destination port is allowed. If it isn't, the packet is dropped.
4. If the destination port is valid, then Warden performs bytematching (if enabled in the Armor).
   1. If the packet fails bytematching, then it is denied access into the network.
   2. If it passes bytematching, and if the packet per second is below the configured threshold, then the packet is allowed to enter the network.

<img src="/files/mLuS8vlii3UuMwTeSvmP" alt="" class="gitbook-drawing">

## Expiration precision

The `expires` value passed via `POST /lists/{id}` is applied down to the minute. Any seconds component is rounded down — `"2025-08-20T19:04:55Z"` is treated as `"2025-08-20T19:04:00Z"` in the Warden dataplane.

## Warden FAQs

#### What are the advantages of NOT using Warden's greylisting features at all, only allowing access from trusted IPs?

* **Full service continuity while attacks are ongoing:** New players can continue to connect to the game instance even while the server is under attack. When relying on greylisting, untrusted IPs will experience degraded service or may even have no service at all when the `tcp-gl-pps` or `udp-gl-pps` value is exceeded.
* **Reduced operational overhead:** You can skip thinking about how to interact with the blocklisting feature entirely, anything that is not trusted will be automatically dropped.
* **Reduced exposure to low-and-slow attacks:** You cannot receive packets from untrustworthy sources, significantly reducing the attack surface of your game and helping to defend against application layer attacks, such as those involving malformed packets. To avoid triggering greylisting, manage your PPS (Packets Per Second) and ensure it remains below the specified threshold.
* **Easier troubleshooting:** Debugging is much easier because a connection will either always work completely, or never work at all, there is no intermittency factor.

#### How should I size my greylist PPS values?

Because greylist PPS is enforced per individual IP (not per prefix), the right value depends on the legitimate volume of new or unauthenticated connections your server handles. A reasonable starting point is **10,000 PPS per IP**, but your ideal value is specific to your workload:

* **Baseline from your traffic data**: Review normal inbound PPS from non-whitelisted sources during non-attack periods. Set the greylist limit at or slightly above that baseline to absorb normal load while still capping attack amplification.
* **Ask i3D.net support for help**: We can plot your weekly traffic patterns to help you identify a safe threshold. Open a support ticket to request a traffic benchmarking review.
* **Consider disabling greylisting entirely** if your integration always whitelists authenticated users before they connect — see the FAQ below for when this is the right choice.

#### If that is the case, why would someone ever want to use Warden's greylisting feature?

* In some cases it's not possible to integrate with the authentication layer, then the game operator could instead choose to add IPs to the trusted list based on that IP's interactions with the server while in the greylist.
* Once your request reaches the GLAD API, updates propagate rapidly through Warden nodes worldwide. However, in some cases the user still tries to connect to the game instance before the IP address collected during authentication makes it onto Warden's trusted IPs list - a greylist would allow for the user to still complete their initial connection successfully.

#### Does a TCP armor also apply greylist controls to UDP traffic?

No. A TCP armor applies `ports` and `tcp-gl-pps` to TCP traffic only — `udp-gl-pps` has no effect in a TCP armor. UDP traffic from non-whitelisted sources passes through unrestricted unless a separate UDP armor exists for the same prefix. This is intentional: without it, a TCP-protected server could not receive DNS responses (which use UDP). To restrict UDP greylist traffic, create a UDP armor for the same prefix. Set `udp-gl-pps: 0` to drop all greylisted UDP (full block), or set a low value (e.g., 1000) to allow a limited amount through — useful when some UDP responses need to reach the server. The same applies in reverse: a UDP armor does not apply greylist controls to TCP traffic.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/anti-ddos/warden-capabilities-and-benefits/warden-how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.