ezrules blog

How fraudsters prepare their attack infrastructure

2026-07-02T00:00:00Z

In this blog post we will look at how fraudsters prepare infrastructure for a fraud attack and what you can do today to be better prepared. For professional scammers, not opportunists, defrauding a financial institution is a highly sophisticated operation. As the defences of companies become more sophisticated, so do the fraudsters.

What fraudsters are trying to manufacture

The goal is not just to get one transaction through. The goal is to make an account, a payment method, or a set of identities look ordinary enough that the first serious fraud attempt is not treated as the first suspicious event. Fraudsters are trying to manufacture age, activity, verification, and distance from known bad behaviour.

Normally, preparing attack infrastructure includes, but is not limited to:

buying stolen card details (aka fullz)
buying or renting accounts with the targeted companies (e.g. TapTapSend, or WorldRemit)
potentially buying stolen identities for account verification
making several small transactions

How trust is built before the attack

While buying stolen card details is done mostly for payment facilitation, the other steps are about building up trust with the companies. Any fraud detection system at any payment company looks at how long the user has been known to the company - one way or another. There are multiple angles this can be assessed from. The first and most obvious one is how long the user has been on the books.

There is often increased attention and separate checks for new accounts or accounts making their first ever transaction. That means buying older accounts is preferable to opening new ones, which is why there is a large market for older accounts with payment companies. Not just that, but people often voluntarily advertise those accounts for sale/rent.

Buying stolen identities can be an important step in preparing fraud infrastructure. This is mostly done to open new accounts and immediately verify them with a stolen ID. In many markets ID verification is not mandatory and is often considered a "safety" signal by the companies. However, since the competition between remittance companies is fierce, they tend to lower barriers to transactions and ID verification is introduced only in the markets with high fraud rates and/or strict regulations.

With any sort of account, especially with new ones, fraudsters tend to make a few small transactions. This works because they know that payment companies are overly suspicious of dormant accounts that suddenly start transacting large amounts. Small transactions are cheap probes. They test whether the account, card, recipient, device, and behavioural pattern can pass through controls. They also create recent benign-looking history, which can weaken simple dormancy and velocity rules if those rules are not designed carefully.

Small transactions like this reset companies' internal aggregation features (amount sent last 3 days, number of transactions last X days, etc), thus lowering the probability of such accounts being flagged.

So to sum it up, an ideal account for a fraud attack is an old account that was verified by the previous owner and either has recent transaction history, or a recent history created with small transactions performed with a stolen card.

What can you do to help yourself?

Firstly, treat new customers with a stricter set of rules and/or separate ML models. There are a lot of conversations about how the customer mass should be sliced for analysis and control. My experience is that separating first/non-first time transacting customers is often enough and a good first step.

Secondly, make sure that among the features/fields you check on a transaction the dormancy-related features are present. Make sure you track the cadence and frequency of transactions, as well as how much time has passed since the last transaction. A dormant account that suddenly starts moving money is not the same as an account with a stable recent history, even if the last transaction amount is the same.

Do not overweight the verification flag. It is not foolproof. When analysing your machine learning models, make sure to do counterfactual analysis to see how the prediction changes when the flag is flipped. If you see a dramatic score drop - this might be a bad signal and needs readjusting. Verification should help you understand the customer, not suppress every other signal.

Use the customer graph

There is also one specific method that I found extremely useful in the past: look at the evolution of the customer graph. Count connected components and track the size of the largest one. If it spikes - alert, pay attention to the market slice where it appears.

Let's get into a bit more detail here. Imagine a graph where nodes are transactions and their details. For example, a transaction with id1 is related to this phone number and that card hash, as well as this name and that town. Now look at the last 90 days in a market slice, pull all the data available for that slice and build that graph.

The next step is to calculate connected components - isolated segments of the graph that share some details in common. What you are looking for is connected components that are relatively large compared to the market size. Say, if the CC size you normally see in that market is 5 and you see 50 - that's your first clue to investigate it. It means that a lot of transactions share a lot of details in common: same card hashes, same phone numbers, same names, same devices, same recipients, or other repeated details.

For example, imagine 40 accounts that look unrelated at the account level. When you build the graph, you discover that they share 3 card hashes, 6 phone numbers, 2 device fingerprints, and a repeating set of recipients. None of those links may be decisive alone. Together, they start to look like infrastructure.

It might be a false positive, of course. Some large connected components are normal: families, shared devices, agents, payroll flows, or community patterns can all create legitimate connections. The useful signal is usually the combination of size, growth rate, newness, market context, and the type of shared identifiers.

However, one large connected component means nothing on its own - you want its temporal dynamics. So what you do is rewind your data back in time and start building the same connected components as of one week ago, 6 days ago, 5 days ago, etc, until today. If a component is persistent and keeps growing in size - it has every chance of being a coordinated fraud attack. Dig into it. This is the infrastructure we talked about - bought card details are shared between accounts, same phone numbers can be used for verification, etc.

Spot the preparation, not just the spike

The main idea is simple: fraud infrastructure often appears before the fraud spike. If you only look at individual transactions, you may see normal-looking activity. If you look at how accounts, cards, phones, identities, recipients, and devices connect over time, the preparation phase becomes much easier to spot.

This is also the kind of problem ezrules is built for: turning those observations into testable rules, graph-derived signals, and investigation workflows that fraud teams can adjust quickly when the pattern changes.

Graph-Based Event Investigation in ezrules

2026-06-14T00:00:00Z

Fraud investigations rarely stop at one transaction.

A single event can look suspicious because of its own fields: high amount, fresh device, risky merchant category, unusual geography, or a burst of recent declines. But many of the most useful signals are relational:

the same card appearing across several users
a device reused by unrelated accounts
a merchant cluster tied to repeated chargebacks
an email domain connecting a burst of new accounts
a customer identity touching many payment instruments

Those relationships are hard to see when every event is inspected as an isolated JSON payload. ezrules now supports graph-backed investigation from Tested Events and graph-derived rule features for production evaluation.

What the graph represents

The graph is built from configured entity fields. Each stored event is linked to entity values extracted from its payload, such as:

customer_id
customer.id
sender.id
merchant_id
email_domain
card_fingerprint
device_id

When two events share the same configured entity value, they become connected through that entity. The graph view renders this as event nodes connected to entity nodes.

This means an analyst can start from one served decision and immediately see nearby traffic connected through shared operational identities.

Why this is useful during review

Without a graph, an analyst reviewing one event has to manually search for related activity. They might copy a card fingerprint, filter historical events, inspect another transaction, copy a device id, and repeat the process.

The event graph makes the first pass faster:

open a Tested Events row
click Show graph
inspect related events up to the configured event and hop limits
click entity nodes to expand additional nearby relationships

The graph is intentionally bounded. By default it opens with nearby relationships up to three event-to-event hops, and the max event limit prevents broad clusters from overwhelming the browser.

How rule execution uses graph data

The investigation graph is not only a visual aid. The same stored event-to-entity links support graph-derived computed stats in rule logic.

For example:

if stat[user.unique_cards_graph_90d] >= 2:
    return !HOLD

At evaluation time, ezrules resolves stat[...] before executing the rule. A graph feature starts from an entity in the current event, traverses historical event-to-entity links within the configured time window and depth, and returns a bounded aggregate such as a distinct count of target entities.

That makes relationship-aware rules possible without embedding graph traversal logic in every rule.

Keeping graph features bounded

Graph traversal can grow quickly in production traffic, so graph features include guardrails:

allowed time windows
allowed entity types
max traversal depth
max expanded node count
active-feature lifecycle controls
statement timeout protection

The goal is to support useful connected-event signals while keeping rule execution predictable.

A practical fraud example

Consider an event where customer_id = cust_00013.

In isolation, the payload might show:

a card-not-present checkout
a risky merchant category
a disposable email domain
elevated velocity

The graph can show that the same customer, email domain, merchant category, or other configured entity also appears in nearby events. That gives the reviewer immediate context: this may be part of a broader cluster rather than a one-off transaction.

For rules, a graph feature can turn that cluster context into a policy signal. Instead of only checking this event's fields, a rule can ask whether the current user has connected to too many cards, devices, or merchants in the configured window.

When to use graph investigation

Graph investigation is especially useful for:

card testing bursts
synthetic identity clusters
account takeover patterns
mule-account networks
merchant abuse
repeated disposable-email activity

It is less useful for events that are genuinely isolated or for rules where the decision depends only on event-local fields.

What to configure carefully

The quality of graph results depends on the configured entity fields.

If an entity field is not configured, ezrules will not materialize links for it. If historical events were stored before a field was configured, those older events need link backfill before they appear in graph traversal.

Useful graph fields are stable identifiers with operational meaning. Avoid low-cardinality fields that connect too much traffic, such as country or currency, unless the feature is deliberately designed around broad groups.

Good candidates include:

customer ids
account ids
device ids
card fingerprints
merchant ids
email domains
beneficiary ids

The graph should reveal meaningful relationships, not turn every event into the same giant component.

From Zero to Live Rule Evaluation in 10 Minutes with ezrules

2026-05-05T00:00:00Z

This is the fastest path to prove value with ezrules: create one rule, send one real event, and see a decision come back from the live evaluator.

If you already finished Installation, this walkthrough is designed to take about 10 minutes.

Teams often have a familiar problem: fraud and compliance logic takes too long to validate because rule authoring, API behavior, and analyst tooling are disconnected. You can spend days debating rule ideas before seeing a real decision in a live path.

This guide focuses on a single outcome: prove the full workflow quickly. In one short run, you will create a rule in the UI, evaluate an event through /api/v2/evaluate, and confirm the decision path is working end to end. That gives you a concrete artifact for demos, internal buy-in, and faster iteration.

Minute 0-2: Start the stack

docker compose up -d
uv run ezrules api --port 8888

In a second terminal:

cd ezrules/frontend
npm install
npm start

Quick checks:

API health: http://localhost:8888/ping
Frontend login page: http://localhost:4200

Minute 2-5: Create your first decision rule

Log in at http://localhost:4200.
Open Rules and create a new rule with this logic:

if $amount > 10000:
    return !HOLD

Open Outcomes and add HOLD if it is not there yet.

Fresh installs start with an empty outcomes catalog, so creating the first outcome is part of the setup.

Minute 5-7: Send a live event to the evaluator

Authenticate first (for example via POST /api/v2/auth/login) and then call the evaluator endpoint:

curl -X POST http://localhost:8888/api/v2/evaluate \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_live_001",
    "effective_at": 1700000000,
    "event_data": {
      "amount": 15000,
      "user_id": "user_42"
    }
  }'

You should get JSON with:

rule_results
outcome_counters
outcome_set (should include HOLD)

Minute 7-9: Validate in the UI

Open Dashboard to confirm transaction activity.
Open the rule detail page and use Test Rule to try a low amount (for example, 500) and compare results.

Use the 30-day Dashboard window for demos so the chart shows the traffic shape clearly, then zoom into the rule's own test panel for the concrete decision result.

After the live call, the Tested Events view gives analysts the concrete event record, outcome, and highlighted payload fields that explain why the rule fired.

Minute 9-10: Tune and rerun

Change the threshold, save, and call /api/v2/evaluate again. This quick edit-test-evaluate loop is the core workflow teams use to iterate on fraud and compliance logic without redeploying application code.

Why this 10-minute flow matters

You validate the full path: UI authoring -> stored rule config -> live evaluator response.
You show both analyst and engineering workflows in one short demo.
You have a concrete artifact to share in release notes, demos, and onboarding.

Next Steps

Rule Lifecycle Management in ezrules: Draft, Promote, Pause, Roll Back, Archive with Audit Trail

2026-04-30T00:00:00Z

Rule engines usually fail at one of two extremes:

Every edit is live immediately, which is fast but risky.
Every edit requires an external process, which is safe but slow.

ezrules now supports an explicit lifecycle so teams can move fast without losing control: draft -> active -> paused -> active or archived, with lifecycle events captured in the audit trail and rollback available when a historical revision needs to be restored as a new draft.

Why lifecycle controls matter

If a rule change can go live directly from an edit, then you can accidentally ship unreviewed logic. If a rule change requires manual coordination outside the system, then iteration slows down and people work around process.

The useful middle ground is to separate:

rule authoring (draft)
rule deployment (active)
temporary operational disablement (paused)
retirement (archived)

This gives you cleaner change control and a clear operational state for every rule.

What is now stored per rule

Each rule now includes lifecycle metadata:

status: draft, active, paused, or archived
effective_from: when the active version became effective
approved_by: user id recorded when the current rule version was activated or reactivated
approved_at: timestamp recorded when the current rule version was activated

There is no separate approval workflow. The approved_* field names are kept for API compatibility and refer to promote, resume, or auto-promote actions. The audit trail exposes lifecycle transitions as event-log rows: action, actor, timestamp, and status transition.

API behavior by lifecycle

The lifecycle is enforced by API behavior:

POST /api/v2/rules creates a draft rule
PUT /api/v2/rules/{id} saves edits as draft and clears previous activation metadata by default
POST /api/v2/rules/{id}/rollback restores a historical revision's logic and description into a brand new draft
POST /api/v2/rules/{id}/promote moves draft to active and records the activation actor + timestamp
POST /api/v2/rules/{id}/pause moves active to paused without archiving the rule and requires a dedicated pause permission
POST /api/v2/rules/{id}/resume moves paused back to active
POST /api/v2/rules/{id}/archive moves a rule to archived
DELETE /api/v2/rules/{id} deletes the rule (requires DELETE_RULE)

Production evaluation config now includes only active rules.

An org can opt into auto_promote_active_rule_updates through the runtime settings API or Settings → General. When that setting is enabled, editing an already active rule keeps it active and rewrites the production config immediately, but the caller still needs PROMOTE_RULES in addition to MODIFY_RULE.

flowchart LR
    A[Create rule] --> B[draft]
    B --> C[Edit rule]
    C --> B
    B --> D[Promote]
    D --> E[active]
    E --> F[Pause]
    F --> G[paused]
    G --> H[Resume]
    H --> E
    E --> I[Edit or detect issue]
    I --> J[Rollback to prior revision]
    J --> B
    E --> K[Archive]
    G --> K
    K --> L[archived]

In the rule list, the lifecycle state stays visible next to the rule, alongside the actions that are available for that state.

Promotion is a first-class activation step

Promotion is no longer an implicit side effect of editing. It is an explicit operation that records:

who activated the rule
when it was activated
when it became effective

That gives you a defensible trail for internal governance and external audits, while keeping authoring fast for rule editors.

Pause is not archive

Pausing is useful when a rule should stop affecting live outcomes right now, but you expect to reuse it.

paused rules are excluded from production config
the rule can be resumed later without recreating it
teams can distinguish "temporarily off" from "retired"

Use pause when you want a reversible operational stop. Use archive when the rule is retired.

Archive is not delete

Archiving is useful when you need to retire a rule but keep full context.

archived rules are no longer active in production config
historical versions and metadata remain available
teams can distinguish "no longer used" from "removed forever"

Use delete when you intentionally want permanent removal. Use archive when you want operational retirement with history intact.

Rollback is not history deletion

Rollback does not rewind the database in place and it does not remove newer revisions.

the selected historical revision remains in history
the current revision remains in history
rollback creates a new draft version using the older logic and description
the rollback action itself is recorded in audit history

This is the safer operational model: you recover known-good logic quickly without destroying evidence of what changed.

Example: promote and archive

# Roll back rule 42 to revision 3 (creates a new draft)
curl -X POST http://localhost:8888/api/v2/rules/42/rollback \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"revision_number": 3}'

# Promote draft rule 42
curl -X POST http://localhost:8888/api/v2/rules/42/promote \
  -H "Authorization: Bearer <access_token>"

# Pause rule 42
curl -X POST http://localhost:8888/api/v2/rules/42/pause \
  -H "Authorization: Bearer <access_token>"

# Resume rule 42
curl -X POST http://localhost:8888/api/v2/rules/42/resume \
  -H "Authorization: Bearer <access_token>"

# Archive rule 42
curl -X POST http://localhost:8888/api/v2/rules/42/archive \
  -H "Authorization: Bearer <access_token>"

How this fits with shadow deployment

Lifecycle and shadow solve different concerns:

Lifecycle controls whether a rule is draft, active, paused, or archived in production management flow.
Shadow deployment validates candidate behavior on live traffic before promotion.

A practical sequence is:

Edit rule in draft
(Optional) deploy to shadow for live validation
Roll back to a known-good revision if a newer draft or active version proves wrong
Promote when ready to activate
Archive when rule is retired

Net effect

You get a cleaner rule lifecycle without adding operational friction:

safer releases through explicit promotion
faster recovery through auditable rollback
auditable activation trail
clear operational state in UI and API
predictable retirement path through archive

Related docs:

AI-Assisted Rule Authoring in ezrules: Generate Transaction Monitoring Rules from Natural Language

2026-04-30T00:00:00Z

Writing transaction-monitoring rules is usually a mix of policy thinking and syntax work.

An analyst knows the behavior they want to detect:

large transfers from risky destinations
activity from disposable email domains
repeated proxy-heavy transactions from low-trust devices

But getting that intent into a valid rule still takes time:

finding the right fields
remembering list names
using the correct outcome syntax
checking whether the draft logic actually compiles

ezrules now adds AI-assisted rule authoring directly inside the existing rule editor so teams can move from natural-language intent to a reviewable draft faster.

What AI rule authoring does

The AI assistant is built into the normal rule create and rule edit workflows.

A user can describe the rule they want in plain English, and ezrules will:

generate a draft in native ezrules rule syntax
validate the generated logic
attempt bounded repair for obvious issues
explain the generated rule line by line
show a diff against the current rule when editing
offer a manual backtest action for valid edit-mode drafts
require an explicit copy step into the real editor before save

This is important: the assistant does not auto-save and does not auto-activate anything.

The generated output is a draft preview until the user explicitly copies it into the main rule editor.

Why this matters for fraud and compliance teams

Most rule authoring friction is not about business logic. It is about translation.

A fraud analyst might want to say:

Hold high-value wire transfers from newer accounts when the beneficiary is in a sanctioned country.

The system already knows:

which fields have been observed
which user lists exist
which outcomes are configured
whether the rule is in the main lane or allowlist lane

AI-assisted authoring closes the gap between those two layers.

Instead of starting from a blank editor, the analyst starts from a generated draft that already uses ezrules-native concepts such as:

$amount
$customer.account.age_days
@SanctionedCountries
!HOLD

That shortens time-to-first-draft without creating a second rule language that has to be translated back into the engine.

The review flow is intentionally explicit

The safest part of the feature is not the generation. It is the review flow around generation.

The assistant now makes the generated draft easier to inspect before it affects the real rule body.

1. Validation and repair happen before the user copies anything

Generated rules are checked against the same validation path used by the rule API.

That means the preview can surface:

syntax errors
missing or invalid outcomes
warnings about referenced fields
lane-specific constraints

The assistant can also attempt bounded repair before handing the draft back to the user.

2. The draft is visually separated from the real editor

The generated rule appears in a dedicated preview block, not silently inside the actual editable rule body.

This avoids the common problem where an AI suggestion looks authoritative even though it has not been reviewed yet.

3. A diff shows exactly what changed

When editing an existing rule, the assistant can show a char-level diff against the current editor content.

That matters because many useful AI edits are small:

adding one more condition
changing one threshold
swapping one outcome

Char-level diff makes those edits easier to inspect than a full-line replacement view.

4. A line-by-line explainer is available when needed

The assistant also produces a line-by-line explanation of the generated draft.

This is useful when a reviewer wants to understand:

what each branch is doing
which condition maps to which business idea
whether the generated logic matches the original analyst request

5. Manual backtests show likely impact before save

When a valid draft is generated while editing an existing rule, ezrules shows a Run Backtest action under the proposed logic change.

The action uses the same Backtest Results section as the rest of the rule detail page. It compares the stored rule and proposed draft before the user copies or saves anything, and shows:

outcome distribution deltas between the stored and proposed logic
skipped-record counts and missing-field warnings
label-aware precision, recall, and F1 when historical labels exist

This keeps the expensive comparison user-triggered while preserving the normal save, promote, rollout, and shadow workflows.

6. Copy into the main editor is a deliberate action

The preview becomes real rule content only when the user chooses:

Use Draft In Main Editor

Until then, the normal Save/Create actions are still tied to the main rule editor, not the AI preview.

That keeps the human-in-the-loop and makes the authoring step auditable and reviewable.

What context the assistant uses

AI rule authoring is not a generic chatbot prompt box. It uses ezrules-specific context from the organisation.

The current implementation can include:

observed fields
configured field types
user lists
configured outcomes
lane constraints
neutral outcome rules for allowlist behavior
the current rule body and description when editing

That makes the generated output much more likely to fit the actual rule engine than a generic model prompt would.

OpenAI-backed settings in the product

ezrules also adds AI configuration to the Settings page.

An organisation can now:

enable or disable AI rule authoring
select the OpenAI provider
choose the model
manage the provider API key

At the moment, the product UI intentionally supports OpenAI only.

That keeps the first release simple while preserving a backend shape that can support additional providers later.

A practical example

Imagine an existing rule:

if $amount > 500 and $email_domain in @DisposableEmailDomains:
    return !HOLD
else:
    return !RELEASE

An analyst may want to tighten it with one more requirement, such as email age.

Instead of manually editing and rechecking syntax, they can ask the assistant for that change and review:

whether the threshold logic is still correct
whether only the intended condition changed
whether the new draft preserved the right outcome behavior

That is exactly the kind of small-but-risky authoring step where AI can help without replacing human judgment.

What this feature is not

AI rule authoring in ezrules is not:

automatic promotion
automatic activation
a separate no-code rule engine
a replacement for analyst review

It is a drafting accelerator on top of the existing expert editor.

That distinction matters. In transaction monitoring, the problem is rarely “how do we let the model decide?” It is usually “how do we get from intent to a reviewable draft faster without weakening controls?”

Final thought

The most useful AI features in compliance and fraud tooling are usually the ones that remove mechanical work while keeping responsibility clear.

AI-assisted rule authoring in ezrules does exactly that:

faster rule drafting
native engine syntax
explicit validation
visual review aids
human acceptance before save

That is a much better fit for production transaction monitoring than a fully automatic rule-writing workflow.

Related docs:

Shipping Rule Changes with Less Guesswork: Shadow Deployment in ezrules

2026-04-24T00:00:00Z

There's a gap between "this rule passes tests" and "this rule is safe to ship." Closing that gap is what shadow deployment is for.

The problem with deploying rule changes

You write a new version of a rule. You test it with realistic payloads and the logic is correct. You backtest it against stored historical events and the numbers look acceptable. Then you ship it and find out fairly quickly that production traffic was different from what you expected — a field arriving as a string instead of an integer, a traffic spike at a time you didn't have good historical coverage for, a new upstream product generating a pattern your backtest window didn't include.

This is not primarily a testing problem. Backtesting is genuinely useful: it tells you how a rule would have performed on a defined historical window, which helps you calibrate thresholds and catch logic errors before they touch anything real. But a historical window is fixed. Your traffic today might differ from three months ago in ways that matter — seasonal patterns, data quality shifts from upstream systems, new transaction types entering the mix. A backtest from Q3 is a reasonable but imperfect proxy for Q1.

What you actually want to know is: how does this rule behave on current traffic, with current data, at current volumes?

What shadow mode does

When you deploy a rule to shadow, it evaluates every incoming event alongside the production rule set. The same payload goes through both. Production results are returned to the caller as normal. Shadow results are stored in a separate table and never returned.

From the caller's perspective, nothing has changed. From your perspective, you're accumulating a real distribution of how the candidate rule would have answered every question the production system received, starting from the moment you deployed it.

There is no traffic splitting, no separate service to deploy, no routing configuration. You hit the Deploy to Shadow button (or the API equivalent), and from that point forward every event is evaluated against the shadow config in parallel with production.

The Shadow Rules page shows the candidate rule, its current shadow status, and the live comparison surface operators use before promotion.

flowchart LR
    A[Incoming event] --> B[POST /api/v2/evaluate]
    B --> C[Production rules]
    B --> D[Shadow rules]
    C --> E[Response to caller]
    D --> F[(shadow_results_log)]

What the comparison tells you

The stats endpoint (GET /api/v2/shadow/stats) shows outcome distributions for each shadow rule alongside the production outcomes for the same events. If you're tightening a threshold — a rule that should fire more often than the current version — you expect more HOLD decisions in the shadow column than in the production column. If they're close, your change has less bite than you expected. If they diverge significantly, you know the magnitude before it matters.

This doesn't tell you whether the decisions would have been correct, only how different they are from current production behavior. Whether that difference is acceptable is a judgment call that depends on your situation. But you're making that call with data from today's traffic rather than from a historical window that may or may not be representative.

The draft-logic path

One workflow that comes up often: you want to test a logic change in shadow without committing it to the rules table first. The deploy endpoint accepts optional logic and description fields. If you provide them, they're stored in the shadow config and the rules table stays unchanged.

If you decide the change is wrong after observing the shadow results, you remove it. Nothing was written to production. If it looks right, you promote: the rules table updates to the shadow logic, the production config updates, and the shadow entry is cleared in one atomic operation.

This matters for iteration speed. You can go through several candidate versions of a rule — deploy to shadow, watch the distribution, decide it's off, adjust, re-deploy — without any of those intermediate versions touching production. The only version that ever enters the production config is the one you decided to promote.

flowchart LR
    A[Candidate logic] -->|deploy to shadow| B[Shadow config]
    B -->|traffic accumulates| C[shadow_results_log]
    C --> D{Stats look right?}
    D -->|yes| E[Promote → production]
    D -->|no| F[Remove → nothing written]

Backtesting and shadow are complementary

Backtesting and shadow deployment answer different questions and the useful pattern is to use both.

Backtest before you have a candidate ready. It's good for initial calibration: does this threshold make sense on historical data, are there edge cases in the stored event set, is the logic handling the patterns it's supposed to handle? This is where you rule out obviously bad ideas.

Shadow after you have a candidate ready. It's good for validation on current traffic: is the production impact what I expected, are there patterns in live data that weren't well represented in the historical window? This is where you build confidence before promoting.

Neither tool tells you what the other does. Backtesting has no access to live traffic. Shadow has no access to historical events. A rule that passes both gives you substantially more confidence than one that only passed one.

A few things shadow doesn't do

Shadow results aren't labeled. You can see how often the shadow rule returns each outcome and compare that to production for the same events, but you don't automatically know whether those shadow decisions would have been correct against ground truth. If you have labeled data covering the shadow period, you can cross-reference manually, but that's not built in.

Shadow evaluation is best-effort. If the shadow evaluation for an event fails — a missing field, a type error, anything that raises an exception — the error is silenced and that event isn't stored in the shadow results. The production evaluation is unaffected. This means the shadow results may have gaps, and if the rule has bugs that only surface on certain payload shapes, those events are undercounted rather than surfaced as errors. Worth checking result counts against total event volume if completeness matters to you.

Stats reset when you re-deploy the same rule to shadow. If you update the draft logic and push a new version, the existing results are cleared. You start accumulating again from zero. This is intentional — stale results from a previous candidate version aren't meaningful for evaluating the current one — but it's worth knowing if you're expecting continuous accumulation across logic changes.

The net effect

Shadow deployment narrows the gap between "the backtest looked acceptable" and "I'm confident this is right." It doesn't eliminate judgment, but it moves the validation point from historical data to current traffic, which is where the rule will actually run.

Full docs: Shadow Deployment guide

Rule Quality in ezrules: Precision and Recall by Outcome-Label Pair

2026-04-24T00:00:00Z

Teams usually know which rules fire often. The harder part is knowing whether those rules are right.

In ezrules v0.19, the new Rule Quality view makes that explicit by comparing rule outcomes against ground-truth labels.

The practical problem

Rules return outcomes like HOLD, RELEASE, CANCEL. Labels are business ground truth like FRAUD, NORMAL, CHARGEBACK.

Those vocabularies are intentionally separate, so quality analysis must evaluate pairs:

HOLD -> FRAUD
RELEASE -> NORMAL
CANCEL -> CHARGEBACK

Each pair can have different precision/recall behavior.

Before ranking rules, analysts can confirm that labels are flowing over a useful window in Analytics.

What the page shows

Open Rule Quality from the sidebar.

You get:

Best Rules: highest average F1 (across valid outcome→label pairs)
Needs Attention: lowest average F1
Pair Metrics Table for every rule, including:
- precision
- recall
- F1
- TP / FP / FN
- predicted positives / actual positives

This helps analysts answer:

Which rules are over-flagging (low precision)?
Which rules are missing confirmed cases (low recall)?
Which mapping actually represents this rule best?

Support filtering matters

Low-volume pairs can create noisy rankings. The page includes a Min support filter.

Under the hood, this maps to:

GET /api/v2/analytics/rule-quality?min_support=<n>

Raise the threshold when you want stable operational ranking; lower it for exploratory analysis.

Configured outcome-label pairs keep the report focused on mappings the team actually reviews.

Feeding data quickly: bombardment fraud labels

The bombardment script now supports in-line labeling of a small random percentage of evaluated events:

uv run python scripts/bombard_evaluator.py \
  --api-key <api_key> \
  --token <access_token> \
  --fraud-rate 0.01

That gives you continuous traffic plus a trickle of labeled events for quality monitoring, without waiting for manual CSV uploads.

Operational workflow

Run traffic (live or bombardment).
Label events (manual, CSV, or bombardment rate).
Open Rule Quality and rank by F1.
Inspect low-scoring pairs and decide whether to adjust rule logic or mapping assumptions.

For API details, see Manager API reference.

Ordered Rule Execution in ezrules: When First Match Beats Conflict Resolution

2026-04-24T00:00:00Z

Most rule engines start with one simple idea: run every active rule, collect every outcome, and then resolve conflicts at the end.

That works well when:

you want broad signal collection
multiple rules are allowed to fire on the same event
the final decision should come from a severity hierarchy

It starts to break down when the business intent is really procedural:

run the strongest allow or deny rule first
stop once you already know the answer
make the ordering itself part of the policy

ezrules now supports that second model for the main rule lane through ordered execution and a first_match mode.

When ordered execution is useful

Ordered execution is useful when the rule set is really a sequence, not a bag of independent checks.

Common cases:

Progressive screening: early rules handle obvious or high-confidence cases, and later rules are fallback checks.
Short-circuit decisions: once one rule returns the intended outcome, running more rules only adds noise.
Policy precedence: some rules should win because they represent stricter or more authoritative business intent.
Operational clarity: analysts need to know not just which rules exist, but which one gets first shot.

In those cases, "run everything and resolve later" can be misleading. The severity hierarchy still gives you a winner, but it does not reflect the procedural order people actually intended.

What ezrules now supports

For the main rule lane, ezrules supports two execution modes:

all_matches
first_match

all_matches is the legacy behavior:

every active main rule is evaluated
all non-null outcomes are collected
the platform resolves the stored resolved_outcome from the configured outcome hierarchy

first_match changes that:

active main rules are evaluated in explicit order
evaluation stops at the first main rule that returns an outcome
only that matching rule is persisted for the served result

The allowlist lane still keeps its own behavior:

allowlist runs before the main lane
if an allowlist rule matches, the main lane is skipped
allowlist is still governed by the configured neutral outcome

So the feature is specifically about how the main rule lane behaves once allowlist did not short-circuit the request.

How operators use it

The operator flow is now:

Go to Settings -> General
Set Main rule execution mode to Stop on first match
Go to Rules
Click Reorder Rules
Use:
- ↑ to move a rule earlier
- ↓ to move a rule later
- # to jump a rule to an exact position
Click Save Order

When first-match mode is not enabled, the ordering UI is intentionally hidden:

no Order column
no Reorder Rules button
no inline position controls

That is deliberate. The product only shows ordering controls when ordering actually changes live execution semantics.

Why the controls live on the Rules page

The first implementation exposed an exact numeric order on individual rule edit screens. That turned out to be the wrong mental model.

Ordering is not really a property of one rule in isolation. It is a property of the whole main rule set.

To make that clearer, ezrules now groups rule-order controls in one place:

the Rules list page shows the visible sequence
button-based reordering and exact-position entry both live there
create and edit screens no longer ask authors to manage absolute position numbers in isolation

That keeps the UI closer to the actual question operators are answering:

"Where should this rule sit relative to the other main rules?"

How ezrules implements it

At the data model level, each rule stores:

evaluation_lane
execution_order
status

Only non-archived main rules participate in the reorder workflow.

When the platform rebuilds the production rule config for the main lane, it sorts by:

execution_order
r_id as a deterministic tie-breaker

The runtime setting main_rule_execution_mode controls whether the evaluator:

runs the full ordered list and collects all matches, or
stops on the first matching main rule

That same execution mode is also snapshotted into the shadow-evaluation queue payload so replay stays consistent with the semantics that were active when the event was actually served.

What gets audited

Reordering is not just a UI shuffle. It is recorded.

ezrules now includes:

a dedicated reorder_rules permission
reorder actions stored in rule history with action=\"reordered\"
execution_order included in the rule audit response

That matters because ordered execution changes live decision behavior. If order is a production control surface, it needs the same governance and traceability as promotion, pause, or rollback.

What this does not change

This feature does not turn the whole platform into a single sequential pipeline.

It does not change:

allowlist-first precedence
outcome hierarchy semantics for all_matches
backtesting into a full multi-rule sequential simulator

Backtesting in ezrules is still primarily rule-centric. Ordered serving is about the live main-lane evaluator path.

Practical guidance

Use all_matches when:

you want broad observability across the rule set
you care about every triggered rule
the severity hierarchy is the right final arbiter

Use first_match when:

the rule set is intentionally procedural
precedence matters more than aggregate conflict resolution
later rules should only run if earlier rules did not already decide the case

If your team debates whether a rule should be "more severe" or "earlier", that is a sign you are choosing between two different policy models:

severity hierarchy answers "which outcome wins if several rules fire?"
ordered execution answers "which rule gets to decide first?"

ezrules now supports both models explicitly.

Related docs:

Automatic Field Type Management

2026-04-24T00:00:00Z

JSON doesn't have a strong type system. An amount field might arrive as 15000 in one event and "15000" in the next, depending on the source system. When a rule does $amount > 10000, the result depends entirely on which one shows up — and string comparison produces different ordering than numeric comparison. "9999" > "10000" is True lexicographically. That's backwards.

The usual fix is to cast inside the rule:

if int($amount) > 10000:
    return !HOLD

Which works until the next person writes a rule without the cast. Now you have inconsistent behavior across the rule set with no easy way to audit it.

ezrules v0.12 handles this at the engine level.

How it works

Every event that passes through /api/v2/evaluate is observed. For each field in the payload, we record the JSON type Python saw — int, float, str, bool. The same happens in the Test Rule panel, so observations build up during development without needing live traffic.

The observations show up under Settings → Field Types:

amount    int
amount    str

Two rows for amount means it arrived with two different types. That's a data quality signal worth investigating, but you don't have to wait — configure amount as float and both variants are handled correctly from that point on.

From the same page, click Configure next to any observation, pick the type, save. For datetime fields you also provide a format string (%Y-%m-%dT%H:%M:%S), and the value will be parsed into a proper datetime object before rules run.

After that, the rule stays as written:

if $amount > 10000:
    return !HOLD

The comparison is always numeric. No casts inside rules, no special handling per field.

If a value can't be cast — say amount is "not-applicable" and the configured type is float — evaluation returns a 400 with the specific field and value that failed. That's better than a silent wrong answer.

What this doesn't do

It doesn't fix upstream data quality. If your source sends malformed values you'll find out faster (hard failure rather than incorrect evaluation), but you still have to fix the source.

It's also not a replacement for schema validation at ingestion if you need that. The scope here is making rule comparisons correct without requiring every rule author to remember casting.

Audit trail

Every field type configuration change is recorded — who changed it, when, and what the previous value was. If amount gets changed from integer to float and evaluation behavior shifts, you can trace it directly. Available at GET /api/v2/audit/field-types or in the Audit Trail page under Field Type History.

Full docs

Field Type Management guide

Why Complex Entities Matter in a Fraud Rules Engine

2026-04-24T00:00:00Z

Fraud systems rarely evaluate one flat record with a handful of fields.

Real transaction monitoring usually involves related entities:

the customer
the sender
the device
the merchant
the beneficiary
the payment instrument

Those entities often have their own attributes and sub-attributes:

customer.profile.age
customer.behavior.avg_amount_30d
sender.origin.country
sender.device.trust_score

If a fraud rules engine forces all of that into one flat namespace, the rule layer becomes harder to read, harder to maintain, and easier to break.

ezrules now supports canonical dotted nested paths in rule logic, test payloads, observations, backtesting, and the Tested Events UI. That makes it possible to model transactions as collections of related fraud entities instead of flattening everything into one long list of loosely related keys.

The practical problem with flat fraud payloads

Flattening looks simple at first:

{
  "customer_country": "US",
  "sender_country": "BR",
  "sender_device_trust_score": 18,
  "customer_profile_age": 34
}

But as a fraud program grows, flat naming starts to work against you:

field names get long and inconsistent
two teams may flatten the same concept differently
related attributes lose their grouping
the payload stops looking like the real business object it represents
rule authors have to remember naming conventions instead of business meaning

That matters because fraud rules are not just technical filters. They are operational policy.

If an analyst reads a rule, they should be able to see the entity model immediately.

What complex entities look like in fraud monitoring

A more natural event model keeps related attributes together:

{
  "amount": 875.5,
  "currency": "USD",
  "customer": {
    "id": "cust_00042",
    "country": "US",
    "profile": {
      "age": 34,
      "segment": "established"
    },
    "behavior": {
      "avg_amount_30d": 140.0,
      "std_amount_30d": 30.0
    }
  },
  "sender": {
    "id": "cust_00042",
    "country": "US",
    "origin": {
      "country": "BR"
    },
    "device": {
      "trust_score": 18,
      "age_days": 1
    }
  }
}

That structure mirrors how fraud teams actually think about an event:

who is transacting
from where
on what device
against what baseline

Rules become easier to read because the entity model is visible in the syntax itself.

Why this is useful in rule authoring

With nested-path support, an ezrules author can now write:

if $customer.profile.age >= 21 and $sender.device.trust_score <= 35 and $sender.origin.country != $customer.country:
    return !HOLD

That is easier to reason about than a flat equivalent such as:

if $customer_profile_age >= 21 and $sender_device_trust_score <= 35 and $sender_origin_country != $customer_country:
    return !HOLD

The dotted version communicates:

which fields belong to the customer entity
which fields belong to the sender entity
which nested attributes are part of profile, behavior, origin, or device

In fraud detection work, this matters because many rules are about relationships across entities, not just thresholds on isolated fields.

Common fraud use cases for nested entities

Nested entity modeling is especially useful for:

Cross-entity mismatch checks

if $sender.origin.country != $customer.country:
    return !HOLD

This is clearer than comparing two flattened country fields with ambiguous prefixes.

Device risk inside a sender context

if $sender.device.trust_score <= 20 and $amount >= 500:
    return !HOLD

The device is explicitly part of the sender entity rather than a standalone global field.

Customer baseline logic

if $customer.behavior.std_amount_30d > 0:
    zscore = ($amount - $customer.behavior.avg_amount_30d) / $customer.behavior.std_amount_30d
    if zscore >= 3:
        return !HOLD

This keeps behavioral baselines grouped under the customer rather than spread across unrelated top-level names.

Mixed entity and top-level features

if $txn_type == "card_purchase" and $customer.profile.segment == "new" and $sender.device.age_days <= 1:
    return !HOLD

That kind of rule is common in transaction monitoring: some signals are transaction-level, some are customer-level, and some belong to the sender or device context.

Why this helps operational teams, not just engineers

Nested entities are not only a schema preference. They improve day-to-day fraud operations.

1. Rules read more like policy

Analysts and fraud managers often review rule logic directly. Dotted paths make it easier to see what a rule is actually saying.

2. Event schemas stay closer to source systems

Many payment and case-management systems already expose nested objects. Preserving that shape avoids translation layers that create drift between the source event and the rule event.

3. It reduces naming collisions

Fields such as country, id, or age are common across entities. Nested paths make the scope explicit.

4. It improves investigation workflows

When an event is stored and reviewed later, the entity grouping still exists. That makes it easier to inspect what happened and why a rule fired.

What ezrules now supports around nested paths

This is not just parser-level syntax support. ezrules now handles canonical dotted paths across the full rule workflow:

rule logic can reference nested fields such as $customer.profile.age
missing nested fields produce path-aware errors
field observations record canonical dotted paths
field type configuration can target dotted paths
the Test Rule panel pre-fills nested JSON objects for nested params
backtesting applies the same nested-path normalization and eligibility logic
the Tested Events page highlights nested referenced fields inside the JSON payload

That end-to-end consistency matters. It is not enough to let authors type nested paths if every downstream tool still assumes flat fields.

Why this matters for fraud detection quality

Fraud rules often degrade when the event model is too lossy.

A flat payload tends to encourage:

duplicated concepts
weaker naming discipline
rules that reference the wrong field because two similar fields look interchangeable

A more structured entity model makes it easier to write rules against the right concept and to explain why a rule fired.

That can reduce false positives caused by ambiguous field mapping, especially when several related countries, ids, or behavioral features exist in one event.

A useful middle ground

This does not mean every fraud event needs to become a deeply nested document.

A useful middle ground is:

keep core transaction attributes at the top level when they truly are event-wide
group entity-specific attributes under the entity they belong to
use nested paths where the grouping carries operational meaning

For example:

top-level: amount, currency, txn_type
nested: customer.profile.*, customer.behavior.*, sender.origin.*, sender.device.*

That gives rule authors the clarity of a structured model without making every rule overly verbose.

Final point

Fraud rules engines are not just evaluating values. They are evaluating relationships between entities.

As soon as the rule set starts asking questions like:

"Is the sender origin different from the customer country?"
"Is this device low-trust for this sender?"
"Is the amount abnormal for this customer's baseline?"

you are already reasoning about complex entities.

At that point, the event model should help you, not hide the structure.

Nested-path support in ezrules is useful because it lets the fraud event look more like the fraud problem.

Related docs: