diff --git a/src/content/docs/bots/account-abuse-protection.mdx b/src/content/docs/bots/account-abuse-protection.mdx index 9a531dffad3..492d9ac6335 100644 --- a/src/content/docs/bots/account-abuse-protection.mdx +++ b/src/content/docs/bots/account-abuse-protection.mdx @@ -1,11 +1,12 @@ --- pcx_content_type: Concept title: Account Abuse Protection (Early Access) -description: Detect and block automated abuse on login and registration endpoints. +description: Detect and investigate account abuse on login and registration endpoints. products: - bots tags: - Account takeover + - Fake account creation sidebar: order: 8 label: Account Abuse Protection @@ -22,6 +23,8 @@ import { Render, Description, DashButton, Steps } from "~/components"; Account abuse — bulk account creation and account takeover attacks — can cause financial losses and erode user trust. Fraud detection allows you to detect and mitigate these attacks among your traffic. You can use fraud signals to [update or create new rules](/waf/custom-rules/) for suspicious account activity, or pass signals to your origin to integrate into authentication and authorization systems. +--- + ## Availability Account Abuse Protection is available in Early Access for any [Bot Management Enterprise](/bots/get-started/bot-management) customer. You can use these features at no additional cost for a limited period until they are generally available. @@ -34,7 +37,9 @@ Contact your Cloudflare account team to request access. ### User ID -User ID is a cryptographically hashed, per-zone identifier that customers can use in [Security Analytics](/waf/analytics/security-analytics/), [Security Rules](/waf/custom-rules/), and [Managed Transforms](/rules/transform/managed-transforms/reference/). Hashed User IDs are created by encrypting the primary credentials your users provide, converting them into opaque identifiers unique to your zone. This allows traffic analysis while protecting user privacy. With access to hashed User ID, website owners can: +User ID is a cryptographically hashed, per-zone identifier that customers can use in [Security Analytics](/waf/analytics/security-analytics/), [Security Rules](/waf/custom-rules/), and [Managed Transforms](/rules/transform/managed-transforms/reference/). Hashed User IDs are created by encrypting the primary credentials your users provide, converting them into opaque identifiers unique to your zone. This allows traffic analysis while protecting user privacy. + +Each login or sign up adds the event to that account's history, along with the network and device signals Cloudflare observes at the edge. Over time, this history shows what normal activity looks like for the account, so meaningful changes are easier to spot. With access to hashed User ID, website owners can: - Review which users have the most activity on your website. - Find the details on a specific user's characteristics and activity patterns. @@ -43,9 +48,15 @@ User ID is a cryptographically hashed, per-zone identifier that customers can us - Manage network patterns or signals associated with specific users. :::note[Data privacy] -User profiling was created with privacy in mind. Its design and engineering align with our privacy and compliance programs and contain technical controls that protect the privacy of users. Hashed User IDs are created by encrypting the primary credentials your users use to access your applications. +User ID was created with privacy in mind. Its design and engineering align with our privacy and compliance programs and contain technical controls that protect the privacy of users. Hashed User IDs are created by encrypting the primary credentials your users use to access your applications, such as an email address, username, or phone number. Other Cloudflare customers cannot access your user profiles. They are unique to your zone. + +**Roles** + +The **Account Abuse Protection** role grants fraud teams access to the dashboard. The **Account Abuse Protection PII** role also grants access to account-level personally identifiable information (PII), such as associated email addresses. Only team members with the **Account Abuse Protection PII** role can create or edit Logpush jobs that include PII. Team members without either role cannot access the Account Abuse Protection dashboard. + +To assign either role, in the Cloudflare dashboard, go to **Manage Account** > **Members** and select **Invite Members**. Under **Permission policies**, select **Add a policy**. ::: User ID is an opt-in feature that can be enabled in Security Settings. @@ -57,11 +68,28 @@ To enable, edit, or disable the setting: -2. Filter by **Fraud**. +2. Go to the **Fraud** section. 3. Go to **User ID**. 4. Turn **User ID** on or off. +### AI assistants + +Some users ask AI assistants to log in or sign up on their behalf. When Cloudflare recognizes the assistant that made a login or sign up request, Account Abuse Protection records which assistant it was against that account's Hashed User ID. This lets site owners and fraud teams see which account each assistant acts for. + +- **Population overview:** View which AI assistants are active across your users and how many accounts use them. +- **AI assistant filters:** Filter accounts by number of AI assistant events or number of AI assistants. +- **Individual account overview:** View the assistants that acted for a single account, the number of events, and its overall behavior. + +You can use this to: + +- **Act on one account.** If an assistant's activity on one account looks suspicious, investigate and mitigate that account without blocking the assistant for everyone else who relies on it. +- **Tune your agent policies with evidence.** Use what you see for each assistant to set per-agent access in [AI Crawler and Agent access policies](/bots/additional-configurations/block-ai-bots/). + +:::note +AI assistant visibility covers login and sign up events only. Requests from assistants that Cloudflare does not recognize appear as ordinary traffic. +::: + ### Ephemeral IDs Customers using Cloudflare [Turnstile](/turnstile/) can utilize ephemeral IDs for Fraud detection. @@ -86,25 +114,59 @@ Account takeover (ATO) detections are not available for accounts using the [Data Fraud detection requires the following configurations and settings to be enabled to properly identify suspicious behavior. -#### Security Settings +#### Security settings + +Turn on **User ID** and tell Cloudflare where the user's identifier, such as an email address or username, appears in each login and sign up request. + +| Request format | Example username location | +| ---------------- | ------------------------------------------------------- | +| URL-encoded form | `url_decode(http.request.body.form["username"][0])` | +| JSON body | `lookup_json_string(http.request.body.raw, "username")` | +| Query parameter | `http.request.uri.args["username"][0]` | -- User ID: Cloudflare encrypts or hashes your user IDs to better understand typical user traffic patterns across your applications. Enabling Cloudflare to create hashed user ID mappings to your users will allow you to receive account takeover and bulk account creation detections. +Use the field name that your application sends in place of `username`. Supported expressions can use request body, header, and query fields with [`lookup_json_string()`](/ruleset-engine/rules-language/functions/#lookup_json_string) and [`url_decode()`](/ruleset-engine/rules-language/functions/#url_decode). -#### Eligible traffic +Cloudflare hashes this value to create a Hashed User ID for each account. Requests without the identifier are not linked to an account. -Cloudflare automatically identifies certain login and sign up traffic on your applications and runs these detections without any additional configurations. +If your endpoints do not return `2XX` status codes for success and `4XX` for failure, configure custom success and failure criteria so Cloudflare records each outcome correctly. -- Sign-ups: Cloudflare automatically monitors traffic on endpoints that match common sign up endpoints. +#### Verify the User ID configuration + +After traffic reaches your labeled login or sign-up endpoints, go to **Security** > **Account Abuse Protection** and confirm that accounts appear in the dashboard. Data may not appear immediately. + +| Result | Recommended action | +| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| Accounts and activity appear | The User ID configuration is working. | +| Events appear, but accounts do not | Verify that the username location expression matches the account identifier in the request. | +| No events or accounts appear | Verify your assigned role, endpoint labels, selected date range, and whether traffic has reached the configured endpoints. | + +#### Label login and sign-up endpoints + +Cloudflare automatically identifies certain login and sign-up traffic on your applications and runs these detections without any additional configurations. + +- Sign-ups: Cloudflare automatically monitors traffic on endpoints that match common sign-up endpoints. - Login: Cloudflare automatically monitors traffic on endpoints that match common login endpoints. -Verify that your endpoints are properly labeled to ensure Cloudflare can detect and monitor them correctly. +To verify endpoint labels, go to **Security** > **Web Assets** > **Endpoints** and confirm that login endpoints have the `cf-log-in` label and sign-up endpoints have the `cf-sign-up` label. :::caution[Login or sign up endpoints] -Not all login or signup endpoints are automatically detected. +Not all login or sign-up endpoints are automatically detected. -Cloudflare evaluates and automatically detects your website or application's login or sign up endpoint, but non-traditional login or sign up endpoints may not be recognized. +Cloudflare evaluates and automatically detects your website or application's login or sign-up endpoint, but non-traditional login or sign-up endpoints may not be recognized. For example, if you have a non-traditional login endpoint, you should label it with `cf-log-in` using the [endpoint labeling service](/api-shield/management-and-monitoring/endpoint-labels/). Once you have applied the `cf-log-in` label, Cloudflare will use the labeled endpoint for account takeover detection decisions. + +To manually label a login or sign-up endpoint: + + +1. In the Cloudflare dashboard, go to **Security** > **Web Assets** > **Endpoints**. +2. Find your login or sign-up endpoint and select **Edit endpoint labels**. +3. Under **Managed labels**, select the appropriate label: + - For login endpoints, select `cf-log-in`. + - For sign-up endpoints, select `cf-sign-up`. +4. Select **Save labels**. + + ::: :::tip[Enhanced with leaked credential detections] @@ -113,17 +175,71 @@ Cloudflare also recommends enabling [Leaked credentials detection](/waf/detectio --- -### Detections +## Analytics dashboard + +The dashboard is organized as an investigative funnel. Start with your whole account population, narrow down to the accounts that need review, then investigate each one. + +### Population overview + +The population overview summarizes login and sign up activity on your zone for a selected time range: + +- Total events, unique accounts, unique IPs, and unique devices. +- Events over time, split into login and sign up, with the share of events made by AI assistants. +- AI assistant events: which known assistants made login and sign up requests, how many events each made, and across how many accounts. +- Top countries and top ASNs by events. +- Leaked credential checks: how many events had a leaked username and password, a leaked username, a leaked password, or clean credentials. + +The **Accounts** table lists each Hashed User ID with its total events, AI assistant events, leaked credential events, unique IPs, top country, and top IP. Use filters to narrow the list for investigation. + +### Individual account overview + +Selecting a Hashed User ID from the **Accounts** table opens its individual account summary and detailed activity log. + +- **Account overview:** A summary of the account's login and sign up activity, its login success rate, leaked credential matches, and the networks, locations, and devices most often seen with a specific user. +- **AI assistants:** The assistants that acted for this account, with the number of events and event types for each. +- **Activity log:** Every event for the account, with its timestamp, Ray ID, event type, AI assistant (if any), location, network, device, and any mitigation applied. Filter the log by AI assistant to review one assistant's activity. + +Use the Ray ID to look up the full request in Security Events. + +When reviewing an account, consider: + +- Was this a single event or part of a series of repeated attempts? +- Did a login introduce a new country, network, IP address, device, or AI assistant? +- What happened before and after the suspicious event? +- Did a burst of logins follow shortly after sign up, from different networks or devices? + +### Respond to an account + +If your review confirms that an account was compromised or is abusive: + +- Start your own recovery or enforcement process for the account. +- Select **Mitigate account** to create a Security Rule for its Hashed User ID, or create the rule manually with `cf.fraud.user_profile.id` equal to the impacted Hashed User ID. Choose _Managed Challenge_ to add friction, or _Block_ to stop the account's requests. Only this account is affected, including when it uses an AI assistant that other users rely on. + +### Security Analytics + +You can also filter [Security Analytics](/waf/analytics/security-analytics/) by User ID to review requests for a single account. To review AI assistant traffic across all requests on your zone, not only logins and sign ups, select **Personal assistants** in **Bot analysis**. + + + +Fraud fields can be used as filters to identify suspicious patterns in your traffic. + +--- + +## Detections Fraud detections focus on account abuse attacks such as account takeover, bulk account creation, and credential quality. These detections run on all eligible traffic and can be used across [Cloudflare Rules](/rules/) to log, challenge, and/or block requests to your sign up and login endpoints. -#### Account creation +### Bulk account creation + +Bulk account creation detection identifies patterns that indicate automated or repeated creation of fake accounts. Detection runs on account-creation endpoints labeled with `cf-sign-up`. + +### Account creation Disposable Email Checks detect when users sign up with throwaway email addresses commonly used for promotion abuse and fake account creation. These disposable email services allow attackers to create thousands of unique accounts without maintaining real infrastructure. You can use `cf.fraud_detection.disposable_email` to block disposable emails or issue a [challenge](/cloudflare-challenges/challenge-types/) to anyone attempting to create an account with a disposable email. -#### Suspicious emails +### Suspicious emails Cloudflare checks email domains used during sign up against lists of known temporary or disposable email services. Cloudflare runs the same check on login requests when the extracted username is an email address. @@ -136,11 +252,11 @@ This check also determines the value of `cf.fraud.email_risk` in Security Rules --- -### Mitigations +## Mitigations The following Fraud detection fields can be used in Security Rules to help identify and mitigate suspicious traffic. -#### Security Rules +### Security Rules The following fields can be used in new and existing Security Rules. @@ -148,25 +264,48 @@ The following fields can be used in new and existing Security Rules. | ------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `cf.fraud_detection.disposable_email` | Flags whether a domain for a given email is included in a known list of temporary email providers. | `True` or `False` | | `cf.fraud.email_risk` | Indicates whether Cloudflare identifies an email domain as temporary or disposable. | `high` when Cloudflare identifies the domain as temporary or disposable.
`unknown` otherwise. | +| `cf.fraud.detection_ids` | Contains the IDs of fraud detections that matched the request. | For bulk account creation, use `201326594`, `201326595`, `201326596`, or `201326597`. | +| `cf.fraud.user_profile.id` | The Hashed User ID for the request. | String of hashed user IDs. | -#### Other rules +### Other rules You can use Fraud detection data in Request Header [Transform Rules](/rules/transform/managed-transforms/) to pass information down to the origin. -#### LogPush +### Logpush -You can add Fraud detection fields to existing or new [LogPush](/logs/logpush/) jobs. +You can add Fraud detection fields to existing or new [Logpush](/logs/logpush/) jobs. --- -## Analytics +## Troubleshooting -You can find Fraud data and detections in Security Analytics, where you can see top User IDs. +### Account Abuse Protection is not visible - +- Confirm that the team member has the **Account Abuse Protection** or **Account Abuse Protection PII** role. +- Confirm that Account Abuse Protection Early Access is enabled for the account. Contact your Cloudflare account team if you need access. -Fraud fields can be used as filters to identify suspicious patterns in your traffic. +### The dashboard has no data + +- Confirm that the selected date range contains login or sign-up activity. +- Confirm that traffic has reached the configured endpoints since Account Abuse Protection was enabled. Historical traffic is not backfilled. +- Go to **Security** > **Web Assets** > **Endpoints** and verify that login endpoints have the `cf-log-in` label and sign-up endpoints have the `cf-sign-up` label. + +### Events appear, but accounts do not + +Verify that the username location expression matches the account identifier in an actual request. Requests without the configured identifier are not associated with a Hashed User ID. + +### Login outcomes are incorrect + +Verify the configured success and failure criteria. By default, successful requests should return `2XX` response codes and failed requests should return `4XX` response codes. + +If an application returns a successful response code for a failed login, configure custom criteria so Cloudflare records the outcome correctly. + +### Personally identifiable information is hidden + +Confirm that the team member has the **Account Abuse Protection PII** role. The base **Account Abuse Protection** role does not grant access to account-level personally identifiable information. -The hashed User ID field within Security Analytics also provides Fraud customers with data that can help review detections and patterns per individual users rather than requests. You can review user level aggregations for IPs and IP counts, event types (login or sign up), locations, devices, and browsers. +### Leaked credential results show **Not checked** -A user level profile also provides a quick way to review the latest events associated with a user so that you can identify any anomalies and create a custom rule to log, block, or challenge that user. +- Confirm that leaked credentials detection is turned on for the zone. +- Verify that Cloudflare can extract the credentials from the configured request locations. +- Confirm that the request is within the supported detection scope.