ocsf

OCSF Fraud Extension

An Open Cybersecurity Schema Framework (OCSF) extension for detecting, investigating, and reporting internal and external fraud at banks and other financial institutions, worldwide.

It adds a Financial Activity category, five event classes, twelve objects, and two profiles, and extends core OCSF findings so that one fraud alert can carry:

• What happened: fraud type, mechanism, whether the account holder authorized it, and who played which role.
• How it was done: fraud tactics and techniques from MITRE’s Fight Fraud Framework (F3), plus banking-operations behaviors for insider fraud.
• How it is reported: the Basel operational risk loss event type, and classifications for each jurisdiction’s reporting regime.

Every field has a documented example, and every field appears in at least one validated example event.

Status: draft, version 0.1.0. The extension UID 983 is provisional until it is reserved in the OCSF extensions registry. F3 tactic and technique identifiers are left blank until they are copied from the official F3 matrix. The goal is to propose this to core OCSF; see docs/upstreaming.md.

Contact: fraud@evanrkinney.com

What’s in the schema

Event class	class_uid	Use it for
Transaction Activity	98330001	Payments and other movements of funds, from initiation to settlement, reversal, and dispute
Beneficiary Activity	98330002	Saved payees added, changed, removed, or verified
Account Maintenance Activity	98330003	Contact, address, limit, card issue, authorized user, and state changes
Staff Operation Activity	98330004	Employee fee waivers, journals, suspense postings, overrides, reactivations, trade amendments
Customer Record Access Activity	98330005	Employees viewing, searching, exporting, or printing customer records

Core OCSF classes the extension adds to:

• Detection Finding and Incident Finding get the fraud profile: fraud type, origin (internal, external, collusion), mechanism, is_authorized, involved parties, loss amounts, Basel classification, and regulatory classifications.
• Finding Information and Incident Finding get fraud_attacks for F3 and internal-behavior mappings, alongside the existing attacks for ATT&CK.
• Authentication and User Management get the fraud_signals profile: new device, SIM change, number port, line type, caller attestation, synthetic voice score, emulator, remote access, active call, pasted input.

Money is always integer minor units plus an ISO 4217 code (monetary_amount), never a float. Accounts and cards are tokenized; full numbers are never recorded.

Repository layout

schema/fraud/      The extension (same layout as OCSF platform extensions)
  extension.json   Name, UID, version
  categories.json  Financial Activity category
  dictionary.json  Every new attribute, each with a "For example" in its description
  events/          financial/ classes, plus additions to core findings/ and iam/ classes
  objects/         New objects, plus an addition to core finding_info
  profiles/        fraud and fraud_signals
mappings/          F3 tactics, internal behaviors, fraud type to Basel, EU payment fraud statistics
examples/          Nine scenarios as sequences of OCSF events (31 events), from informational
                   alerts closed as benign to critical incidents with large losses
tools/             check.sh and the Python tools it runs
viewer/            Source of the fraud-only schema viewer
docs/              Design notes and the path into core OCSF

Run the checks

You need Python 3.14 or later (the OCSF compiler requires it) and Git.

python3 -m pip install ocsf-schema-compiler ocsf-validator
tools/check.sh

check.sh clones core OCSF 1.9.0 into .core/ on first run, then:

1. validates the extension against the OCSF metaschema,
2. compiles core plus the extension to build/schema.json,
3. checks captions and descriptions against the OCSF style rules,
4. validates every example event and confirms every extension field appears in one,
5. builds the viewer to site/fraud/index.html.

To test against another core version: OCSF_REF=main tools/check.sh (delete .core/ first), or point OCSF_CORE at an existing checkout. CI runs the same script against 1.9.0 and core main.

The viewer

site/fraud/index.html is one self-contained page (data embedded, no server needed) that shows only the fraud extension: classes with their activities and type_uid values, objects, profiles, the changes to core classes, the mappings, and the example scenarios. Every attribute shows its example, and links to an example event where it appears. Open the file in a browser, or publish the site/ folder to any static host; the page works from any path, such as /fraud/.

Example scenarios

Scenario	What it shows
External account takeover	SIM change, new-device logon, factor swap, new payee, instant transfer held
Authorized payment scam	Customer pays during a scammer’s call; finding updated later with recovery and reimbursement
Voice-channel takeover	Unsigned, ported, synthetic-sounding caller gets a virtual card and limit raise; gift card purchase blocked
Insider-enabled collusion	Leaving employee reactivates a dormant account by self-approved override; account drained abroad
Internal fee reversals	Teller supervisor refunds fees to a relative; statistical outlier finding

License

Apache License 2.0, the same license as OCSF. See LICENSE.