Findings
Missing 401 response
Updated: June 19, 2025
Description
An endpoint is missing the definition for a 401 response.
Consistent and well-documented HTTP status codes in API specifications play a vital role in the usability and understanding of an API. When developers consume an API, clear status code definitions save them time and reduce the risk of misinterpreting a response. HTTP 401, in particular, signifies that the requester has not provided the credentials necessary to view the resource. This is a common response in APIs, especially those that require authentication.
This rule applies at the API Specification level (OAS/Swagger).
Example Attack
Security Misconfiguration Exploitation: The absence of a 401 response may indicate a broader security misconfiguration in the API or its authentication mechanisms, which attackers can exploit to gain unauthorized access or compromise the system.
Remediation
Ensure API specifications include definitions for 401 responses. API endpoints that do not return HTTP status code descriptions are more difficult to use for developers. Adding standard responses to API specifications ensures use of those APIs is predictable and safe.
Security Frameworks
This category combines API3:2019 Excessive Data Exposure and API6:2019 - Mass Assignment, focusing on the root cause: the lack of or improper authorization validation at the object property level. This leads to information exposure or manipulation by unauthorized parties.
Looking forward to generic implementations, developers tend to expose all object properties without considering their individual sensitivity, relying on clients to perform the data filtering before displaying it to the user.
CIS-ASG-2.3.2: CIS 2.3.2: Establish standardized error handling procedures
Put in place a consistent procedure to handle errors.
Rationale
Establishing standardized error handling procedures ensures consistency across the API, providing a uniform approach to managing and communicating errors. This improves the clarity and usefulness of error messages for developers and users, enhancing overall user experience. It also prevents revealing sensitive information that could help attackers.
Remediation
- Improve the clarity of error messages.
- Establish guidelines for handling errors.
- Enforce HTTP return status compliance.
- Update the documentation accordingly.
Audit
- Review the documentation by inspecting the existing error format that is in place.
- Identify potential disclosure of internal system information in error messages.
- Assess all existing error message quality - is it comprehensive, does it correctly communicate the error.
- Verify HTTP standards compliance, for example 404 error should be used for non-existing resources, 401/403 error codes should be used for unauthorized access and so on.