Rules and Blocklists

Tangate uses a layered rules system that merges threat intelligence, operator rules, and your local overrides into a single blocklist enforced at the CloudFront edge.

Rule Types

Tangate supports four types of blocking rules:

Type Example Matching
IPs 1.2.3.4 Exact IP match
CIDRs 192.0.2.0/24 IP falls within CIDR range
User Agents BadBot/ Partial string match against User-Agent header
Query Patterns eval( Partial string match against query string

User agent and query pattern rules use partial (substring) matching. A rule value of BadBot/ will match any user agent containing that string, such as BadBot/1.0 or Mozilla BadBot/2.0.

Rules Hierarchy

Rules are fetched and merged from four sources, in order of increasing precedence:

Priority Source Scope Auth
1 (lowest) Global All instances No auth (public)
2 Elevated Elevated protection enabled Instance API key
3 Instance Your deployment only Instance API key
4 (highest) Local Your deployment only Your S3 bucket

How Merging Works

  1. Global rules are loaded first (threat intelligence from open-source feeds)
  2. Elevated rules are added (if your tier includes elevated protection)
  3. Instance-specific rules are added (operator-assigned rules for your deployment)
  4. Local rules are applied last:
    • Local blocklist entries are added to the combined blocklist
    • Local whitelist entries override everything — a whitelisted IP is never blocked

Local whitelist wins over everything. If an IP appears in the global threat intel blocklist but you have whitelisted it locally, it will not be blocked. This is by design — you have full override control in your own AWS account.

Local Rules File

Your local rules are stored at s3://{bucket}/deckard/local-rules.json. A starter template with empty arrays is created during deployment.

Schema

{
  "version": "1.0",
  "updated": "2026-03-05T00:00:00Z",
  "whitelist": {
    "ips": ["203.0.113.42", "198.51.100.0/24"],
    "user_agents": ["OurMonitor/1.0", "PartnerBot/2.0"],
    "query_patterns": []
  },
  "blocklist": {
    "ips": ["192.0.2.100"],
    "user_agents": ["KnownBadBot/"],
    "query_patterns": ["eval(", "UNION SELECT"]
  }
}

Managing Local Rules

You can manage local rules through:

  • Dashboard My Rules page — Add and remove entries through the web UI. See Dashboard.
  • Dashboard API — POST /api/rules and DELETE /api/rules with {list, type, value} body.
  • Direct S3 edit — Edit the JSON file directly in S3. Useful for bulk changes.

Changes take effect on the next hourly analysis run.

Common Use Cases

Whitelist your office IP range:

{
  "whitelist": {
    "ips": ["203.0.113.0/24"]
  }
}

Whitelist a monitoring service:

{
  "whitelist": {
    "user_agents": ["UptimeRobot/2.0", "Pingdom/"]
  }
}

Block a known bad actor immediately:

{
  "blocklist": {
    "ips": ["192.0.2.100"],
    "user_agents": ["ScrapeBot/"]
  }
}

Override Logging

When a local whitelist entry overrides a Tangate rule, a structured log entry is written to CloudWatch:

{
  "event": "LOCAL_WHITELIST_OVERRIDE",
  "ip": "203.0.113.42",
  "overridden_rule": "tyrell:global:botnet-c2",
  "timestamp": "2026-03-05T14:00:00Z"
}

Blocklist Enforcement

The combined blocklist is written to s3://{bucket}/deckard/blocklist.json after each analysis run. Lambda@Edge reads this file and caches it for 5 minutes.

Blocklist JSON Schema

{
  "version": "abc123",
  "generated": "2026-03-05T14:00:00Z",
  "blocked_ips": ["1.2.3.4", "5.6.7.8"],
  "blocked_cidrs": ["192.0.2.0/24"],
  "blocked_user_agents": ["BadBot/"],
  "blocked_query_patterns": ["eval("]
}

Enforcement Behavior

For each incoming CloudFront viewer request:

  1. Client IP is checked against blocked_ips (exact match)
  2. Client IP is checked against blocked_cidrs (CIDR range match)
  3. User-Agent header is checked against blocked_user_agents (substring match)
  4. Query string is checked against blocked_query_patterns (substring match)
  5. If any check matches, the request is blocked with a 403 Forbidden response
  6. If no checks match, the request passes through to CloudFront

The blocklist cache refreshes every 5 minutes. After an analysis run updates the blocklist in S3, new blocks take effect within 5 minutes at the edge.

Next Steps