API 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 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 10 MB.

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. Data validation also contributes more to the audit score.

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.

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. You can also search the issue IDs in the documentation for the issue descriptions and remediations, or just browse API Security Encyclopedia.

You can download a copy of the report, for example, to share the results outside the platform.

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.

Audit score

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.

Security Audit uses a special algorithm to calculate the impact that different security risks from security schemes or requirements or poor data validation have on the audit score. Each risk has a base number of how many points they take away from the audit score. This starting point indicates how bad the issue itself is.

But Security Audit also considers the sensitivity level of the whole API or API operation. This reflects the level of risk involved with the API operation or the data it handles, and sets a severity multiplier for how risks are weighed in the algorithm: the higher the sensitivity, the more severe the issue and the more weight it gets. By default, sensitivity is considered to be medium, but you can tweak this directly in your OpenAPI definition if needed (see Extensions for Security Audit).

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.

You can also see how the audit score of the API has evolved over time in the Security Audit trends chart on the API summary page:

An example screenshot showing the API summary page of the Pixi API.

Multiple security risks in a single security requirement

APIs often define several different security schemes to accommodate for different authentication methods. These can then be combined in different ways in the security requirements that apply the security measures, either to the whole API or to a particular API operation. This in turn means that Security Audit can raise multiple issues in a single security requirement in your API definition.

If you have a single authentication method in a security requirement and Security Audit raises an issue on it, the impact to the audit score is clear and direct. However, if you have defined multiple authentication methods in the security requirement, bit more calculation is needed. In this case, the relative security of different authentication methods changes how the issues impact of the audit score.

In security, the most severe risk is the biggest concern. If the audit finds multiple security risks of varying severity in a single security requirement, it is the least secure authentication methods that pose the biggest risk to your API. Thus, only the methods deemed as the biggest risks affect the security grade and audit score.

The more secure authentication methods provide more protection even if they are not perfect. Issues found in them are raised as per usual, but they do not affect the audit score until the more severe issues found in the same security requirement are fixed. On subsequent audits, the impact of the less severe risks rolls in as the higher level risks get fixed.

When Security Audit finds security risks in a security requirement that applies multiple security schemes, it first checks the sensitivity of the API or the API operation, depending on which level the security requirement has been defined. Based on that, it then checks the severity of each issue found, and rates the different authentication methods (like OAuth 2.0, the various kinds of HTTP authentication, API keys) based on how secure they are on a scale of 15, from not severe and most secure to critical and least secure. Once Security Audit knows which issues are the most immediate concern, it can the calculate the impact on the audit score.

Extensions for Security Audit

Not all APIs and API operations are equal, 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 (x-42c-sensitivity).

For more details, see x-42c extensions.