> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-discovery-discovery/protection/bot-protection/common-fraud-detection-scenarios.md).

# Common Fraud Detection Scenarios

Detect common fraud patterns using custom entities and aggregation rule templates with thresholds, time windows, and actions

Fraud patterns rarely look suspicious at the level of a single request. A failed login, a password reset, a new account with a promo code, each is unremarkable on its own. The signal only becomes visible in aggregate, when you can see how many times something happened, and to whom. Traceable's **Custom Entities** and **Aggregation Rule Templates** are built to surface that signal. Together, they let you track application-specific data across your APIs and define the exact conditions under which that data indicates fraud.

## What you will learn from this topic

By the end of this topic, you will be able to:

* Create custom entities to extract and track business-specific values, such as passport numbers, beneficiary accounts, wallet IDs, and OTP destinations, across your APIs.
* Configure aggregation rule templates to group requests, apply thresholds within a defined time window, and detect suspicious patterns based on business-specific data.
* Specify actions for matching rules, such as generating alerts or blocking requests.
* Reuse a single custom entity across multiple aggregation rules to detect different fraud scenarios without recreating entity configurations.

***

## Why this matters

Fraud patterns are not always visible through conventional API security signals. A single request may appear legitimate, while repeated activity involving the same passport number, beneficiary account, or wallet ID may indicate fraudulent behavior.

Most API security platforms rely on generic signals, such as IP addresses, user agents, and request rates, and lack visibility into the business context of application payloads. Custom Entities and Aggregation Rule Templates bridge this gap in the following ways:

* **Business-specific detection:** Define detection logic around your application's data model, including passport fields, beneficiary relationships, and card tokens, rather than relying solely on generic traffic attributes.
* **Composable detection logic:** Reuse a single custom entity across multiple aggregation rules to introduce new fraud detection scenarios without rebuilding existing configurations.
* **Cross-request correlation:** Identify suspicious patterns by tracking business-specific values across requests and evaluating their frequency within a defined time window.
* **Targeted responses:** Configure actions such as generating alerts or blocking requests when defined aggregation conditions are met.

***

## Rule templates

Rule templates are the policy engine that acts on your Custom Entities. A Rule template defines a rule. For example, if a field, grouped by a dimension, exceeds a threshold of distinct or total values within a time window, Traceable triggers an alert or blocks the request. Every rule template consists of the following four attributes:

| Attribute              | Description                                                                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Target Field**       | The entity or attribute being measured, for example, *Card Details, Passport Number*, or *Beneficiary Bank Account.*                                                        |
| **Function**           | The aggregation method: `COUNT` for total occurrences, or `DISTINCT_COUNT` for unique values. `DISTINCT_COUNT` It is effective for detecting enumeration and mule patterns. |
| **Group By**           | The dimension that anchors the count, for example, is grouping by OTP Destination Mobile, so Traceable tracks how many distinct cards are seen per phone number.            |
| **Threshold + Window** | The trigger condition, for example, more than *5* distinct values in *24* hours. Traceable supports minutes, hours, and days as the window unit.                            |

***

## Fraud detection use cases

The following five use cases represent fraud patterns common across fintech, e-commerce, and digital services. Each is built using a combination of custom entities and Aggregation Rule Templates described above.

<details>

<summary>Credential stuffing</summary>

Attackers replay large lists of stolen username-password pairs against a login endpoint to identify valid credentials. Each individual attempt resembles a normal failed login. The signal that exposes the attack is the volume of distinct accounts targeted from a single origin. The following table discusses the attributes and description:

| Attribute    | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| **Endpoint** | `POST /api/auth/login`                                                                        |
| **Entity**   | Email Address: extracted from the request body field `email`.                                 |
| **Filter**   | HTTP Response Status equals `401`: counts only failed authentication attempts.                |
| **Rule**     | Group by IP Address, `DISTINCT_COUNT(Email Address) > 20` in 10 minutes.                      |
| **Trigger**  | One IP address attempts login against more than 20 distinct email accounts within 10 minutes. |
| **Severity** | High: block the IP address and alert the security team.                                       |

A legitimate user fails to log in once, at most a few times. A credential stuffing attempt cycles through a large number of distinct accounts from the same origin. `DISTINCT_COUNT` on the email field captures that breadth, where a standard rate limit would not.

</details>

<details>

<summary>Account takeover via password reset abuse</summary>

Attackers submit password reset requests for many accounts in rapid succession from the same device or IP address, either to determine which email addresses are registered (account enumeration) or to lock out legitimate users. The following table explains the attributes and its description:

| Attribute    | Description                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| **Endpoint** | *POST /api/auth/password-reset*                                                                        |
| **Entity**   | Email Address: extracted from the request body field.                                                  |
| **Filter**   | None required: all requests to this endpoint are in scope.                                             |
| **Rule**     | Group by IP Address, `DISTINCT_COUNT(Email Address) > 15` in 5 minutes.                                |
| **Trigger**  | One IP address submits password reset requests for more than 15 distinct email addresses in 5 minutes. |
| **Severity** | High: a strong signal of enumeration or targeted takeover; block and investigate.                      |

Password reset requires no credentials, which makes it a common target for enumeration. This rule uses *DISTINCT\_COUNT* to capture the breadth of accounts targeted, rather than overall request volume.

</details>

<details>

<summary>OTP and 2FA bypass via phone number farming</summary>

A single device or automated script requests one-time passwords (OTPs) for many different phone numbers, typically to identify registered numbers, harvest OTP windows for a SIM-swap attack, or exhaust OTP quotas. The following table explains the attributes and its description:

| Attribute    | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| **Endpoint** | *POST /api/otp/send*                                                                       |
| **Entity**   | Phone Number: extracted from the request body field *phone\_number*.                       |
| **Filter**   | None required: applies to all OTP send requests.                                           |
| **Rule**     | Group by Device Fingerprint, `DISTINCT_COUNT(Phone Number) > 5` in 15 minutes.             |
| **Trigger**  | One device fingerprint requests OTPs for more than 5 distinct phone numbers in 15 minutes. |
| **Severity** | Medium to High: block and alert; flag the device fingerprint for review.                   |

A legitimate user requests an OTP for their own number, typically once per session. Grouping by device fingerprint and measuring `DISTINCT_COUNT` on phone number surfaces a device cycling through a target list, a pattern that per-number rate limits do not catch.

</details>

<details>

<summary>Promo and bonus abuse</summary>

Fraudsters create multiple accounts from the same device or network to repeatedly claim sign-up bonuses, referral rewards, or promotional credits. Each account appears legitimate on its own; the shared device is the signal. The following table explains the attributes and its description:

| Attribute    | Description                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------- |
| **Endpoint** | *POST /api/users/register*                                                                  |
| **Entity**   | promo\_code: extracted from the request body field *promo\_code*.                           |
| **Filter**   | *promo\_code* is not null: scopes the rule to registrations that use a promotional offer.   |
| **Rule**     | Group by Device Fingerprint, `DISTINCT_COUNT(User ID) > 3` in 24 hours.                     |
| **Trigger**  | One device fingerprint creates more than 3 accounts claiming a promo within 24 hours.       |
| **Severity** | Medium: flag the accounts for manual review and withhold promo credit pending verification. |

A legitimate customer registers once per device. Grouping by device fingerprint and counting distinct *User IDs* identifies the multi-account pattern without affecting normal users.

</details>

<details>

<summary>Referral fraud</summary>

Fraudsters generate synthetic sign-ups using a single referral code to earn referral bonuses at scale. The referring account creates a network of accounts that trace back to a small pool of devices. The following table explains the attributes and its description:

| Attribute    | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| **Endpoint** | *POST /api/users/register*                                                                 |
| **Entity**   | referral\_code: extracted from the request body field *referral\_code*.                    |
| **Filter**   | *refferal\_code* is not null: scopes the rule to referred registrations only.              |
| **Rule**     | Group by Referral Code, `DISTINCT_COUNT(Device Fingerprint) > 5` in 24 hours.              |
| **Trigger**  | One referral code is used across more than 5 distinct device fingerprints within 24 hours. |
| **Severity** | Medium: suspend referral payouts and flag the referring account for review.                |

Organic referrals originate from genuinely different devices. Fabricated referrals trace back to a small, recycled pool of device fingerprints. `DISTINCT_COUNT` on device fingerprint, grouped by referral code, surfaces this pattern directly.

</details>

{% @harness-feedback/feedback %}
