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.

What you can audit

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: 32 levels
  • Maximum number of object properties or array items in a element: 256
  • Maximum number limit: float64

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.

Audit report

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.

The report provides more details on the issues as well as recommendations on how fix them. The descriptions of the issues and their remediation 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 protected 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 the issue are shown in the report 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.

Audit score

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.

Security Editor

The Security Editor tab enables you to fix the issues that Security Audit found directly in 42Crunch Platform.

Note The issues represent real concerns in your OpenAPI definition, and they may either prevent API Protection completely, or severely impact its quality. We highly recommend that you fix all found issues.

You can see the issues Security Audit found in your API and your API definition side by side, so comparing them is easy. If you click on an issue, Security Editor shows where in the API definition the issue is located.

The small scoreboard at the top of the list shows how well your API scored overall and how the score is split between security and data definition quality.

Screenshot of an example scoreboard

By default, Security Editor shows all found issues in the list, but you can filter the shown issues based on the severity level.