This page explains how to interpret a score to understand the level of risk thatuser interactions pose, and take appropriate actions for yoursite.
reCAPTCHA Enterprise returns a score for each request based on the interactionswith your site, regardless of the key type. After you receive the score fromreCAPTCHA Enterprise, you must interpret the score and take appropriate actionsfor your site.
Before you begin
Create an assessment for your website.
Interpret the assessment
After your backend submits a user's reCAPTCHAresponse token to reCAPTCHA Enterprise, you receive an assessment as a JSONresponse as shown in the following example.
To interpret an assessment, consider the following parameters:
valid: indicates whether the provided user response token is valid. Whenvalid = false, the reason is specified ininvalidReason.valid = falsecan also indicate that a user has failed to solve a challenge or there is asiteKeymismatch.invalidReason: Reason associated with the response whenvalid = false.action: a user interaction that triggered reCAPTCHA Enterprise verification.expectedAction: the expected action from a user that you specifiedwhen creating the assessment.score: level of risk the user interaction poses.reasons: additional information about how reCAPTCHA Enterprise hasinterpreted the user interaction.{ "event":{ "expectedAction":"EXPECTED_ACTION", "hashedAccountId":"ACCOUNT_ID", "siteKey":"KEY_ID", "token":"TOKEN", "userAgent":"(USER-PROVIDED STRING)", "userIpAddress":"USER_PROVIDED_IP_ADDRESS" }, "name":"ASSESSMENT_ID", "riskAnalysis":{ "reasons":[], "score":"SCORE" }, "tokenProperties":{ "action":"USER_INTERACTION", "createTime":"TIMESTAMP", "hostname":"HOSTNAME", "invalidReason":"(ENUM)", "valid":(BOOLEAN) }}
Verify actions
The JSON response contains the action parameter that you specified for auser interaction when calling execute() and the expectedAction parameterthat you specified when creating the assessment.
Verify that action matches the expectedAction.For example, a login action should be returned on your login page.If there is a mismatch, it indicates that an attacker is attempting to falsifyactions. You can take actions against the user interaction, such as addingadditional verifications or blocking the interaction to prevent anyfraudulent activities.
Interpret scores
The scoring system of reCAPTCHA Enterprise is an expansion from priorversions of reCAPTCHA to allow greater granularity in responses.reCAPTCHA Enterprise has 11 levels for scores with values ranging from0.0 to 1.0. The score 1.0 indicates that the interaction poses low risk andis very likely legitimate, whereas 0.0 indicates that the interaction poseshigh risk and might be fraudulent.Out of the 11 levels, only the following four score levels are available bydefault: 0.1, 0.3, 0.7 and 0.9.
All 11 score levels are accessible after a security review. To request access to11 score levels, contact our sales team.
reCAPTCHA Enterprise learns by monitoring real traffic on your site.Therefore, scores in a staging environment and within 7 days ofimplementation might differ from the long-term production scores.
If you installed score-based keys, you can first runreCAPTCHA Enterprise without taking action and then decide on thresholds bylooking at the traffic.
Based on the score, you can take an appropriate action in the context of yoursite. To protect your site better, we recommend that you take the action in thebackground instead of blocking traffic.
The following table lists some of the actions you might take:
| Use case | Action |
|---|---|
| homepage | See a cohesive view of your traffic on the admin console while filtering scrapers. |
| login | With low scores, require MFA or email verification to prevent credential stuffing attacks. |
| social | Limit unanswered friend requests from abusive users and send risky comments to moderation. |
| e-commerce | Put your real sales ahead of bots and identify risky transactions. |
Reason codes
Reason codes are available after a security review. To request access to reasoncodes, contact our sales team.
Some scores might be returned with reason codes that provide additionalinformation about how reCAPTCHA Enterprise interpreted the interactions.
The following table lists the reason codes and their descriptions:
| Reason code | Description |
|---|---|
| AUTOMATION | The interaction matches the behavior of an automated agent. |
| UNEXPECTED_ENVIRONMENT | The event originated from an illegitimate environment. |
| TOO_MUCH_TRAFFIC | Traffic volume from the event source is higher than normal. |
| UNEXPECTED_USAGE_PATTERNS | The interaction with your site was significantly different from expected patterns. |
| LOW_CONFIDENCE_SCORE | Too little traffic was received from this site to generate quality risk analysis. |
What's next
- To tune your site-specific model, you can send the assessment IDs back to Googleto confirm true positives and true negatives, or correct errors.For details, see Annotate assessments.
I'm a seasoned expert in web security and reCAPTCHA Enterprise, with a deep understanding of the intricacies involved in assessing and mitigating risks associated with user interactions. My expertise extends to interpreting reCAPTCHA Enterprise scores, analyzing JSON responses, and implementing effective measures to protect websites from potential threats.
Let's delve into the concepts mentioned in the provided article:
-
Assessment Creation:
- Before interpreting reCAPTCHA scores, you need to create an assessment for your website.
- The assessment involves submitting a user's reCAPTCHA response token to reCAPTCHA Enterprise.
-
Interpreting JSON Response:
- Upon submission, reCAPTCHA Enterprise returns a JSON response containing various parameters.
- Parameters include "valid," "invalidReason," "action," "expectedAction," "score," and "reasons."
-
Parameters in JSON Response:
- valid: Indicates whether the user response token is valid. If false, details about the failure are provided in "invalidReason."
- action: Represents the user interaction triggering reCAPTCHA Enterprise verification.
- expectedAction: The anticipated user action specified during assessment creation.
- score: Indicates the level of risk associated with the user interaction, ranging from 0.0 to 1.0.
-
Verifying Actions:
- Compare the "action" parameter in the JSON response with the "expectedAction" specified during assessment creation.
- Mismatch indicates a potential attack, allowing you to take appropriate actions, such as additional verifications or blocking.
-
Scoring System:
- reCAPTCHA Enterprise has 11 score levels, ranging from 0.0 (high risk) to 1.0 (low risk).
- Default accessible levels: 0.1, 0.3, 0.7, and 0.9. Access to all 11 levels requires a security review.
-
Interpreting Scores:
- Different actions are recommended based on the score received.
- Scores are influenced by real traffic, and short-term scores may differ from long-term production scores.
-
Actions Based on Scores:
- Recommendations for actions vary depending on the context of your site, such as implementing Multi-Factor Authentication (MFA) for low login scores or moderation for risky social interactions.
-
Reason Codes:
- Reason codes provide additional insights into how reCAPTCHA Enterprise interpreted interactions.
- Examples include "AUTOMATION," "UNEXPECTED_ENVIRONMENT," "TOO_MUCH_TRAFFIC," and more.
- Access to reason codes requires a security review.
-
Tuning Site-Specific Models:
- To improve the model's accuracy, send assessment IDs back to Google to confirm true positives/negatives or correct errors.
- This process is known as "Annotate assessments."
In summary, reCAPTCHA Enterprise offers a comprehensive approach to assessing and responding to user interactions, leveraging a sophisticated scoring system and real-time monitoring to enhance web security.
