Firewall product documentation

src/routes/blog/post/the-appwrite-network/+page.markdoc

@@ -21,7 +21,7 @@ faqs:
   - question: "Can I control where my project's data is stored?"
     answer: "Yes. When you create a project, you can choose the region where your data lives. The data stays in that region for compliance, while edges and the CDN make it accessible to users worldwide with low latency."
   - question: "Does Appwrite offer a Web Application Firewall?"
-    answer: "Yes. The [WAF](/docs/products/network/waf) is available to enterprise customers and inspects HTTP and HTTPS traffic at OSI Layer 7. It blocks common attacks like SQL injection, XSS, and CSRF, and includes customizable rulesets managed through a dedicated success manager."
+    answer: "Yes. The [WAF](/docs/products/network/firewall) is available to enterprise customers and inspects HTTP and HTTPS traffic at OSI Layer 7. It blocks common attacks like SQL injection, XSS, and CSRF, and includes customizable rulesets managed through a dedicated success manager."
 ---
 
 We are happy to announce the launch of the Appwrite Network, a network of cloud regions and edge locations (edges) to improve Appwrite Cloud availability, performance, and compliance with local regulations. This will provide Appwrite developers and teams with the best tools and infrastructure to build, deploy, and scale your applications. This brings us closer to the Appwrite mission of making software development more accessible and enjoyable for all developers.
@@ -100,7 +100,7 @@ Moreover, the CDN includes integrated DDoS protection that combines standard tra
 
 # Web application firewall (WAF)
 
-Our [Web Application Firewall](/docs/products/network/waf) (WAF) is now available exclusively to enterprise customers, providing a crucial protective layer for your applications. Operating at OSI Layer 7, the WAF inspects and filters all HTTP/HTTPS traffic in real time, effectively blocking common web vulnerabilities such as SQL injection, XSS, and CSRF, while also mitigating application-level DDoS attacks.
+Our [Web Application Firewall](/docs/products/network/firewall) (WAF) is now available exclusively to enterprise customers, providing a crucial protective layer for your applications. Operating at OSI Layer 7, the WAF inspects and filters all HTTP/HTTPS traffic in real time, effectively blocking common web vulnerabilities such as SQL injection, XSS, and CSRF, while also mitigating application-level DDoS attacks.
 
 Customizable rulesets allow you to tailor the WAF to your application's specific needs, with detailed analysis of request headers, payloads, and query strings to identify and neutralize threats before they reach your infrastructure. Setup and configuration are managed through your dedicated Appwrite success manager, ensuring that the WAF adapts to evolving security challenges and compliance requirements. To learn more about our enterprise plan, you can [contact us](/contact-us/enterprise).
 

src/routes/docs/products/network/+layout.svelte

@@ -35,6 +35,10 @@
                 {
                     label: 'Endpoints',
                     href: '/docs/products/network/endpoints'
+                },
+                {
+                    label: 'Firewall',
+                    href: '/docs/products/network/firewall'
                 }
             ]
         },
@@ -61,10 +65,6 @@
                     label: 'TLS',
                     href: '/docs/products/network/tls'
                 },
-                {
-                    label: 'WAF',
-                    href: '/docs/products/network/waf'
-                },
                 {
                     label: 'Compression',
                     href: '/docs/products/network/compression'

src/routes/docs/products/network/+page.markdoc

@@ -70,8 +70,8 @@ Protects against distributed denial-of-service attacks, ensuring uninterrupted a
 {% cards_item href="/docs/products/network/tls" title="Transport Layer Security (TLS)" %}
 Encrypts data in transit for secure and private communication.
 {% /cards_item %}
-{% cards_item href="/docs/products/network/waf" title="Web Application Firewall (WAF)" %}
-Shields applications from common web vulnerabilities and attacks on the application layer.
+{% cards_item href="/docs/products/network/firewall" title="Firewall" %}
+Controls the traffic that reaches your project with rules that block, challenge, rate limit, or redirect requests.
 {% /cards_item %}
 {% cards_item href="/docs/products/network/compression" title="Compression" %}
 Reduces data size in transit to improve transfer speed and efficiency.

src/routes/docs/products/network/firewall/+layout@docs.svelte

@@ -0,0 +1,64 @@
+<script lang="ts">
+    import Docs from '$lib/layouts/Docs.svelte';
+    import Sidebar, { type NavParent, type NavTree } from '$lib/layouts/Sidebar.svelte';
+
+    const parent: NavParent = {
+        href: '/docs/products/network',
+        label: 'Firewall'
+    };
+
+    const navigation: NavTree = [
+        {
+            label: 'Getting started',
+            items: [
+                {
+                    label: 'Overview',
+                    href: '/docs/products/network/firewall'
+                },
+                {
+                    label: 'Quick start',
+                    href: '/docs/products/network/firewall/quick-start'
+                }
+            ]
+        },
+        {
+            label: 'Concepts',
+            items: [
+                {
+                    label: 'Rules',
+                    href: '/docs/products/network/firewall/rules'
+                },
+                {
+                    label: 'Conditions',
+                    href: '/docs/products/network/firewall/conditions'
+                },
+                {
+                    label: 'Actions',
+                    href: '/docs/products/network/firewall/actions'
+                },
+                {
+                    label: 'Logs',
+                    href: '/docs/products/network/firewall/logs'
+                },
+                {
+                    label: 'Analytics',
+                    href: '/docs/products/network/firewall/analytics'
+                }
+            ]
+        },
+        {
+            label: 'Guides',
+            items: [
+                {
+                    label: 'Common rules',
+                    href: '/docs/products/network/firewall/common-rules'
+                }
+            ]
+        }
+    ];
+</script>
+
+<Docs variant="two-side-navs">
+    <Sidebar {navigation} {parent} />
+    <slot />
+</Docs>

src/routes/docs/products/network/firewall/+page.markdoc

@@ -0,0 +1,44 @@
+---
+layout: article
+title: Firewall
+description: Control the traffic that reaches your Appwrite project with firewall rules that block, challenge, rate limit, or redirect requests at the edge.
+---
+
+Appwrite Firewall lets you control which requests reach your project. You define rules that match requests by attributes like IP address, country, path, or user agent, and choose what happens when they match: block the request, rate limit it, challenge it, redirect it, or explicitly allow it through.
+
+Rules are enforced on Appwrite's edge network, before a request reaches your [function](/docs/products/functions) or [site](/docs/products/sites). A blocked request never executes your code, never triggers a cold start, and never consumes your project's compute resources.
+
+# How it works {% #how-it-works %}
+
+Every request to your project's functions and sites passes through an Appwrite edge location. When your project has firewall rules, the edge evaluates them before running your deployment:
+
+1. Rules are evaluated in priority order, from the lowest priority number to the highest.
+2. A rule matches when all of its conditions match the incoming request.
+3. The first matching rule wins. Its action is applied and evaluation stops.
+4. If no rule matches, the request continues to your function or site as usual.
+
+Firewall is designed to fail open. If a rule is misconfigured or cannot be evaluated, the rule is skipped and traffic continues to flow, so a broken rule degrades protection rather than availability.
+
+# Key concepts {% #key-concepts %}
+
+| Concept | Description |
+| ------- | ----------- |
+| [Rules](/docs/products/network/firewall/rules) | The unit of configuration. A rule combines conditions, an action, a priority, and a scope. |
+| [Conditions](/docs/products/network/firewall/conditions) | What a rule matches on: IP address, country, path, HTTP method, host, or user agent. |
+| [Actions](/docs/products/network/firewall/actions) | What happens on a match: deny, rate limit, challenge, redirect, or bypass. |
+| [Logs](/docs/products/network/firewall/logs) | A record of the requests your rules acted on. |
+| [Analytics](/docs/products/network/firewall/analytics) | Aggregated metrics on blocked, challenged, and redirected traffic. |
+
+# Common use cases {% #common-use-cases %}
+
+- Block traffic from specific IP addresses or countries.
+- Rate limit expensive or sensitive endpoints, like authentication routes.
+- Restrict an admin path to a known set of IP addresses.
+- Challenge suspicious traffic, like requests with automation user agents.
+- Redirect blocked visitors to an explanation page.
+
+See [Common rules](/docs/products/network/firewall/common-rules) for ready-to-use examples of each.
+
+# Getting started {% #getting-started %}
+
+Follow the [quick start](/docs/products/network/firewall/quick-start) to create your first rule from the Appwrite Console.

src/routes/docs/products/network/firewall/actions/+page.markdoc

@@ -0,0 +1,62 @@
+---
+layout: article
+title: Actions
+description: Choose whether a firewall rule denies, rate limits, challenges, redirects, or bypasses the requests it matches.
+---
+
+A rule's action determines what happens to a request that matches all of the rule's conditions. Appwrite Firewall supports five actions.
+
+| Action | Behavior | Response |
+| ------ | -------- | -------- |
+| `deny` | Blocks the request. | `403` |
+| `rateLimit` | Blocks the request once a request limit is exceeded. | `429` when over the limit |
+| `challenge` | Requires the client to pass a verification challenge. | `403` until the challenge is passed |
+| `redirect` | Redirects the request to a different URL. | `3xx` |
+| `bypass` | Allows the request and stops rule evaluation. | Request continues normally |
+
+# Deny {% #deny %}
+
+Deny blocks the request outright with a `403` status code. The request never reaches your function or site. Use deny for traffic you never want to serve, like known-abusive IP addresses or countries you cannot serve.
+
+# Rate limit {% #rate-limit %}
+
+Rate limit allows matching requests up to a configured limit within a time window, tracked per client IP address. Once a client exceeds the limit, further matching requests from that client are blocked with a `429` status code until the window resets.
+
+| Configuration | Description | Default |
+| ------------- | ----------- | ------- |
+| Limit | The number of requests allowed per window. | `100` |
+| Interval | The window length in seconds. | `3600` |
+
+Blocked responses include a `Retry-After` header indicating how many seconds the client should wait before retrying. Use rate limiting to protect expensive endpoints and to slow down brute-force attempts against authentication routes.
+
+# Challenge {% #challenge %}
+
+Challenge requires the client to prove it is a legitimate browser before the request is allowed through. Requests that have not passed the challenge receive a `403` status code. Use challenge for traffic that looks suspicious but might be human, where an outright block would be too aggressive.
+
+# Redirect {% #redirect %}
+
+Redirect sends the client to a different URL instead of serving the request.
+
+| Configuration | Description | Default |
+| ------------- | ----------- | ------- |
+| Location | The URL to redirect to. | Required |
+| Status code | The redirect status code, in the `3xx` range. | `302` |
+
+Use redirect to send blocked visitors to an explanation page or to route traffic from specific regions to a different destination.
+
+# Bypass {% #bypass %}
+
+Bypass explicitly allows the request and stops evaluation, so no later rule can block it. Bypass is the building block for allowlists: place a bypass rule for trusted traffic at a lower priority number than a broader deny rule, and the trusted traffic is exempted from the block. See [Rules](/docs/products/network/firewall/rules#priority) for how priority ordering makes this work.
+
+# Response headers {% #response-headers %}
+
+When a firewall rule acts on a request, the response identifies the rule and action:
+
+| Header | Description |
+| ------ | ----------- |
+| `X-Appwrite-WAF-Rule` | The ID of the matched rule. |
+| `X-Appwrite-WAF-Action` | The action that was applied. |
+| `X-Appwrite-WAF-Challenge-Type` | The type of challenge issued. Only present on challenge responses. |
+| `Retry-After` | Seconds until the rate limit window resets. Only present on rate-limited responses. |
+
+These headers are useful when testing new rules or debugging why a request was blocked.

src/routes/docs/products/network/firewall/analytics/+page.markdoc

@@ -0,0 +1,38 @@
+---
+layout: article
+title: Analytics
+description: Monitor how much traffic your firewall rules block, challenge, and redirect, and see where blocked traffic comes from.
+---
+
+Firewall analytics aggregate what your rules are doing over time, so you can see how much traffic is filtered and where it comes from.
+
+Open the **Analytics** tab on the **Firewall** page in your project in the Appwrite Console to view them.
+
+# Metrics {% #metrics %}
+
+Analytics track the requests your rules acted on, grouped by outcome:
+
+| Metric | Description |
+| ------ | ----------- |
+| Blocked | Requests stopped by `deny` rules or rate limits. |
+| Challenged | Requests issued a verification challenge. |
+| Redirected | Requests sent to a different URL by `redirect` rules. |
+
+Metrics are shown as totals with trends over your selected date range, along with a time series so you can spot spikes.
+
+# Traffic sources {% #traffic-sources %}
+
+Analytics also break blocked traffic down by origin:
+
+- **Top blocked IP addresses** show which clients trigger your rules most, which helps identify persistent abusers worth a dedicated deny rule.
+- **Top blocked countries** show the geographic distribution of filtered traffic, which helps evaluate whether geo-blocking rules are working as intended.
+
+# Using analytics {% #using-analytics %}
+
+A few patterns worth watching:
+
+- A sudden spike in blocked requests usually means an attack or scraper found your application, and your rules are absorbing it.
+- A high challenge count with few subsequent successful requests suggests the challenged traffic was automated.
+- If a rule shows no activity over a long period, verify it still matches what you intended, or consider removing it to keep your rule set easy to reason about.
+
+For request-level detail behind any of these numbers, switch to the [logs](/docs/products/network/firewall/logs).

src/routes/docs/products/network/firewall/common-rules/+page.markdoc

@@ -0,0 +1,105 @@
+---
+layout: article
+title: Common rules
+description: Ready-to-use firewall rule patterns for geo-blocking, IP allowlists, rate limiting, and bot challenges.
+---
+
+These patterns cover the most common ways to use Appwrite Firewall. Each example shows the rule's action, priority, and conditions. Create them from the **Firewall** page in your project in the Appwrite Console, adjusting values to your needs.
+
+# Block traffic from specific countries {% #geo-blocking %}
+
+A single `deny` rule with a multi-value `equal` condition on `country` blocks every listed country:
+
+- **Action**: `deny`
+- **Priority**: `10`
+- **Conditions**:
+
+```json
+[
+    { "method": "equal", "attribute": "country", "values": ["KP", "IR"] }
+]
+```
+
+To do the opposite and serve only specific countries, use `notEqual` conditions, or pair a `bypass` rule for the allowed countries with a broader `deny` rule.
+
+# Restrict a path to known IP addresses {% #ip-allowlist %}
+
+Allowlists use two rules. A `bypass` rule at a lower priority number exempts trusted traffic, and a `deny` rule behind it blocks everyone else. See [priority and evaluation order](/docs/products/network/firewall/rules#priority) for why the ordering matters.
+
+Rule 1 allows your trusted IP addresses through:
+
+- **Action**: `bypass`
+- **Priority**: `5`
+- **Conditions**:
+
+```json
+[
+    { "method": "startsWith", "attribute": "path", "values": ["/admin"] },
+    { "method": "equal", "attribute": "ip", "values": ["203.0.113.7", "203.0.113.8"] }
+]
+```
+
+Rule 2 blocks all other traffic to the same path:
+
+- **Action**: `deny`
+- **Priority**: `10`
+- **Conditions**:
+
+```json
+[
+    { "method": "startsWith", "attribute": "path", "values": ["/admin"] }
+]
+```
+
+# Rate limit an authentication endpoint {% #rate-limit-auth %}
+
+Slow down brute-force attempts by limiting how often a single IP address can call a login route:
+
+- **Action**: `rateLimit`
+- **Priority**: `20`
+- **Configuration**: limit `10`, interval `60` seconds
+- **Conditions**:
+
+```json
+[
+    { "method": "equal", "attribute": "method", "values": ["POST"] },
+    { "method": "equal", "attribute": "path", "values": ["/v1/login"] }
+]
+```
+
+Legitimate users are unaffected until they exceed 10 requests per minute, and clients over the limit receive a `429` response with a `Retry-After` header.
+
+# Challenge automated clients {% #challenge-bots %}
+
+Require verification from clients that identify as automation tools or send no user agent at all:
+
+- **Action**: `challenge`
+- **Priority**: `30`
+- **Conditions**:
+
+```json
+[
+    {
+        "method": "or",
+        "values": [
+            { "method": "contains", "attribute": "userAgent", "values": ["curl", "python-requests", "Go-http-client"] },
+            { "method": "isNull", "attribute": "userAgent" }
+        ]
+    }
+]
+```
+
+# Redirect blocked visitors to an explanation page {% #redirect-blocked %}
+
+Instead of serving a bare `403`, send blocked traffic somewhere informative:
+
+- **Action**: `redirect`
+- **Priority**: `10`
+- **Configuration**: location `https://example.com/not-available`, status code `302`
+- **Conditions**:
+
+```json
+[
+    { "method": "equal", "attribute": "country", "values": ["KP"] }
+]
+```