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 natures 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. Each category:tag pair can apply only a single customization.

We recommend putting customization rules in a dedicated category, so that it is easy to find the customization tags. You can also restrict that category so that users can only apply a single tag from it to any one API. This makes it easy to avoid adding two conflicting customization rules to an API.

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.

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.

You can have only a single customization rule of any one type as the default rule. So while you can have both a default audit rule and a default scan rule, you cannot have two default audit or scan rules.

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.

However, on directives that define a list — such as a list of skipped checks or methods, or list of tests with custom response analysis — the more generic directives from the default rule are applied in addition to the directives from the more specific rule from the tag. On other directives, such as toggles, the directive from the rule applied with the tag prevails. To avoid surprises, we recommend thinking carefully which directives should be defined in the default rule, which in other rules.

Example: You have a default scan rule called foo and on top of that you also tag an API to apply a normal scan rule bar. The directives of foo define the methods HEAD and OPTIONS as skipped operations, and 400 as an expected response code for happy path requests. The directives of bar define TRACE as a skipped method and skipping header assessment in response analysis. When you scan the API in question:

  • Conformance Scan skips the methods HEAD, OPTIONS, and TRACE, because the list of skipped methods from the default rule foo is added to the list in the rule bar.
  • Conformance Scan accepts 400 as an expected response code for happy path requests, as defined in the default rule foo.
  • Conformance Scan skips analyzing response headers because this setting is not a list, so the rule bar takes precedence over the default rule foo (where header assessment would still have been included).

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.

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:

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

The x-42c extensions for customizations applied locally in API definitions override the customizations defined as audit rules on the platform level and applied with tags.

Customization Description Extension

Authentication checks

Switch off authentication checks from Security Audit if they are not needed.

x‑42c‑no‑authentication

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.

For more details, see Customize platform features.