Risk Scores Explained

Assessment output#

| Field | Meaning | | --- | --- | | riskScore | Composite value from 0 to 100. | | recommendedAction | Threshold-based engine recommendation. | | action | Final action after policy mode and safety floors. | | riskLevel | low, medium, high, or critical. | | reasonCodes | Machine-readable evidence and availability markers. | | featureContributions | Diagnostic signal values for this engine version. |

Signals and weights#

| Signal | Weight | Examples | | --- | ---: | --- | | Graph | 35% | Shared indicators and fraud-neighbour topology. | | Velocity | 25% | Bursts and activity spikes. | | Similarity | 15% | Overlap with threat indicators. | | Contextual | 25% | Geography, card, device, amount, and profile mismatch. |

Weights may change with the engine version. Integrate against response fields rather than reproducing the formula.

Levels and actions#

| Risk level | Usual score band | | --- | ---: | | low | 0–30 | | medium | 31–60 | | high | 61–85 | | critical | 86–100 |

Policy thresholds determine allow, review, or block; configured floors can raise the final action. In advisory or shadow, action may remain allow while recommendedAction records the threshold result. See Policy Modes.

Reason codes#

| Group | Codes | | --- | --- | | Threat and graph | GLOBAL_INDICATOR_MATCH, BLACKLIST_OVERLAP_HIGH, ONE_HOP_GUARD_TRIGGERED | | Velocity | VELOCITY_ZSCORE_SPIKE | | Unavailable signals | GRAPH_UNAVAILABLE, REDIS_UNAVAILABLE, BLOOM_UNAVAILABLE, GDS_SCORES_UNAVAILABLE, ML_INFERENCE_UNAVAILABLE, CONTEXTUAL_UNAVAILABLE | | Policy | POLICY_MODE_ADVISORY, POLICY_MODE_SHADOW |

Reason codes explain which evidence or safeguards fired. Automate the workflow using action; retain the other fields for review and audit.

Feature contributions#

Common keys include:

• velocity_zscore
• indicator_overlap_ratio
• graph_neighbor_ratio_n2
• graph_global_penalty
• contextual_score
• ml_fraud_probability
• knn_fraud_similarity

These keys support observability and investigation and can evolve between engine versions.

Partial-signal decisions#

When a dependency is unavailable, VertexY uses remaining signals where possible, adds the corresponding reason code, and applies the configured degradedMinAction. Provide stable identifiers, contextual fields, complete lifecycle events, and confirmed feedback to improve available evidence.