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.

How customizations work

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.

Default rules are applied by default to any APIs in your organization that are not tagged for a rule of the same type (audit rule or scan rule). If APIs are tagged for other other customization rules as well, the rule applied with the tag takes precedence and the default rule is completely ignored. You can see all customization rules that apply to a particular API on the API summary tab.

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.

Currently, GraphQL APIs are not supported.

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 all your audit rules, including the 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.

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

For more details, see Enforce mandatory tag categories.

Customizations for Security Audit

The customizations that are supported depend on the type of your API. For more details on each customization, see Extensions for Security Audit.

Customization for OpenAPI definitions

You can use customizations in your OpenAPI definitions to, for example:

• Declare that your API uses mutual TLS (mTLS) authentication
• Allow empty security requirements (security: []), to indicate where authentication is not needed
• Switch off authentication checks
• 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 when auditing OpenAPI definitions, as these are required to make sure your API definition is valid according to the OpenAPI Specification (OAS).

• Define the sensitivity of an operation

Because the customizations for audit use x-42c vendor extensions to the OpenAPI Specification (OAS), they can in most cases 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.	N/A
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 (1XX—3XX) 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 (4XX—5XX) get in the audit algorithm. The default value is 30.	x-42c-weight-fail

Customizations for GraphQL APIs

You can use customizations in your GraphQL API definitions to, for example:

• Stop audit flagging certain issues that you know are safe to ignore by skipping them in the audit.
• Map the directive names in your naming convention to the most commonly used directive names

As with the OpenAPI definitions, the customizations use x-42c extensions. In GraphQL APIs, customizations are always applied on global level and you can do this in two ways:

• Define customizations as audit rules in 42Crunch Platform. The extensions are 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 customization by manually adding the x-42c extensions as a comment block directly into 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. Security Audit expects your customization rules to be in a single comment block to avoid accidentally giving conflicting directives to it. If your GraphQL API includes multiple comment blocks for customization rules, the audit only takes the first comment block into account and ignores the rest. You must explicitly indicate both the start and finish of your comment block:

  """
  start customization rules
  x-42c-custom-gql-directives-names:
  ...
  end customization rules
  """

Because in GraphQL APIs customizations are always applied globally, for governance reasons customizations applied as audit rules in 42Crunch Platform override the customizations defined as comment blocks in GraphQL APIs.

Customization	Description	Extension
Skipped checks	Define which checks Security Audit skips during the audit.	N/A
Directive naming convention	Map the GraphQL directives names that Security Audit expects by default to the ones used in your GraphQL API definitions.	x-42c-custom-gql-directives-names

Customizations for API Scan

The customizations that are supported depend on the type of your API. For more details on each customization, see Extensions for Security Audit.

Customization for OpenAPI definitions

You can customize how API 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 API 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 API 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 (4XX—5XX) are to be expected in your environment, you can list them so that API 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, API Scan considers a happy path request to be successful if the response to it is 200—399 or 404. However, some frameworks respond with 400 or 403 instead of 404 that API Scan expects for happy path requests. In this case, you can adjust API 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 (1XX—3XX) are to be expected in your environment, you can list them so that API 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 API 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 API 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.

Customization for GraphQL APIs

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

• Stop scan running certain tests and skip them during the scan.
• 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 API 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 API 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.
Custom headers	Define custom headers that the scan includes in all requests to the scanned API as key—value pairs, where the key is the header name and the value sets the value of the header.