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 object properties or array items in a element: 256
- 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.
Note 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.
Tip 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 OpenAPI annotations in the API definition.
The API definition gets an initial pool of 100 points. During the audit, each security risk that Security Audit finds takes away points and reduces the audit score of the API. The audit score reflects what is the risk associated with the API. The more points API gets, the better and more secure the API definition is.
The following is how the points are split between the two categories:
- Security analysis: max. 30 points
- Data definition quality: max. 70 points
API validation against the OAS does not affect the API score, it only flags the API either valid or not.
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 Visual Studio Code extension.
TipYou 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 API security CI/CD integration.
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.