API Contract Security Audit
The starting point for the API security is the API definition itself. If the API definition has gaping security holes, applying security measures on top of that just creates a ticking time bomb. The first step is to properly specify in your API definition the security constraints that an API consumer must conform to so that it can consume the API. This is where auditing the security of your API steps in.
Whenever you import an OpenAPI (formerly known as Swagger) definition into the 42Crunch Platform, API Contract Security Audit automatically performs a static analysis on the API definition. Your API is audited against the OpenAPI Specification (OAS) to check that the definition adheres to the specification and to catch any security issues your API might contain. The results clearly indicate the issues found and their respective severity levels, both when listing the APIs in a collection and in the audit report, so you can prioritize in which order to start fixing things.
Both OpenAPI Specification v2 and v3 are supported. The file size of your API should not exceed 4 MB.
For best performance, ensure that the complexity of your API definition meets the following:
- Maximum key length: 256 characters
- Maximum string length: 8192 characters
- Maximum depth for nested objects: 36 levels
- Maximum number of properties in an object or items in an array: 300
- Maximum number limit:
If your API definition is more complex than what is allowed, contact our support.
What the audit checks
Security Audit performs over 200 checks on your API contract, ranging from its structure and semantics to its security and input and output data definition. Security Audit reviews your API definition on three levels:
- OpenAPI format: Is your API a valid and well-formed OpenAPI file, and does it follow the best practices and the spirit of the OpenAPI Specification? Can it be correctly parsed, reviewed, or protected?
- Security: How good are the security definitions in your API? Have you defined authentication and authorization methods, and is your chosen protocol secure enough?
- Data validation: What is the data definition quality of your API? How well have you defined what data your API accepts as input or can include in the output it produces, and how strong are the schemas you have defined for your API and its parameters?
Data validation and security definitions are checked both on the global path level (affecting the whole API) as well as on operation level in individual operations.
Inadequate data validation is the most common attack vector in API security. It is very important to properly restrict what gets passed to your API and backend server and what your API can pass back to API consumers. This is reflected in Security Audit: in terms of numbers, checks on data definition quality form the biggest part of the audit.
When Security Audit finishes, you get a detailed report of the issues the audit found in your API.
The report shows the impact of each issue is, so you can prioritize what to fix first. The more dots an issue has, the more severe it is. You can jump from an issue directly to Security Editor, fix it in your API, and rerun the audit to see the improvement immediately.
The list of found issues shows how many points each issue deducted from the audit score of the API. Fixing the issues with the biggest impact on the score is the fastest way to a better audit score.
Clicking the found issues show articles that provide the issue ID of the audit check and more details on the issue as well as recommendations on how fix it. The IDs, descriptions of the issues and their remediations are also available online in API Security Encyclopedia at APIsecurity.io.
If your API has structural or semantic issues, it is not a valid OpenAPI definition. The API validation fails and you do not get a full audit report until you have fixed these issues. In addition, you cannot proceed to scan or protect your API as long as its structure or semantics does not conform to the OAS.
If an issue keeps recurring in multiple places in your API, only the first 30 occurrences of it are shown in detail to avoid cluttering the report up. The rest of the occurrences of the same issue are included in the report on subsequent audits as you fix the ones already reported.
Security Audit also calculates an audit score for each API it analyzes, based on the annotations in the OpenAPI definition. Security analysis on the authentication, authorization, and transport of data, and the data definition quality (data validation) in your API definition reveal direct security risks to your API.
Each API definition gets an initial pool of 100 points, split between the two categories of security risks as follows:
- Security analysis: max. 30 points
- Data validation: max. 70 points
During the audit, each security risk that Security Audit finds in the API definition takes away points according to the impact of the found issue, reducing the audit score of the API. In other words, the more points an API definition has, the better and more secure it is.
The audit score of your API definition affects API Protection. API Protection creates an allowlist of the valid operations and input data based on the API contract, and API Firewall enforces this configuration to all transactions, incoming requests as well as outgoing responses. If the audit score is too low, the security in your API definition is not yet good enough for a reliable allowlist. Security Audit should give your API 70 points or more before you can reliably protect it.
To improve the quality and security of your API, and to increase your audit score, you must fix reported issues and re-run Security Audit. For more details on fixing the issues, see Security Editor and extensions for third-party editors.
You can also integrate Security Audit with your CI/CD pipeline so that any changes to APIs in your project are automatically audited for security. For more details, see CI/CD integrations.
Security Audit can find multiple security risks in a single operation in your API. If all the found risks are equal in their severity (low, medium, high, critical), they are reported as per usual. However, if the severity of the risks in the same operation varies, it affects how the impact of the issues is shown in the audit report.
In security, the most severe risk is the biggest concern. If the audit finds multiple security risks with different severity levels in a single API operation, it only reports the impact from the risks with the highest severity level. The less severe risks are included in the audit report, but they do not impact the audit score until the more severe issues are fixed: their impact is shown as 0. On subsequent audits, the impact of the less severe risks is shown as the higher level risks get fixed.
Example: Security Audit finds four security risks (
D) in a single
POST operation in your API:
Ais a critical.
Care high severity.
Dis of medium severity.
In the report, you see the impact number (like 15) for the critical risk
A, but the risks
D show impact as 0, because their severity is lower than risk
You fix the risk
A and run Security Audit again. You get the points that fixing the risk
A brought to you, but now the risks
C will impact the audit score and take away some points, because they are now both on the next highest severity level in your
POST operation. Risks
C now each show their impact on the audit score. Risk
D still shows 0 impact because its severity is lower than
You fix the risks
C, and run Security Audit again. Risk
D is now the highest (and only) risk left in your
POST operation, and finally shows how many points it takes from the audit score.
Extensions for Security Audit
Not all APIs and API operations are equal, though, so one size does not fit all. It might be an overkill to require the strictest security from an API that does not handle sensitive data. This also applies on operation-level, an operation listing ATM locations does not require same level of security as, say, payment operations.
42Crunch vendor extensions to the OAS let you enrich your OpenAPI definitions with additional information on how they should be handled during audit. You can add them directly to the OpenAPI definition of your API in an editor of your choice to, for example, switch off authentication checks (
x-42c-no-authentication), or define the sensitivity of an operation (
For more details, see x-42c extensions.