Customizations

One size does not fit all, not even in API security. How big a security concern an API is directly depends on the sensitivity of the data that its operations handle. 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 within an API: an operation listing ATM locations does not require same level of security as, say, payment operations.

To take this into account, organization administrators can customize the features in 42Crunch API Security Platform to reflect the different nature of your APIs. This helps you to prioritize the data you get on your APIs and concentrate your efforts where they matter the most.

Customizations are not available in the free community organization.

How customizations work

Customization rules comprise of a list of directives (instructions) to the features in 42Crunch Platform, such as API Security Audit and API Conformance Scan, on how they should behave: what to test or not, what is expected behavior in your particular circumstances, or how to consider the results.

Tags are the mechanism for applying the customizations to your APIs. When you define your customizations, you also define the tags that go with those customizations. Then, to apply those customizations to your APIs, you tag each API with the tag for the customization you want. You can only apply one audit and one scan rule to an API. This makes it easier to understand the results from the audit or scan and and prevents unpredictable combinations of directives for the same feature. However, organization administrators can control the handling of default rules in their organization.

We recommend putting customization rules in a dedicated category, so that it is easy to find the customization tags. We also recommend that you do not allow users to create tags in this category, so that organization administrators stay in control of these.

The screenshot shows four customizatios rules, three for audit and one for scan. On the right, details of one of the rules are shown.

When you create a new customization, you can choose when that customization starts to take effect and when it expires. This allows you to control the roll-out of your customizations so that you can prepare for the changes.

The maximum number of customization rules is 100.

Default customization rules

Normally, customization rules take effect when APIs get tagged with the tags that apply them. But sometimes a rule might be so important that you would like to make sure it gets applied even before APIs are tagged. This is what the default customization rules are for.

Each organization automatically gets a default audit rule and a default scan rule out of the box, so that you have a starting point right from the beginning. You cannot delete the default rules, but you can edit them as needed. You can also reset the default rules back to their original state.

The screenshot shows the default scan rule this organization has at the top of the customization rule list, with the details of the applying tag replaced by the status as the default rule.

Default rules are applied by default to all APIs in your organization. If APIs are tagged to apply other customization rules as well, the rule applied with the tag takes precedence over default rule: for example, if you tag your API to apply an audit rule, then the default audit rule is completely ignored.

Customizations for mandatory tag categories

Depending on how you decide to use tags, you might want to enforce all APIs to have a certain kind of tag. You can enforce this through mandatory categories in customization rules.

For example, you might want to ensure that your APIs always denote which service or application they relate to. You could create a category called Application and add a tag for each of your applications in that category. You could then set your default audit rule to automatically enforce the category Application as a mandatory category for all APIs in your organization. This way, each and every API that gets imported to any API collection in your organization is flagged as missing a tag from your mandatory category in Security Audit until the tag is applied to it.

The screenshot shows the default audit rule, with category called "Application" selected in the list of available categories to be mandatory.

Because the default audit rule is ignored if the API is tagged for another audit rule, you should repeat your mandatory categories in all audit rules. Otherwise, they might accidentally cease to be enforced. If you create the additional rules by copying your default rule, you can be sure that all your audit rules start from the same baseline.

Although Security Audit is the main gatekeeper by alerting on the missing mandatory categories, you can also define mandatory categories in scan rules. In this case, missing a tag from a mandatory category prevents creating a scan configuration for the API, thus blocking Conformance Scan.

For more details, see Enforce mandatory tag categories.

Customizations for Security Audit

You can customize how Security Audit handles your API definitions, for example:

  • Declare that your API uses mutual TLS (mTLS) authentication
  • Allow empty security requirements (security: []), to indicate that authentication is not required.
  • Stop audit flagging certain issues that you know are safe to ignore by skipping them in the audit.

    You cannot skip structural (validation-) or semantic (semantic-) issues in the audit, as these are required to make sure your OpenAPI definition is valid according to the OpenAPI Specification (OAS).

  • Define overall sensitivity of the operations in your APIs, as well as the sensitivity of data the schemas and parameters include.
  • Fine-tune how the audit algorithm weighs different elements when calculating the API score.

Because the customizations for audit use x-42c vendor extensions to the OpenAPI Specification (OAS), they can be done in two ways:

  • Define customizations as audit rules in 42Crunch Platform. The extensions are wrapped into a directives object that is then applied to your API definitions in 42Crunch Platform on the global level when they are tagged with the associated category:tag pair. When the audit rule takes effect, subsequent audits on the tagged APIs follows the specified directives. This is the recommended way.
  • Define customizations locally by manually adding the x-42c extensions directly to the specific objects in your API definition. The extensions take effect the next time the API definition is audited. This may be a good way to try different extensions, but is much more difficult to manage and maintain.
Customization Description Extension
   

Authentication checks

 

Declare that your API is using mutual TLS (mTLS) authentication, so that Security Audit can take it into account when calculating your audit score.

x‑42c‑mtls

Allow using empty security requirements (security: []) to indicate that an API operation does not require authentication.

x‑42c‑accept‑empty‑security (recommended)

Switch off authentication checks completely in Security Audit.

x-42c-no-authentication (not recommended)

Audit score

Set audit score to 0 if Security Audit finds any semantic issues in the API definition, to highlight that it is not a valid OpenAPI definition.

x-42c-no-score-on-semantic
Skipped checks

Define which checks Security Audit skips during the audit.

x-42c-skipIssues

Operation sensitivity level

Define how sensitive API operations in your API definition are and how severe security risk is involved.

  • Not sensitive: 1
  • Low: 2
  • Medium: 3
  • High: 4
  • Critical: 5

If no other value is specified, the property defaults to 3.

x-42c-sensitivity

Data sensitivity level

Define how sensitive data the schema or parameter definitions for API operations include and how severe security risk is involved.

  • Not sensitive: 1
  • Low: 2
  • Medium: 3
  • High: 4
  • Critical: 5

If no other value is specified, the property defaults to 3.

x-42c-sensitivity-data

Input weight

Define how much weight (as percentage) the input definitions of API operations get in the audit algorithm. The default value is 80.

x-42c-weight-input

Output weight

Define how much weight (as percentage) the output definitions of API operations get in the audit algorithm. The default value is 20.

x-42c-weight-output

Parameter weight

Define how much weight (as percentage) the parameter definitions of API operations get in the audit algorithm. The default value is 50.

x-42c-weight-parameters

Request body weight

Define how much weight (as percentage) request body definitions of API operations get in the audit algorithm. The default value is 50.

x‑42c‑weight‑requestBody

Header weight

Define how much weight (as percentage) the response header definitions of API responses get in the audit algorithm. The default value is 20.

x-42c-weight-headers

Content weight

Define how much weight (as percentage) the content definitions of API responses get in the audit algorithm. The default value is 80.

x-42c-weight-content

Success weight

Define how much weight (as percentage) the response definitions for HTTP status codes for success (1XX3XX) get in the audit algorithm. The default value is 70.

x-42c-weight-success

Failure weight

Define how much weight (as percentage) the response definitions for HTTP status codes for failure (4XX5XX) get in the audit algorithm. The default value is 30.

x-42c-weight-fail

For more details on each customization, see Extensions for Security Audit.

Customizations for Conformance Scan

You can customize how Conformance Scan behaves when scanning your API implementations with scan rules, for example:

  • Stop scan running certain tests and skip them during the scan.
  • Skip some API operations (methods) in the tests that the scan generates.
  • Define which HTTP response status codes are expected for errors and successes, both in the baseline happy path requests as well as for the actual test requests.
  • Define custom headers that scan includes in the requests it sends.

Scan customizations are defined as scan rules in 42Crunch Platform. Scan rule is a configuration that Conformance Scan uses when it scans APIs tagged with the associated category:tag pair. When the scan rule takes effect, subsequent scans on the tagged APIs follow the specified configuration.

If you are running Conformance Scan on-premises, you must delete and reconfigure the existing scan configurations for your APIs before new scan rules take effect.

Scan rules do not replace the existing scan configuration that defines, for example, the scanned endpoint and authentication details. Instead, scan rules let you define things outside the basic scan configuration and they are added on top of it.

Customization Description
Skipped tests If you know you do not want scan to run a particular test in a scan, you can state the IDs of the tests you do not want to run in the future. You can check which test ID goes with which test from your previous scan reports.
Skipped HTTP methods As with tests, you can also select which HTTP methods you do not want to include in your scans.
Expected error status

If you know that certain HTTP status codes for errors (4XX5XX) are to be expected in your environment, you can list them so that Conformance Scan knows those are expected and not anomalies. You can define this customization for the all happy path requests, and test ID by test ID for the actual tests.

For example, Conformance Scan considers a happy path request to be successful if the response to it is 200399 or 404. However, some frameworks respond with 400 or 403 instead of 404 that Conformance Scan expects for happy path requests. In this case, you can adjust Conformance Scan to accommodate your particular framework by listing its response status codes as expected.

Expected success status If you know that certain HTTP status codes for successes (1XX3XX) are to be expected in your environment, you can list them so that Conformance Scan knows those are expected and not anomalies. You can define this customization for the all happy path requests, and test ID by test ID for the actual tests.
Skip header assessment If you do not want the scan to analyze the headers in the API responses it receives, you can skip this. You can define this customization for the all happy path requests, and test ID by test ID for the actual tests.
Skip body assessment If you do not want the scan to analyze the body of the API responses it receives, you can skip this. You can define this customization for the all happy path requests, and test ID by test ID for the actual test.
Custom headers If you want to include custom headers in requests that Conformance Scan sends to the scanned API, you can define them as key—value pairs, where the key is the header name and the value sets the value of the header.

By default, the expected HTTP status response codes that are defined in scan rules applied to the scanned API take preference over the response codes that Conformance Scan would otherwise expect. However, this can cause problems in scan process if your scan rule only skips header or response body analysis but does not define any expected response codes, either for happy path requests or for particular test IDs. This results in the scan rule to have null defined as the expected response code, and because the scan rule takes preference over the default scan behavior, no response codes except null are accepted. This in turn means that some tests are incorrectly flagged as returning unexpected response codes when they were in fact successful.

For more details, see Create a new scan rule.