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

FieldMeaning
weightAggregated with diminishing returns: 1 − Π(1 − wᵢ). Three 0.5 rules ≈ 0.875, never a naive sum.
severity: criticalSets a hard score floor of 0.85 that AI cannot lower. Use only for near-proof signals (OTP requests, remote-access demands).
localesRule 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.
channelsOptional. [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_patternsSuppresses 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:

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 scamsa pitch, not a discussion"Guaranteed returns? Sounds like a scam to me."
the same verb with an ordinary objectabout a windfall"Pay the delivery fee to the driver to receive your order"
the same nouns in the other directionasking you to give"I'll send you the gift card code — happy birthday"
the setup without the asksetup and a money request"Hi mum, new number, save it!"
an organisation doing its normal jobimpersonating 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:

WeightAloneUse for
≥ 0.85ScamDefinitive on its own: a code, a recovery phrase, gift-card codes, blackmail
0.75Be careful — "Likely" with any second signal, including urgencyA specific pattern you cannot fully rule out in genuine text
0.5 – 0.6Be carefulA signal that is common in scams and not rare elsewhere
≤ 0.35Nothing aloneSupporting 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:

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:

AvoidUse
(?P<name>…)(?<name>…) or plain groups
\A / \Z^ / $
Possessive quantifiers a*+plain quantifiers
\d inside character classes with Unicode intentexplicit 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.