Web Application Firewall Guideline

Verbex uses a Web Application Firewall (WAF) to protect platform APIs and services from common web threats and malicious traffic.

Organization-Specific Protection

WAF rules are applied per organization to ensure isolated and customizable protection.
Each organization can define its own WAF policy based on its security requirements.

Policy Modes

Organizations can configure their WAF policy in one of the following modes:

Default Deny with Allow Rules
- All traffic is denied by default.
- Only explicitly allowed requests are permitted.
Default Allow with Deny Rules
- All traffic is allowed by default.
- Only explicitly denied requests are blocked.

Quick Start

1. Configure WAF for Your Organization

# Create WAF configuration (ALLOW mode - blocklist)curl -X POST /v1/waf/config \
  -H "X-User-Org-Id: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "default_policy": "ALLOW",
    "status": "ACTIVE"
  }'

2. Add IP Rules

# Block a malicious IPcurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "198.51.100.50",
    "action": "BLOCK",
    "reason": "Suspicious activity detected"
  }'

3. Check IP Access

# Check if an IP should be blockedcurl -X POST /v1/waf/check \
  -H "X-User-Org-Id: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{"ip_address": "198.51.100.50"}'

Response:

{  "ip_address": "198.51.100.50",  "is_blocked": true,  "action": "BLOCK",  "matched_rule": "rule-id-here"}

Core Concepts

Default Policy

Policy	Mode	Behavior
`ALLOW`	Blocklist	Allow all IPs by default, block specific threats
`DENY`	Allowlist	Block all IPs by default, allow specific trusted IPs

IP Types

Type	Format	Example	Description
`EXACT`	Single IP	`192.168.1.100`	Match one specific IP
`CIDR`	IP Range	`192.168.1.0/24`	Match IP range (256 IPs)

CIDR Notation


IP_ADDRESS / PREFIX_LENGTH

CIDR	Subnet Mask	IP Range	Total IPs
`/32`	255.255.255.255	Single IP	1
`/24`	255.255.255.0	x.x.x.0 - x.x.x.255	256
`/16`	255.255.0.0	x.x.0.0 - x.x.255.255	65,536
`/8`	255.0.0.0	x.0.0.0 - x.255.255.255	16,777,216

Rule Priority (Specificity)

When multiple rules match, the most specific wins:


/32 (exact) > /24 > /16 > /8 (broadest)

Example:

Rule 1: BLOCK 10.0.0.0/8
Rule 2: ALLOW 10.1.2.3/32

Result: IP 10.1.2.3 is ALLOWED (/32 beats /8)

WAF Status

Status	Behavior
`ACTIVE`	WAF rules are enforced
`INACTIVE`	All IPs allowed (bypass mode for troubleshooting)

API Reference

Endpoints

Endpoint	Method	Description
`/v1/waf/check`	POST	Check if IP should be blocked
`/v1/waf/config`	GET	Get WAF configuration
`/v1/waf/config`	POST	Create WAF configuration
`/v1/waf/config`	PUT	Update WAF configuration
`/v1/waf/rules`	POST	Create a rule
`/v1/waf/rules/paginated`	GET	List rules with pagination
`/v1/waf/rules/{ruleId}`	GET	Get rule by ID
`/v1/waf/rules/{ruleId}`	PUT	Update rule
`/v1/waf/rules/{ruleId}`	DELETE	Delete rule
`/v1/waf/rules/activate-all`	POST	Activate all rules
`/v1/waf/rules/deactivate-all`	POST	Deactivate all rules
`/v1/waf/cache/{orgId}`	DELETE	Clear cache
`/v1/waf/cache/{orgId}/sync`	POST	Sync cache from database

Request Headers

Header	Required	Description
`X-User-Org-Id`	Yes	Organization identifier
`X-User-ID`	No	User ID for audit trail
`X-Client-IP`	No	Client IP for auto-rule creation
`X-Trace-Id`	No	Request correlation ID

Data Models

WAF Configuration:

{
  "org_id": "string",
  "default_policy": "ALLOW | DENY",
  "status": "ACTIVE | INACTIVE",
  "created_at": "2026-02-17T10:00:00Z",
  "updated_at": "2026-02-17T10:00:00Z"
}

IP Access Rule:

{
  "id": "string",
  "org_id": "string",
  "ip_address": "192.168.1.100",
  "ip_type": "EXACT | CIDR",
  "action": "ALLOW | BLOCK",
  "reason": "string",
  "is_active": true,
  "expires_at": "2026-03-17T00:00:00Z",
  "notes": "string",
  "created_at": "2026-02-17T10:00:00Z",
  "updated_at": "2026-02-17T10:00:00Z"
}

IP Check Response:

{
  "ip_address": "192.168.1.100",
  "is_blocked": false,
  "action": "ALLOW",
  "matched_rule": "rule-id or null",
  "default_policy": "ALLOW (if no rule matched)"
}

Configuration

Application Properties

waf:
  enabled: true                    # Enable/disable WAF
  default-policy: ALLOW            # System-wide default
  cache-ttl: PT1H                  # Redis cache TTL
  max-rules-per-org: 1000          # Max rules per org
  debug-logging: false             # Verbose logging

  negative-cache:
    enabled: true                  # Cache "no rule" results
    ttl: PT5M                      # Negative cache TTL

  cache-warmup:
    enabled: true                  # Preload on startup
    delay: PT5S                    # Warmup delay
    batch-size: 100                # Orgs per batch

Limits

Resource	Limit
Rules per organization	1,000
Batch operations	100 rules
Pagination max size	100 items

Usage Examples

Example 1: Blocklist Mode (Default: ALLOW)

Block specific threats while allowing all other traffic.

# 1. Configure ALLOW modecurl -X POST /v1/waf/config \
  -H "X-User-Org-Id: acme-corp" \
  -d '{"default_policy": "ALLOW", "status": "ACTIVE"}'# 2. Block attacker IPcurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: acme-corp" \
  -d '{"ip_address": "198.51.100.50", "action": "BLOCK", "reason": "Brute force"}'

Result:

IP	Rule Match	Access
`203.0.113.10`	No rule → Default ALLOW	Allowed
`198.51.100.50`	BLOCK rule	Blocked

Example 2: Allowlist Mode (Default: DENY)

Only allow specific trusted IPs.

# 1. Configure DENY mode (auto-creates rule for your IP)curl -X POST /v1/waf/config \
  -H "X-User-Org-Id: acme-corp" \
  -H "X-Client-IP: 203.0.113.10" \
  -d '{"default_policy": "DENY", "status": "ACTIVE"}'# 2. Allow office networkcurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: acme-corp" \
  -d '{"ip_address": "192.168.1.0/24", "action": "ALLOW", "reason": "Office network"}'

Result:

IP	Rule Match	Access
`203.0.113.10`	Auto-created ALLOW	Allowed
`192.168.1.50`	CIDR ALLOW	Allowed
`10.0.0.99`	No rule → Default DENY	Blocked

Example 3: Temporary Contractor Access

# Create rule with expirationcurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: acme-corp" \
  -d '{
    "ip_address": "45.67.89.100",
    "action": "ALLOW",
    "reason": "Contractor - Project Alpha",
    "expires_at": "2026-03-17T00:00:00Z",
    "notes": "Contract #CON-2026-042"
  }'

Rule auto-expires and is cleaned up by hourly job.

Example 4: CIDR with Exception

Block a range but allow specific IP within it.

# Block suspicious rangecurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: acme-corp" \
  -d '{"ip_address": "198.51.100.0/24", "action": "BLOCK", "reason": "Malicious range"}'# Allow trusted partner in that rangecurl -X POST /v1/waf/rules \
  -H "X-User-Org-Id: acme-corp" \
  -d '{"ip_address": "198.51.100.75", "action": "ALLOW", "reason": "Trusted partner"}'

Result: 198.51.100.75 is ALLOWED (/32 beats /24)

Architecture

Multi-Tenant Design

WAF operates at the organization level with complete isolation.

flowchart TB
    subgraph Platform["Platform"]
        subgraph Org1["Organization A"]
            WAF1["WAF Config + Rules"]
        end
        subgraph Org2["Organization B"]
            WAF2["WAF Config + Rules"]
        end
    end

IP Check Flow

Redis Key Patterns

Key	Type	Purpose
`waf:exact:{orgId}`	Hash	Exact IP rules
`waf:cidr:{orgId}`	Hash	CIDR rules
`waf:config:{orgId}`	String	Default policy
`waf:nc:{orgId}:{ip}`	String	Negative cache

Storage

MongoDB: Source of truth for config and rules
Redis: High-performance cache layer

Performance

Response Times

Scenario	Latency
Redis hit (exact/CIDR)	~1ms
Redis hit (negative cache)	~1ms
MongoDB fallback	~15ms

Negative Cache

Caches “no rule found” results to prevent repeated MongoDB queries. Without negative cache: Every unknown IP → MongoDB query With negative cache: First query → MongoDB, subsequent → Redis (~93% faster)

Cache Invalidation

Operation	Invalidation Scope
Create exact rule	Single IP negative cache
Create CIDR rule	All negative cache for org
Update policy	All negative cache for org
Sync cache	All cache for org

Troubleshooting

Enable Debug Logging


waf:  debug-logging: true

Common Issues

Issue	Solution
Rule not taking effect	Clear cache: `DELETE /v1/waf/cache/{orgId}`
Locked out after DENY mode	Auto-rule should be created; check with `GET /v1/waf/rules`
High latency	Check Redis connectivity; ensure cache warmup completed
Rules not expiring	Verify cleanup scheduler is running

Bypass WAF for Troubleshooting

Set status to INACTIVE to allow all traffic:

curl -X PUT /v1/waf/config \
  -H "X-User-Org-Id: your-org-id" \
  -d '{"status": "INACTIVE"}'

Remember to re-enable after troubleshooting!

Safety Features

Auto-Rule Creation

When switching to DENY mode, an ALLOW rule is automatically created for the requesting client IP to prevent admin lockout.

Policy Change Protection

Changing between ALLOW and DENY clears existing rules to ensure consistent behavior.

​Organization-Specific Protection

​Policy Modes

​Quick Start

​1. Configure WAF for Your Organization

​2. Add IP Rules

​3. Check IP Access

​Core Concepts

​Default Policy

​IP Types

​CIDR Notation

​Rule Priority (Specificity)

​WAF Status

​API Reference

​Endpoints

​Request Headers

​Data Models

​Configuration

​Application Properties

​Limits

​Usage Examples

​Example 1: Blocklist Mode (Default: ALLOW)

​Example 2: Allowlist Mode (Default: DENY)

​Example 3: Temporary Contractor Access

​Example 4: CIDR with Exception

​Architecture

​Multi-Tenant Design

​IP Check Flow

​Redis Key Patterns

​Storage

​Performance

​Response Times

​Negative Cache

​Cache Invalidation

​Troubleshooting

​Enable Debug Logging

​Common Issues

​Bypass WAF for Troubleshooting

​Safety Features

​Auto-Rule Creation

​Policy Change Protection