Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(security): match access rules on email patterns (#121133)

Yasenb44a5292e436
diff --git a/products/security/backend/logic/accounts.py b/products/security/backend/logic/accounts.py
index fcf1f59ad1ff..8fd20e554736 100644
--- a/products/security/backend/logic/accounts.py
+++ b/products/security/backend/logic/accounts.py
@@ -11,13 +11,14 @@ from posthog.helpers.email_utils import EmailLookupHandler
from posthog.models import Organization, OrganizationMembership, User
from .decisions import PROTECTED_DOMAIN
+from .rules import EmailPattern
from .subjects import DOT_INSENSITIVE_DOMAINS
-# An email root or domain count has no index to use, so an uncapped count would scan
+# An email root, domain or pattern count has no index to use, so an uncapped count would scan
# every row of posthog_user while the admin waits.
COUNT_CAP = 500
-CountableType = Literal["email", "email_root", "email_domain"]
+CountableType = Literal["email", "email_root", "email_domain", "email_pattern"]
@frozen
@@ -93,6 +94,10 @@ def _email_root_regex(root: str) -> str:
return rf"^{re.escape(local)}{suffix}@{re.escape(domain)}$"
+def _email_pattern_regex(pattern: EmailPattern) -> str:
+ return "^" + ".*".join(re.escape(segment) for segment in pattern.segments) + "$"
+
+
def count_active_accounts(target_type: CountableType, value: str) -> CappedCount:
if target_type == "email":
# Matches resolve_subject's fold (LOWER via EmailLookupHandler), not `iexact` (UPPER):
@@ -103,6 +108,12 @@ def count_active_accounts(target_type: CountableType, value: str) -> CappedCount
condition = Q(email__iregex=_email_root_regex(value))
case "email_domain":
condition = Q(email__iendswith=f"@{value}") | Q(email__iendswith=f".{value}")
+ case "email_pattern":
+ pattern = EmailPattern.parse(value.strip().lower())
+ # A pattern the snapshot would refuse matches nobody at decision time, so it counts nobody.
+ if pattern is None:
+ return CappedCount(count=0, capped=False)
+ condition = Q(email__iregex=_email_pattern_regex(pattern))
return _capped(User.objects.filter(condition, is_active=True))
diff --git a/products/security/backend/logic/matching.py b/products/security/backend/logic/matching.py
index 2998e435b6f6..e3d055fa6006 100644
--- a/products/security/backend/logic/matching.py
+++ b/products/security/backend/logic/matching.py
@@ -1,7 +1,9 @@
"""Which snapshot rules can match a subject, and whether one does.
-Every target type except IP ranges is an exact lookup, so a decision stays fast with
-thousands of rules. Domain rules are looked up once per suffix of the subject's domain.
+Every target type except IP ranges and email patterns is an exact lookup, so a decision
+stays fast with thousands of rules. Domain rules are looked up once per suffix of the
+subject's domain. Email patterns are parsed once per snapshot, and a decision checks them
+only when the subject has an email address.
"""
from collections import defaultdict
@@ -31,11 +33,16 @@ def _match_domain(rule: SnapshotRule, subject: Subject) -> bool:
return domain is not None and (domain == rule.target_value or domain.endswith(f".{rule.target_value}"))
+def _match_email_pattern(rule: SnapshotRule, subject: Subject) -> bool:
+ return rule.email_pattern is not None and subject.email is not None and rule.email_pattern.matches(subject.email)
+
+
_MATCHERS: dict[str, Callable[[SnapshotRule, Subject], bool]] = {
"user_uuid": lambda rule, subject: subject.user_uuid == rule.target_value,
"email": lambda rule, subject: subject.email == rule.target_value,
"email_root": lambda rule, subject: subject.email_root == rule.target_value,
"email_domain": _match_domain,
+ "email_pattern": _match_email_pattern,
"organization_id": lambda rule, subject: rule.target_value in subject.organization_ids,
"ip": _match_ip,
"everyone": lambda rule, subject: True,
@@ -52,20 +59,28 @@ def rule_matches(rule: SnapshotRule, subject: Subject) -> bool:
class RuleIndex:
exact: Mapping[tuple[str, str], tuple[SnapshotRule, ...]]
networks: tuple[SnapshotRule, ...]
+ email_patterns: tuple[SnapshotRule, ...]
-EMPTY_INDEX = RuleIndex(exact={}, networks=())
+EMPTY_INDEX = RuleIndex(exact={}, networks=(), email_patterns=())
def build_index(rules: Iterable[SnapshotRule]) -> RuleIndex:
exact: defaultdict[tuple[str, str], list[SnapshotRule]] = defaultdict(list)
networks: list[SnapshotRule] = []
+ email_patterns: list[SnapshotRule] = []
for rule in rules:
if rule.target_type == "ip":
networks.append(rule)
+ elif rule.target_type == "email_pattern":
+ email_patterns.append(rule)
elif rule.target_type in _EXACT_TYPES:
exact[(rule.target_type, rule.target_value)].append(rule)
- return RuleIndex(exact={key: tuple(value) for key, value in exact.items()}, networks=tuple(networks))
+ return RuleIndex(
+ exact={key: tuple(value) for key, value in exact.items()},
+ networks=tuple(networks),
+ email_patterns=tuple(email_patterns),
+ )
def _domain_suffixes(domain: str | None) -> list[str]:
@@ -93,4 +108,7 @@ def candidates(index: RuleIndex, subject: Subject) -> list[SnapshotRule]:
if subject.ip is not None:
for rule in index.networks:
found[rule.id] = rule
+ if subject.email:
+ for rule in index.email_patterns:
+ found[rule.id] = rule
return sorted(found.values(), key=lambda rule: rule.id)
diff --git a/products/security/backend/logic/rules.py b/products/security/backend/logic/rules.py
index 3f1bc76c5024..959e9c5b62f9 100644
--- a/products/security/backend/logic/rules.py
+++ b/products/security/backend/logic/rules.py
@@ -1,5 +1,6 @@
"""One rule as the hub's snapshot delivers it. Values are already normalized by the hub."""
+import re
import ipaddress
from datetime import datetime
from typing import Any
@@ -7,6 +8,63 @@ from typing import Any
from posthog.dataclasses import frozen
_TEXT_FIELDS = ("id", "targetType", "targetValue", "effect", "scope")
+_EMAIL_TYPES = ("email", "email_root", "email_domain", "email_pattern")
+
+_WILDCARD = "*"
+_MAX_PATTERN_WILDCARDS = 3
+_MIN_PATTERN_LOCAL_LITERALS = 3
+_MAX_PATTERN_DOMAIN_LENGTH = 253
+_PATTERN_DOMAIN_LABEL = re.compile(r"[a-z0-9*-]+")
+
+
+@frozen
+class EmailPattern:
+ """A whole-address glob. `*` matches any run of characters, and every other character is literal."""
+
+ segments: tuple[str, ...]
+
+ @classmethod
+ def parse(cls, value: str) -> "EmailPattern | None":
+ """The pattern, or None when it breaks the hub's limits.
+
+ The hub refuses these values when a rule is written. Refusing them again here means a
+ bad row can never match everyone, as `*@*` would. The hub also refuses a pattern whose
+ literal domain is posthog.com. That check is not repeated here, because a decision never
+ blocks a posthog.com account.
+ """
+ local, at, domain = value.partition("@")
+ if not at or "@" in domain or re.search(r"\s", value):
+ return None
+ if value.count(_WILDCARD) > _MAX_PATTERN_WILDCARDS:
+ return None
+ if len(local.replace(_WILDCARD, "")) < _MIN_PATTERN_LOCAL_LITERALS:
+ return None
+ if domain != _WILDCARD:
+ labels = domain.split(".")
+ if len(domain) > _MAX_PATTERN_DOMAIN_LENGTH:
+ return None
+ if not all(_PATTERN_DOMAIN_LABEL.fullmatch(label) for label in labels):
+ return None
+ if all(_WILDCARD in label for label in labels):
+ return None
+ return cls(segments=tuple(value.split(_WILDCARD)))
+
+ def matches(self, address: str) -> bool:
+ # Not a regex: with three wildcards a backtracking regex does cubic work on a crafted
+ # address, and signup and login run this for every pattern rule.
+ if len(self.segments) == 1:
+ return address == self.segments[0]
+ head, *middle, tail = self.segments
+ end = len(address) - len(tail)
+ if end < len(head) or not address.startswith(head) or not address.endswith(tail):
+ return False
+ position = len(head)
+ for segment in middle:
+ found = address.find(segment, position, end)
+ if found < 0:
+ return False
+ position = found + len(segment)
+ return True
@frozen
@@ -17,8 +75,9 @@ class SnapshotRule:
effect: str
scope: str
expires_at: datetime | None = None
- # Parsed once when the snapshot loads, so a decision never re-parses a range.
+ # Parsed once when the snapshot loads, so a decision never re-parses a range or a pattern.
network: ipaddress.IPv4Network | ipaddress.IPv6Network | None = None
+ email_pattern: EmailPattern | None = None
@classmethod
def from_wire(cls, raw: object) -> "SnapshotRule | None":
@@ -56,9 +115,19 @@ class SnapshotRule:
# snapshot un-normalized would match nobody, and nothing would report it. The Redis
# list this replaced lowercased on read, so it could not be defeated that way.
target_value = values["targetValue"]
- if values["targetType"] in ("email", "email_root", "email_domain"):
+ if values["targetType"] in _EMAIL_TYPES:
target_value = target_value.strip().lower()
+ email_pattern = None
+ if values["targetType"] == "email_pattern":
+ # The hub writes pattern rules as blocks only. An exemption on a pattern would
+ # drop the login email code for every address it covers.
+ if values["effect"] != "block":
+ return None
+ email_pattern = EmailPattern.parse(target_value)
+ if email_pattern is None:
+ return None
+
return cls(
id=values["id"],
target_type=values["targetType"],
@@ -67,4 +136,5 @@ class SnapshotRule:
scope=values["scope"],
expires_at=expires_at,
network=network,
+ email_pattern=email_pattern,
)
diff --git a/products/security/backend/presentation/serializers.py b/products/security/backend/presentation/serializers.py
index 693fea81f723..1193855fe379 100644
--- a/products/security/backend/presentation/serializers.py
+++ b/products/security/backend/presentation/serializers.py
@@ -1,8 +1,19 @@
"""DRF serializers for security."""
+from django.db import models
+
from rest_framework import serializers
+class CountableTargetType(models.TextChoices):
+ """The target types the hub can count accounts for. Keep in step with `CountableType`."""
+
+ EMAIL = "email"
+ EMAIL_ROOT = "email_root"
+ EMAIL_DOMAIN = "email_domain"
+ EMAIL_PATTERN = "email_pattern"
+
+
class ResolveRequestSerializer(serializers.Serializer):
query = serializers.CharField(
max_length=400,
@@ -14,7 +25,7 @@ class ResolveRequestSerializer(serializers.Serializer):
class CountAccountsRequestSerializer(serializers.Serializer):
target_type = serializers.ChoiceField(
- choices=["email", "email_root", "email_domain"], help_text="How target_value matches accounts."
+ choices=CountableTargetType.choices, help_text="How target_value matches accounts."
)
target_value = serializers.CharField(max_length=320, help_text="The value the hub normalized for this target type.")
diff --git a/products/security/backend/tests/fixtures/access-rules.json b/products/security/backend/tests/fixtures/access-rules.json
index 1cc1b12bb51d..2eadadefb492 100644
--- a/products/security/backend/tests/fixtures/access-rules.json
+++ b/products/security/backend/tests/fixtures/access-rules.json
@@ -86,6 +86,37 @@
{"name": "empty subject", "subject": {}, "expect": "AAAEA"},
{"name": "posthog.com account", "subject": {"email": "[email protected]"}, "expect": "AAAEA"}
]
+ },
+ {
+ "name": "email patterns",
+ "now": "2026-09-17T12:00:00Z",
+ "rules": [
+ {"id": "01920000-0000-7000-8000-000000000201", "targetType": "email_pattern", "targetValue": "farm_acct_*@*", "effect": "block", "scope": "ai_gateway", "expiresAt": null},
+ {"id": "01920000-0000-7000-8000-000000000202", "targetType": "email_pattern", "targetValue": "abuser*@example.com", "effect": "block", "scope": "all_access", "expiresAt": null},
+ {"id": "01920000-0000-7000-8000-000000000203", "targetType": "email_pattern", "targetValue": "farm.bot+*@example.org", "effect": "block", "scope": "signup", "expiresAt": null},
+ {"id": "01920000-0000-7000-8000-000000000204", "targetType": "email_pattern", "targetValue": "dotted.victim*@gmail.com", "effect": "block", "scope": "all_access", "expiresAt": null},
+ {"id": "01920000-0000-7000-8000-000000000205", "targetType": "email_pattern", "targetValue": "bot?[1]*@*.example.net", "effect": "block", "scope": "all_access", "expiresAt": null}
+ ],
+ "cases": [
+ {"name": "wildcard domain", "subject": {"email": "[email protected]"}, "expect": "AABAA", "deciding": {"ai_gateway": "01920000-0000-7000-8000-000000000201"}},
+ {"name": "matching ignores case", "subject": {"email": " [email protected] "}, "expect": "AABAA"},
+ {"name": "a star can match nothing", "subject": {"email": "[email protected]"}, "expect": "BBBAA"},
+ {"name": "a star can match a +suffix", "subject": {"email": "[email protected]"}, "expect": "BBBAA"},
+ {"name": "an underscore matches only itself", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "the pattern covers the start of the address", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "the pattern covers the end of the address", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "a literal domain does not cover subdomains", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "a dot and a plus match only themselves", "subject": {"email": "[email protected]"}, "expect": "BAAAA"},
+ {"name": "a dot is not a single-character wildcard", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "a plus is not a repeat", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "the full address is matched, not the email root", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "the dotted address matches", "subject": {"email": "[email protected]"}, "expect": "BBBAA"},
+ {"name": "question mark and brackets match only themselves", "subject": {"email": "bot?[1][email protected]"}, "expect": "BBBAA"},
+ {"name": "question mark is not a single-character wildcard", "subject": {"email": "botx[1][email protected]"}, "expect": "AAAAA"},
+ {"name": "brackets are not a character class", "subject": {"email": "[email protected]"}, "expect": "AAAAA"},
+ {"name": "a domain alone matches no pattern", "subject": {"domain": "example.com"}, "expect": "AAAAA"},
+ {"name": "a posthog.com account is never blocked", "subject": {"email": "[email protected]"}, "expect": "AAAAA"}
+ ]
}
]
}
diff --git a/products/security/backend/tests/test_accounts.py b/products/security/backend/tests/test_accounts.py
index c41aae2f6c2f..1820e37e9bf1 100644
--- a/products/security/backend/tests/test_accounts.py
+++ b/products/security/backend/tests/test_accounts.py
@@ -1,17 +1,28 @@
+from typing import get_args
+
from posthog.test.base import BaseTest
+from django.test import SimpleTestCase
+
from parameterized import parameterized
from posthog.models import Organization, OrganizationMembership, User
from products.security.backend.logic.accounts import (
COUNT_CAP,
+ CountableType,
count_active_accounts,
count_active_org_members,
email_for_user,
has_posthog_account,
resolve_subject,
)
+from products.security.backend.presentation.serializers import CountableTargetType
+
+
+class TestCountableTargetTypes(SimpleTestCase):
+ def test_serializer_accepts_every_countable_type(self) -> None:
+ assert set(CountableTargetType.values) == set(get_args(CountableType))
class TestAccounts(BaseTest):
@@ -47,6 +58,9 @@ class TestAccounts(BaseTest):
assert count_active_accounts("email", "[email protected]").count == 1
assert count_active_accounts("email_domain", "throwaway.example").count == 1
assert count_active_accounts("email_root", "[email protected]").count == 1
+ assert count_active_accounts("email_pattern", "farm.bot+*@example.com").count == 1
+ assert count_active_accounts("email_pattern", "far.*@*").count == 0
+ assert count_active_accounts("email_pattern", "*@*").count == 0
def test_counts_are_capped(self) -> None:
User.objects.bulk_create(
diff --git a/products/security/backend/tests/test_decisions.py b/products/security/backend/tests/test_decisions.py
index 1b319ff0d0be..711055252244 100644
--- a/products/security/backend/tests/test_decisions.py
+++ b/products/security/backend/tests/test_decisions.py
@@ -16,6 +16,18 @@ from products.security.backend.logic.subjects import normalize_subject
VECTORS = json.loads((Path(__file__).parent / "fixtures" / "access-rules.json").read_text())
ORDER = [Surface.SIGNUP, Surface.APP, Surface.AI_GATEWAY, Surface.EMAIL_CODE, Surface.SIGNUP_RISK]
LETTERS = {Surface.EMAIL_CODE: "E", Surface.SIGNUP_RISK: "E"}
+NOW = datetime(2026, 9, 17, 12, tzinfo=UTC)
+
+
+def _pattern_rule(value: str, **overrides: str) -> dict[str, str]:
+ return {
+ "id": "pattern",
+ "targetType": "email_pattern",
+ "targetValue": value,
+ "effect": "block",
+ "scope": "all_access",
+ **overrides,
+ }
def _cases() -> list[tuple[str, dict[str, Any], dict[str, Any]]]:
@@ -84,6 +96,16 @@ class TestWireParsing(TestCase):
"bad network",
{"id": "a", "targetType": "ip", "targetValue": "not-a-range", "effect": "block", "scope": "signup"},
),
+ ("pattern matches everyone", _pattern_rule("*@*")),
+ ("pattern local part has two literals", _pattern_rule("ab*@*")),
+ ("pattern names only a domain", _pattern_rule("*@gmail.com")),
+ ("pattern has four wildcards", _pattern_rule("abc*d*e*f*@example.com")),
+ ("pattern has two @", _pattern_rule("abc@[email protected]")),
+ ("pattern domain has no literal label", _pattern_rule("abc*@*.*")),
+ ("pattern domain has an empty label", _pattern_rule("abc*@example..com")),
+ ("pattern domain has an underscore", _pattern_rule("abc*@exa_mple.com")),
+ ("pattern has a space", _pattern_rule("abc *@example.com")),
+ ("pattern exemption", _pattern_rule("abc*@example.com", effect="exempt", scope="email_code")),
]
)
def test_malformed_rules_are_skipped(self, _name: str, raw: object) -> None:
@@ -103,6 +125,39 @@ class TestWireParsing(TestCase):
assert rule is not None and rule.expires_at == datetime(2026, 9, 1, tzinfo=UTC)
+class TestEmailPatterns(TestCase):
+ @parameterized.expand(
+ [
+ ("head and tail never overlap", "abc*[email protected]", "[email protected]", False),
+ ("a middle segment never overlaps the tail", "abc*_*[email protected]", "[email protected]", False),
+ ("three wildcards", "bot*_*@*.example.com", "[email protected]", True),
+ ("segments match in order", "bot*_*@*.example.com", "bot12@x_mail.example.com", False),
+ ]
+ )
+ def test_pattern_block(self, _name: str, pattern: str, email: str, blocked: bool) -> None:
+ rule = SnapshotRule.from_wire(_pattern_rule(pattern))
+ assert rule is not None
+ decided = deciding_rule(build_index([rule]), normalize_subject(email=email), Surface.APP, NOW)
+ assert (decided is not None) is blocked
+
+ def test_oldest_rule_decides_across_patterns_and_exact_addresses(self) -> None:
+ exact = SnapshotRule.from_wire(
+ {
+ "id": "b",
+ "targetType": "email",
+ "targetValue": "[email protected]",
+ "effect": "block",
+ "scope": "all_access",
+ }
+ )
+ pattern = SnapshotRule.from_wire(_pattern_rule("abuser*@example.com", id="a"))
+ assert exact is not None and pattern is not None
+ decided = deciding_rule(
+ build_index([exact, pattern]), normalize_subject(email="[email protected]"), Surface.APP, NOW
+ )
+ assert decided is not None and decided.id == "a"
+
+
class TestProtectedDomain(TestCase):
@parameterized.expand([("posthog.com", True), ("eu.posthog.com", True), ("notposthog.com", False), (None, False)])
def test_is_protected_domain(self, domain: str | None, expected: bool) -> None: