Skip to content

About

Synthetic identity-fraud ring generator plus shared-attribute linking detection (union-find). Pure Python, no dependencies.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

24 Commits

Folders and files

Repository files navigation

fraud-rings

Open In Colab

Synthetic identity-fraud ring generator plus graph-based detection, all in pure Python, no dependencies.

Real fraud rings hide in plain sight: a dozen "different" applicants who share two devices, recycle phone numbers, live at cosmetic variants of one address, and use SSNs that differ by a single digit. fraud-rings lets you generate that pattern synthetically and detect it with shared-attribute linking plus union-find connected components: the workhorse technique behind production entity-resolution pipelines.

Disclaimer: every entity in this repo is synthetic. Names, SSNs, phones, addresses, and device IDs are randomly generated and bear no relation to real people. Nothing here touches real PII.

Quickstart

python examples/quickstart.py

Or as a library:

from fraud_rings import RingGenerator, find_rings, evaluate

entities = RingGenerator(seed=42).generate(n=500, n_rings=3)
clusters = find_rings(entities)

for c in clusters:
    print(c.size, c.evidence)   # size + shared-attribute evidence

print(evaluate(entities, clusters).summary())

How detection works

  1. Link (fraud_rings/detection.py::link_entities): entities get an edge when they share a device_id, phone, a normalized address, or a near-duplicate SSN (Hamming distance ≤ 1, found via 8-of-9 digit mask buckets so it stays O(n)). Address matching ignores street-type spelling ("Ave" = "Avenue") and treats a missing unit as a variant of the same address, but never links two different units in one building (see below).
  2. Cluster (find_rings): union-find connected components over those edges, each returned with its shared-attribute evidence (shared device x4, near-duplicate SSN x9, …). Evidence is accumulated once per linked pair, rather than rescanning all edges for each component. This keeps many separate small rings from multiplying the evidence work; dense shared-attribute buckets can still produce quadratically many edges.
  3. Score (evaluate): precision/recall against the planted labels, plus how many planted rings were recovered (≥50% of members in one cluster).

Address normalization

Exact vs normalized address matching on rings that share only address variants

Rings often reuse one address with cosmetic changes. link_entities compares addresses after lowercasing, stripping punctuation and reducing street types ("Street" to "St"), then applies three rules:

Pair Result
same street, same unit (or both without one) shared address
same street, one side has no unit, building has exactly one known unit address variant
same street, one side has no unit, two or more known units no link (it could be any of them)
same street, two different units no link

These rules keep neighbours in an apartment building apart, including through a unitless record: it never chains two units together. The price is recall. On the demo data (rings that share only address variants, seed 42), 2 of 3 rings are recovered and recall is 0.70, versus 0/3 and 0.61 with exact matching; the ring whose variants span several units stays split. Pass normalize_addresses=False to link_entities or find_rings for the old exact-match behaviour. Regenerate the figure with python examples/plot_rings.py (needs matplotlib).

Temporal burst detection

Real rings spray applications in a tight window before going quiet. Every generated entity now carries an applied_at timestamp. Benign traffic spread uniformly over 90 days, ring members clustered inside a 2-hour burst. detect_bursts() runs a two-pointer sliding window (4h default, ≥6 applications) and merges overlapping hits.

It's a recall-oriented tripwire, not a verdict. Exactly how velocity rules work in production: the burst routes to review, attribute linking decides. See examples/burst_example.py for an adversarial ring with fully unique attributes per member: linking finds nothing, the burst catches all 8.

from fraud_rings import RingGenerator, detect_bursts

entities = RingGenerator(seed=42).generate(n=500, n_rings=3)
for b in detect_bursts(entities):
    print(b.summary())

Roadmap

  • Temporal burst detection (many applications in a short window)
  • Louvain community detection for rings that share weak signals across many attributes
  • GNN-based ring scorer (GraphSAGE over the entity graph)
  • Larger, noisier attribute pools + adversarial ring variants that dodge naive linking

Tests

python3 -m pytest tests/ -q

Part of a fraud-ML series

  • GNN Fraud Ring Detection - GraphSAGE, GAT, GCN, GIN and LSTM from scratch in pure Python (zero dependencies) for fraud ring detection
  • Agentic Fraud Investigator - A multi-agent fraud investigation system in pure Python, zero dependencies.
  • ID-document-forgery-detection-CV- - Classic image forensics for ID-document forgery detection, written from scratch in pure Python, zero dependencies.
  • Time-series-anomaly-detection - Time-series anomaly detection, including collective anomalies
  • fraud-eval - Open benchmark for evaluating LLM-based fraud and abuse detectors (20-case smoke test, cost-aware metrics, counterfactual evaluation)

About

Synthetic identity-fraud ring generator plus shared-attribute linking detection (union-find). Pure Python, no dependencies.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages