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 all APIs in your organization. If APIs are tagged to apply other customization rules as well, the directives from the rule applied with the tag takes precedence over default rule. 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.

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.

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 (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

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 (4XX—5XX) 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 200—399 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 (1XX—3XX) 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.