scenario_forge

⚠️ This library generates controlled artificial (not real) anti-money-laundering scenarios for internal testing, model evaluation, and demos. Not intended for real transaction monitoring.

Overview

scenario_forge is a Python library for generating GOVERNED, ARTIFICIAL (NOT synthetic) crypto AML scenarios. This is not a generic synthetic data generator — it is a controlled adversarial scenario compiler designed for:

• Stress-testing AML models
• Demonstrating failure modes
• Educating analysts and regulators
• Model evaluation and benchmarking

Core Principles

• ✅ All data is artificial by design and explicitly labeled as such
• ✅ Every scenario has an INTENT (e.g., sanctions evasion, laundering, false positive trap)
• ✅ Every output includes provenance metadata and a cryptographic hash
• ✅ Outputs are graph-based (entities, transactions, timestamps)
• ✅ Outputs include human-readable narratives explaining the crime
• ✅ For demos and internal testing only, not production use

Installation

pip install -e .

Quick Start

from scenario_forge import cross_chain_laundering, generate_narrative, export_json

# Generate a scenario
scenario = cross_chain_laundering()

# Generate narrative
narrative = generate_narrative(scenario)
print(narrative)

# Export to JSON
export_json(scenario, Path("scenario.json"))

# Get risk summary
risk_summary = scenario.get_risk_summary()
print(f"Transactions: {risk_summary['total_transactions']}")
print(f"Integrity Hash: {scenario.scenario_hash}")

Example Usage

See examples/generate_scenario.py for a complete example:

python examples/generate_scenario.py

Architecture

Financial Primitives

• Wallet: Address, chain, jurisdiction, balance
• Transaction: From/to wallets, asset, amount, fee, timestamp
• Asset: Symbol, chain, decimals
• Chain: Name, chain_id, type (EVM, UTXO)
• Jurisdiction: Code, name, regulatory tier

Laundering Motifs

Reusable strategy classes that generate transaction subgraphs:

1. PeelChain: Chain of small transfers
2. CrossChainBridge: Cross-chain transfers via bridges
3. MixerObfuscation: Mixer service patterns
4. NFTWashTrading: Circular NFT trades
5. DormancyCooling: Time delays between phases
6. FalsePositiveTrap: Legitimate patterns that trigger false positives

Scenario Templates

5 hard-coded scenario templates:

1. cross_chain_laundering: Bridge + CEX exit
2. mixer_ransomware_liquidation: Mixer-based ransomware
3. sanctions_evasion_jurisdiction_hopping: Sanctions evasion
4. nft_wash_trading_extraction: NFT wash trading
5. false_positive_legitimate_pattern: False positive trap

Scenario Class

Each scenario includes:

• Scenario ID (UUID)
• Intent label
• Jurisdiction assumptions
• Motifs used
• Transaction graph (NetworkX)
• Entity roles
• Provenance metadata
• SHA-256 integrity hash

Export Formats

• JSON: Full scenario with graph, metadata, narrative
• CSV: Transaction table export
• Markdown: Human-readable narrative

All exports include:

• ARTIFICIAL_DATA_DO_NOT_USE_FOR_REAL_CASES warning
• Intent label
• Creation timestamp
• Scenario hash

Governance

Every export includes:

• ⚠️ ARTIFICIAL_DATA_DO_NOT_USE_FOR_REAL_CASES header
• Intent label
• Creation timestamp
• Scenario hash (SHA-256)
• Provenance metadata

Design Philosophy

• Demonstration clarity over surface area: Focused on 5 templates, 6 motifs, 3 exporters
• NetworkX internally, simple exports externally: Complex graphs internally, simple structures exported
• Hashlib SHA-256 with extension points: Simple hashing with room to grow
• No UI, no ML, minimal dependencies: Keep it simple but rigorous

Requirements

• Python >= 3.11
• networkx >= 3.0

License

Proprietary - GH Systems

Warning

⚠️ All data generated by this library is ARTIFICIAL and must be explicitly labeled as such. For internal testing, demos, and model evaluation only. Do not use for real cases or production monitoring.