Detection Rules
Rules are data, not code. Adding detection coverage means editing YAML in backend/rules/ — no Python changes, no redeploy of logic.
Adding a rule
backend/rules/scam_rules.yaml:
- id: refund-bait # unique slug, kebab-case
category: remote_access # must match a ScamCategory in schemas.py
description: Unexpected refund that requires codes, apps, or screen access
weight: 0.6 # 0–1 contribution
severity: high # low | medium | high | critical
locales: [ar] # optional; omit for English/default
channels: [call] # optional; omit to run on every channel
patterns:
- '\b(refund|overcharg\w+)\b.{0,80}\b(otp|code|install|screen)\b'
exclude_patterns: # optional negation guards
- "\\b(never|do not)\\s+(share|send)\\b.{0,40}\\b(otp|code)"
Then bump version: at the top of the file (clients use it for cache invalidation) and add a test in backend/tests/.
Field semantics
| Field | Meaning |
|---|---|
weight | Aggregated with diminishing returns: 1 − Π(1 − wᵢ). Three 0.5 rules ≈ 0.875, never a naive sum. |
severity: critical | Sets a hard score floor of 0.85 that AI cannot lower. Use only for near-proof signals (OTP requests, remote-access demands). |
locales | Rule applies when the resolved locale matches or its script is in the text (Arabic) — UAE calls and texts switch language mid-way, and one locale per message cannot describe that. Omitting it means English/default. |
channels | Optional. [call] = runs only on live calls and call transcripts; omit to run everywhere. Call-only rules are left out of the on-device rules pack. See below. |
exclude_patterns | Suppresses a match only inside its own span — see below. |
Calls are judged differently: channels
The same words mean different things on different channels. In a text from your bank, "your OTP is 482913" is the most ordinary message there is — so text rules need a request aimed at you before they fire. On a call, a caller talking about your OTP, PIN or card number at all is the scam: no bank does that.
Written only for texts, the rules were silent on "what is your OTP?", "I need your PIN", "OTP please" during a live call — 7 of 26 natural English red flags and 0 of 16 Arabic ones produced a warning (2026-10-01). Loosening the text rules would flag genuine bank texts again, so calls get rules of their own:
- id: call-credential-talk
channels: [call] # live calls + call transcripts only
...
The engine is told the channel: the live-call manager and any source_type: call_transcript pass call; everything else passes message. The on-device rules pack omits call-only rules — the phones judge SMS, and a call-only rule there would fire on every ordinary bank text that says "OTP".
A call-only rule also needs an entry in _INSTANT_ALERT_RULES (app/core/livecall.py) or it can raise the score but never put a warning on screen — which is exactly how every Arabic rule was silent on calls until 2026-10-01. Tests: tests/test_call_rules.py (calls, both languages, both directions) and tests/test_live_call_browser.py (the served page).
Cover the setup, not only the demand. The first call rules fired on the ask — the code, the PIN, the transfer. A scam call spends its first minute getting you frightened enough to comply: "your account will be blocked", "your Emirates ID was used in a money-laundering case", "this call is confidential". 25 of 27 such lines raised no warning (2026-10-08), so the listener sat silent until the end. The setup rules — call-account-threat, call-authority-case, call-device-control, call-login-secret, call-secrecy and Arabic twins — warn on the opening.
Write call rules in the second person. The microphone hears both sides. "Your card has been blocked" is a caller's script; "my card got blocked last week" is the user talking about their day. Every setup rule keys on your / ك, and each has an ordinary-day twin in the quiet list.
A guard must cover the whole list. Because suppression is span-scoped (next section), a guard that ends at the first secret lets "never share your password or PIN" escape: the match runs on to "PIN", outside the guard. Guards for safety advice now extend across ", / or / and" lists of secrets.
Negation guards and span containment
Real banks write "Never share your OTP with anyone." A naive OTP rule flags that as a scam. exclude_patterns fixes it — but suppression is span-scoped, not message-scoped:
"Please don't tell anyone about this call … now confirm the OTP."
The negation in the first clause must not silence the demand in the second. The engine only suppresses a positive match when it falls entirely inside an exclude span. Keep guards tight (never\s+share, not never.*share) so a scammer cannot disarm a rule by prefacing their demand with safety language.
Tight at the head is not enough — the tail runs on too. A guard like don't\s+tell\b.{0,40}\b(otp|code) has a tight head and a greedy tail: in "don't tell anyone, just give me the OTP" it stretches from "don't tell" all the way to "OTP" and swallows the demand. Use a tempered gap that cannot cross another disclosure verb, and make it lazy:
(?:(?!\b(?:give|tell|read|send|share|say|repeat|provide|forward)\b)[^.!?]){0,40}?
Speech has no full stops
Live-call transcripts arrive from the recogniser as one unpunctuated run: "hello this is your bank don't panic just tell me the code we sent". Anything that relies on [^.!?] as a sentence boundary — every guard, every gap — reaches across what were separate sentences. On 2026-10-01 that turned "don't panic" into a guard that excused the whole demand: 0.00 during a live scam call. Test every rule with lower-case, unpunctuated speech as well as typed text.
Direction: a mention of a code is not a request for it
Genuine services send codes to you and tell you to use them: "enter the code we sent", "we'll send you a 6-digit code", "your verification code is 482913". Scams ask for the code back: "read me the code", "tell me the code we sent", "send it to us". A rule that matches the noun alone flags the most common genuine texts there are — on 2026-10-01, 12 of 28 genuine English messages and 9 of 16 Arabic ones were "scams". So:
- Giving verbs need a recipient:
send|give|tell|share … me|us. Lookahead out the service's own phrasing:send(?!\s+(?:you|u)\b). - A bare "code" needs proof it's the one just delivered — "we sent", "you received", "on your phone". Otherwise it's a door, a discount or source code.
- In-app verbs are not demands: enter, type, use, confirm (imperative). "Can you confirm the code" — a question to a person — is.
- Warnings quote the scam. "If anyone asks you to read out the code we sent, hang up" contains the scam sentence verbatim. Exclude third-person framings.
tests/test_speech_and_2fa.py holds the fire/safe matrix in both languages. Add to both lists with any change: most regressions here are false positives introduced while chasing a miss — including the one this section exists because of.
Red-team every rule before it ships
A genuine list only protects you if it was written to break the rule. On 2026-11-12 twenty new rules passed 146 genuine messages and then flagged 29 of 52 genuine sentences built from their own trigger words. Before a rule ships, write ten genuine sentences that use its vocabulary on purpose, covering at least:
| Write a sentence that is… | Because the scam is… | Example that must stay clean |
|---|---|---|
| narration — I / we / she / "did you…?" | a demand aimed at the reader | "I had to pay a clearance fee first before customs released the car" |
| a question or a remark about scams | a pitch, not a discussion | "Guaranteed returns? Sounds like a scam to me." |
| the same verb with an ordinary object | about a windfall | "Pay the delivery fee to the driver to receive your order" |
| the same nouns in the other direction | asking you to give | "I'll send you the gift card code — happy birthday" |
| the setup without the ask | setup and a money request | "Hi mum, new number, save it!" |
| an organisation doing its normal job | impersonating one | "Your gym membership was renewed. Questions? Contact reception." |
Reusable guards live in the rules file as lookbehinds for narration and (?![^.!?]*\?) for questions. tests/test_scam_tactics.py holds the red-team sentences; add yours there.
Calibration: how strong is one hit?
A single rule of weight w, with no bad link and no AI, scores about 0.64 × w:
| Weight | Alone | Use for |
|---|---|---|
| ≥ 0.85 | Scam | Definitive on its own: a code, a recovery phrase, gift-card codes, blackmail |
| 0.75 | Be careful — "Likely" with any second signal, including urgency | A specific pattern you cannot fully rule out in genuine text |
| 0.5 – 0.6 | Be careful | A signal that is common in scams and not rare elsewhere |
| ≤ 0.35 | Nothing alone | Supporting evidence only |
Until the labelled corpus exists and the false-positive rate is measured, new pattern rules go in at 0.75 or below.
Adding an impersonated entity
backend/rules/known_entities.yaml:
- id: emirates_nbd
name: Emirates NBD
category: bank_impersonation
aliases: ['emirates\s*nbd', '\benbd\b', 'الإمارات دبي الوطني']
official_domains: [emiratesnbd.com]
official_senders: [EmiratesNBD]
official_phones: ["600540000"] # digits only, local format
Verify every value against the entity's official website. A wrong official domain creates false positives against a legitimate institution; a wrong official phone creates false negatives for a real scam. The seeded numbers are examples — confirm before shipping.
A match on official_senders or official_phones never proves legitimacy (both are spoofable) — only a mismatch adds suspicion.
Arabic rules
Spelling is folded before matching
Arabic is written — and transcribed — several ways for the same word: hamza on the alef or not (أعطني / اعطني), taa marbuta or haa (الهوية / الهويه), alef maqsura or yaa (على / علي), diacritics or none, Arabic-Indic digits or Latin. Speech recognisers are not consistent, so one spelling in a pattern meant the same request alerted on one call and not the next. The server folds text and patterns to one spelling (fold_arabic in app/core/rules.py) before matching; entity aliases and claim markers are folded the same way.
The rules pack ships patterns as written in the YAML, because the phone engines match unfolded text — so rules that go to phones still list both spellings. Call-only rules never ship to phones and are written folded.
Requests on a call, as a recogniser writes them
Measured 2026-11-20 on recogniser-style text (no punctuation, dialect, dropped hamza): 53 of 100 requests for a code or a personal detail raised no warning. Four call-only rules close the gap — call-code-readback / ar-call-code-readback ("read me the numbers in the message", "بيوصلك كود الحين عطني اياه") and call-personal-details / ar-call-personal-details (Emirates ID, passport, IBAN, account and card numbers, photos of them). They are new pattern rules, so weight ≤ 0.75 until their false-positive rate is measured, but they count towards the combo alarm after a contradicted identity claim.
Date of birth is combo-only (call-identity-question, ar-call-identity-question, weight 0.3, no alert line): clinics, airlines and the bank you called all ask for it. It raises the score and, after a false identity claim, completes the combo alarm. The design and held-out corpora are in tests/test_call_requests.py.
Arabic rules carry locales: [ar] and are written to mirror the English pack, so per-language coverage stays comparable. Notes:
- Match both spellings of hamza forms (
أandا) — users type both. - Arabic has no case, so
re.IGNORECASEis irrelevant; rely on alternation. - Test with real message text, not translations of English rules — scam phrasing differs idiomatically.
- Mind substrings. "سري" (secret) is the second word of "الرقم السري" — the ordinary word for PIN — so a secrecy rule matching it unbounded fired on every message that mentioned a PIN. Bound standalone words with
(?<![\u0600-\u06FF])…(?![\u0600-\u06FF]). - Direction applies here too: "رمز التحقق الخاص بك هو 482913" (your verification code is 482913) is the plainest genuine bank text there is. A demand needs a verb aimed at the caller — أعطني، أرسل لي، قل لي، اقرأه لي.
Coverage is computed from rules present, so adding Arabic rules automatically upgrades coverage for Arabic messages. Removing them downgrades it — and the engine will start warning users that Arabic is not analyzed, rather than returning a false SAFE.
Regex portability (iOS)
Patterns ship to iOS via /v1/rules/pack and run under ICU (NSRegularExpression), not Python re. Stick to the common subset:
| Avoid | Use |
|---|---|
(?P<name>…) | (?<name>…) or plain groups |
\A / \Z | ^ / $ |
Possessive quantifiers a*+ | plain quantifiers |
\d inside character classes with Unicode intent | explicit ranges |
tests/test_mobile_api.py::test_rules_pack_patterns_are_valid_regex catches Python-side breakage; add ICU validation in the Swift RulesEngineTests.
Tuning weights
Do not tune by intuition on a single example. The review queue (GET /v1/review/queue) collects gray-zone verdicts with human labels — that is the intended feedback loop. Until a labeled evaluation set exists (see the release gate in safety-invariants.md), treat weight changes as hypotheses and always add a regression test for both the true positive you are fixing and a benign message that must stay safe.