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 OAS 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

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?
  • 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?

First, your API is checked for the validity and well-formedness of the OpenAPI format. This validation does not focus on security risks but the quality of your API definition as a whole. This helps ensure that 42Crunch Platform can correctly parse, review, and protect your API, and that API consumers can consume it as intended. If the OpenAPI definition of your API has structural errors, validation fails and the rest of the audit is not run until you have fixed the errors.

After validation, Security Audit focuses on direct security risks in your API by analyzing the security and data definition quality. The audit examines data validation and security definitions 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.

Audit report

When Security Audit finishes, you get a detailed report of the issues the audit found in your API and where they are located in the API definition. The report shows how critical each issue is in terms of API security, so you can prioritize what to fix first. 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 report also provides more details on the issues as well as recommendations how fix them. The descriptions of the issues and their remediation are also available online in API Security Encyclopedia at APIsecurity.io.

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.

If your API has structural issues, it is not a valid OpenAPI definition. The validation fails and your API cannot be audited, scanned, or protected. The API does not get an audit score until all structural errors are fixed.

If your API does not have any structural errors, it can be audited and it gets an audit score. However, any semantic errors in the API definition still mean that it is not a valid OpenAPI definition, and it cannot be protected yet. You must fix all structural and semantic errors before your OpenAPI definition is valid and you can proceed to API protection.

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

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. 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.

The dots on each issue indicate the severity of the involved security risk. The more dots an issue has, the more severe the risk. If you click on an issue, Security Editor shows where in the API definition the issue is located.

TipThe list of found issues in Security Editor also 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.

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