Audit API security

Whenever you import an API to the 42Crunch Platform, API Security Audit automatically audits the OpenAPI definition to check the following:

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

Both OpenAPI Specification v2 and v3 are supported. The file size of your API should not exceed 10 MB.

View audit reports

You can check how many and what kind of issues Security Audit found in your API definition, as well as where they are located in the API definition. The report also shows how critical each issue is in terms of API security, so you can prioritize what to fix first.

1. Click API collections, and click the name of the API collection you want. You can see the APIs in the collection and their status at a glance.
2. Locate the API you want, and click the number of found issues in the Security Audit column to open the audit report. You can see, for example:
   • The audit score
   • The most common issues that the audit found in your API and how many times they occurred
   • Which issues would increase the security of your API definition the most (and consequently add most points to your audit score) if fixed

     

3. Click on the links in the summary, or use the filters on the left to drill into the results.
4. To see a list of all found issues instead of the overview, click Issues above the filter panel.
5. Click on the found issues to 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.
6. To jump to Security Editor to edit your API, click Fix issue in Security Editor.

For more details on fixing the issues that Security Audit found, see Fix APIs.

Export audit report

You can export an audit report from 42Crunch Platform, for example, to share with others.

1. Go to the audit report you want to export.
2. Click Export, and choose if you want to export the full report as JSON, or a report overview as a PDF.

We recommend you treat the exported report as company-confidential information and store it safely because it can reveal information on security risks in your APIs to outsiders.

Start audit manually

Declare mTLS authentication

If your API is using mutual TLS (mTLS) authentication, you can declare that in your OpenAPI definition with the vendor extension x-42c-mtls so that Security Audit can take this into account when it calculates the audit score.

Mutual TLS can only be considered secure if connections are over HTTPS, not if traffic is in the clear over HTTP. If you have declared mTLS with x-42c-mtls but server (OAS v3) or schemes (OAS v2) objects define http, Security Audit ignores x-42c-mtls and security issues deduct points normally.

You cannot apply x-42c-mtls, x-42c-accept-empty-security, or x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to the same API. This would lead to Security Audit getting conflicting directives for authentication checks so that it could not reliably process the API.

Use an audit rule to declare mTLS for the whole API

If your whole API uses mTLS, you can define an audit rule and tag the API for it to apply the rule. For more details on audit rules, see Customizations.

We recommend creating a dedicated audit rule and tag for mTLS, and naming both of them clearly to minimize any chances of this directive getting applied to an API by accident. Do not define this in your default audit rule!

You must be an organization administrator to create or edit customization rules.

1. Before you start, make sure that the category and tag you want to associate with your audit rule already exists. See Create new tags and categories.
2. Click next to your username, and click Customizations. You can see all customization rules already in your organization.
3. Add a new audit rule (recommended).
4. Enter a name for the rule, select the applying category and tag for it, and click Configure audit checks.
5. Select Change authentication checks, then select Mutual TLS is used, and create the audit rule.
6. To apply this rule to APIs, go to the API you want and add the corresponding tag to it. See Apply tags to APIs.

   

Security Audit runs authentication checks normally, but any found potential security issues do not reduce the audit score.

Apply the extension directly in API definition

You can add the extension to locally to individual API operations if the whole API is not using mTLS.

1. Click the API you want, and go to the Security Editor tab.
2. To declare mTLS on a particular operation, add the extension to that operation in the API definition:

   "get": {
       "summary": "List all pets",
       "operationId": "listPets",
       "x-42c-mtls": true,
       "tags": [
           "pets"
           ],
       ...

3. Click Save and re-test to update the API definition and run Security Audit again.

For more details, see x-42c-mtls

Allow empty security requirements

By default, Security Audit expects all API operations to require authentication and empty security requirements are considered as mistakes. However, if some API operations do not require authentication, you can set Security Audit to accept empty security requirements as an indication that authentication is not needed, rather than treating them as an error.

Pay attention that security requirements are left empty only where authentication really is not needed: if you allow empty security requirements, Security Audit treats all of them as intentional omissions, not mistakes, so you cannot rely on the audit to catch any that you simply forgot to fill.

You cannot apply x-42c-mtls, x-42c-accept-empty-security, or x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to the same API. This would lead to Security Audit getting conflicting directives for authentication checks so that it could not reliably process the API.

The empty security requirement (security: []) cannot be declared on the global level in the API, it must be declared in API operations.

Define an audit rule to allow empty security requirements

You can define accepting empty security requirements in an audit rule and tag the APIs for the rule when you want to apply it. This is the recommended option. For more details on audit rules, see Customizations.

We recommend creating a dedicated audit rule and tag for allowing empty security requirements, and naming both of them clearly. Because empty security requirements could pose a significant security risk in a wrong API, you should minimize any chances of this directive getting applied to an API by accident. Do not define this in your default audit rule!

You must be an organization administrator to create or edit customization rules.

1. Before you start, make sure that the category and tag you want to associate with your audit rule already exists. See Create new tags and categories.
2. Click next to your username, and click Customizations. You can see all customization rules already in your organization.
3. Add a new audit rule (recommended).
4. Enter a name for the rule, select the applying category and tag for it, and click Configure audit checks.
5. Select Change authentication checks, then select Allow empty security requirements, and create the audit rule.
6. To apply this rule to APIs, go to the API you want and add the corresponding tag to it. See Apply tags to APIs.

   

Security Audit runs authentication checks normally, but any empty security requirements found in the tagged API are not flagged as issues and do not reduce the audit score.

Apply the extension directly in API definition

You can also apply the extension x-42c-accept-empty-security directly on the global level in the OpenAPI definition of your API, but this may make it more difficult to spot potential conflicts with x-42c-no-authentication. Extensions applied directly to API definitions override extensions from audit rules.

1. Click the API you want, and go to the Security Editor tab. You can also open the API for editing outside 42Crunch Platform in the editor of your choice.
2. To allow empty security requirements, add the extension on the global level of the API definition:

   {
     "openapi: "3.0.0",
     "x-42c-accept-empty-security": true,
     "info": {
       "version": "1.0.0",
       ...

3. Click Save and re-test — or if you edited the API outside the platform, migrate your changes to platform — to update the API definition and run Security Audit again.

For more details, see x-42c-accept-empty-security.

Run audit without authentication checks

You can switch off authentication checks completely for your API, for example, if it is an early draft and you want to first focus on its format or data definition quality.

Switching the authentication checks off completely can be a big security risk down the line, and is not recommended. If unavoidable, remember to switch the back on as soon as possible.

The extension x-42c-no-authentication has no any effect if your API definition or operation includes the security field. Security Audit keeps running the authentication checks as long as the field is present.

You cannot apply x-42c-mtls, x-42c-accept-empty-security, or x-42c-no-authentication (either from audit rules or as extensions directly in the API definition) to the same API. This would lead to Security Audit getting conflicting directives for authentication checks so that it could not reliably process the API.

Define an audit rule to switch off authentication checks

You can define switching off the authentication checks in an audit rule and tag the APIs for the rule when you want to apply it. This is the recommended option. For more details on audit rules, see Customizations.

We recommend creating a dedicated audit rule and tag for switching off authentication checks, and naming both of them clearly, to minimize any chances of this directive getting applied to an API by accident. Do not define this in your default audit rule!

You must be an organization administrator to create or edit customization rules.

1. Before you start, make sure that the category and tag you want to associate with your audit rule already exists. See Create new tags and categories.
2. Click next to your username, and click Customizations. You can see all customization rules already in your organization.
3. Add a new audit rule (recommended).
4. Enter a name for the rule, select the applying category and tag for it, and click Configure audit checks.

   If you set the expiry date for the rule, you do not have to remember to remove it later: rules cease to be applied when they expire, so it is safer to set it to expire quickly and update the expiry date as necessary than leaving the rule in force for long.

5. Select Change authentication checks, then select Ignore authentication checks, and create the audit rule.
6. To apply this rule to APIs, go to the API you want and add the corresponding tag to it. See Apply tags to APIs.

   

Security Audit does not run authentication checks at all when auditing the tagged API, so the audit score does not reflect how secure the API definition actually is. Other security checks are still run normally and continue to reduce points. The audit rule always applies on global level in an API, so all operations are affected.

You can see that the overall audit score and the score for security change as authentication checks are removed:

Remember that the increased score is the result of the checks not being run at all, your API has not suddenly become more secure.

Apply the extension directly in API definition

You can also apply the extension x-42c-no-authentication directly to operation objects or on the global level in the OpenAPI definition of your API, but this may make it more difficult to spot potential conflicts with x-42c-accept-empty-security. Extensions applied directly to API definitions override extensions from audit rules.

1. Click the API you want, and go to the Security Editor tab. You can also open the API for editing outside 42Crunch Platform in the editor of your choice.
2. To switch off security checks for a particular operation, add the extension to that operation in the API definition:

   "get": {
       "summary": "List all pets",
       "operationId": "listPets",
       "x-42c-no-authentication": true,
       "tags": [
           "pets"
           ],
       ...

3. To switch off authentication checks for the whole API, add the extension on the global level of the API definition:

   {
     "openapi: "3.0.0",
     "x-42c-no-authentication": true,
     "info": {
       "version": "1.0.0",
       ...

4. Click Save and re-test — or if you edited the API outside the platform, migrate your changes to platform — to update the API definition and run Security Audit again.

For more details, see x-42c-no-authentication.

Specify sensitivity level

Define how sensitive API operations in your API definition are and how severe security risk is involved. Specifying a sensitivity level affects how the audit score is calculated for your API: an issue occurring in an operation marked to be more sensitive weighs more in the audit and reduces more points from the audit score than the same issue occurring in a less sensitive operation. This lets you to fine-tune Security Audit to better reflect the associated risks.

You can add the extension on the top level of your API to define the sensitivity level globally for the whole API, or locally to individual operation or responses. Local sensitivity levels override the global sensitivity.

1. Click the API you want, and go to the Security Editor tab.
2. Locate the operation you want in your OpenAPI definition, add the extension to that operation, and specify the sensitivity level, from 1 (not sensitive) to 5 (critical):

   "post": {
       "summary": "Creates a new admin user",
       "operationId": "addAdmins",
       "x-42c-sensitivity": 5,
       "tags": [
           "users"
           ],
       ...

3. Click Save and re-test to update the API definition and run Security Audit again.

In the following example, a login operation has been defined as a highly sensitive one. You can see how the increased sensitivity also increases the impact of the issue and how more points are reduced from the audit score:

For more details, see x-42c-sensitivity.

Instead of (or in addition to) the sensitivity of the operation, if you want to specify how sensitive data is included in a particular schema or parameter (for OAS v2 only), you can add the extension x-42c-sensitivity-data to the schema or parameter objects like x-42c-sensitivity to operation objects. See x-42c-sensitivity-data.