API Schema Troubleshooting

Bright parses an uploaded API schema to define the attack surface of the scanned target. If the schema is configured improperly, Bright displays the corresponding warnings and error messages in the Schema Editor.

This section provides the guidelines on how to deal with the configuration issues which may occur while uploading an API schema for a new scan and editing it in the Schema Editor. To learn how to work with the Schema Editor, see Edit an Uploaded API Schema.

Configuration issues overview

All configuration issues can be divided in to two groups:

• The issues that may affect the scan results, but do not prevent running a scan. Such issues are indicated with yellow warning icons in the navigation tree and the smart view of the Schema Editor, and are usually caused by some missing values. To ensure the best scan results, it is recommended to resolve all the warnings that the Schema Editor points out.

• Critical issues (errors) that prevent using the schema for a scan. Such issues are indicated with red error icons in the navigation tree and the smart view of the Schema Editor. They are also accompanied with the corresponding error messages at the bottom of the Schema Editor. The messages usually contain a link (path) to the place in the schema view where the issue is found and a short description of the error cause.

Hierarchically, there are several levels of errors depending on their cause:

• Syntax errors. Have the highest priority, and therefore are displayed first in case of multiple errors of different origin. You will be able to see other errors only after you fix the syntax errors.

• Validation errors. Mostly involve incorrect specification of property names and their values. Structurally, they are presented as <location_prefix>: <error_message>, where:

  • <location_prefix> is either "Error at /path" or "Error at the schema root", where the underlined part is a link to a specific place in the schema. An external path (to an endpoint, an object) starts from /, while all items inside an object (internal path) are separated with .
  • <error_message> is a short description of the error cause.

  Below is an example of a validation error caused by incorrect data type of a value. On the screenshot, the host (url) is expected to be a string, but an additional character was added to demonstrate the error.

• Converting errors. Such errors may occur when the converter cannot generate a .HAR file based on the schema due to invalid configuration. For example:
  • When a sample value cannot be generated due to incorrect (contradicting) conditions. On the screenshot below the minimum number was set to 30, and the maximum number was set to 10. No number can meet these conditions, which resulted in a converting error.

• When prefixing item-level host property with a character like ^ in a Postman collection.

OpenAPI/Swagger schema validation checklist

If you get a parsing error when uploading an OpenAPI schema to Bright, validate and correct the schema configuration according to the following checklist:

1. A target server (host) must be specified:

   • If you are using OpenAPI 3+, include the servers property.
   • (For OAS 3). If the servers values contain variables, it is recommended to define them explicitly (use variable substitutions) to ensure correct scan results. See item 4 for more information.
   • If you are using a Swagger 2+ schema, include the host property.

2. OAS 3 may include multiple servers. Here is an example taken from the Swagger documentation:

}
 "servers": [
   {
     "url": "https://development.gigantic-server.com/v1",
     "description": "Development server"
   },
   {
     "url": "https://staging.gigantic-server.com/v1",
     "description": "Staging server"
   },
   {
     "url": "https://api.gigantic-server.com/v1",
     "description": "Production server"
   }
 ]
}

Bright uses the FIRST element in the servers array as a scan target. If the first server in your schema is not the scan target, you need to change the order of the servers manually in the schema view, or use the Server field in the smart view. Once you select the server to be placed first in the smart view, the order of the servers will be updated automatically in the schema view.

3. Values for all parameters should be specified to ensure correct and complete scan results. You can either add the values directly to the raw schema or enter them in the corresponding Value fields in the smart view.

   If no parameter value is provided:

• The corresponding value field in the Schema Editor is left empty, resulting in a warning icon next to the endpoint.

• Bright automatically defines the data type and generates a random alternate value when parsing the schema.
  By specifying the substitutions, you ensure correct and complete scan results.

👍

Tip

During generation of a random value, Bright takes in to account all the constraints defined for a certain data type in the schema. By specifying the constraints, you ensure better results of alternate values generation. For example, you can use the following constraints:

• For numbers – minimum, maximum
• For strings – pattern , minLength, maxLength
• For arrays – maxItems, minItems, uniqueItems
• For objects – additionalProperties, minProperties, maxProperties

For more information, see the Swagger documentation.

4. (For OAS 3). If variables are used for a server configuration, you should specify substitutions for them to ensure correct scan results. If no substitution is used, Bright automatically detects the data type and generates a random alternate value when parsing the schema.

   The values in the smart view are displayed with the variables applied. In the example below, we set the domain and apiVersion variables for a server in the schema view:

"servers": [
   {
     "url": "https://{domain}/apis/{apiVersion}",
     "description": "Code API",
     "variables": {
      "domain": {
       "default": "coda.io"
     },
     "apiVersion": {
      "default": "v1"
     }
    }
   }
  ]

In this case, the server in the smart view will be displayed as follows: <https://coda.io/apis/v1>.

Postman collection validation checklist

If you get a parsing error when uploading a Postman collection to Bright, validate and correct the schema configuration according to the following checklist:

1. The URL item must be specified properly, for example:

• Literal

{{url}}/.well-known/openid-configuration?client_id={{clientId}}

• Broken-down

{
 "url": {
   "raw": "{{url}}/.well-known/openid-configuration?client_id={{clientId}}",
   "host": [
     "{{url}}"
   ],
   "path": [
     ".well-known",
     "openid-configuration"
   ],
   "query": [
     {
       "key": "client_id",
       "value": "{{clientId}}"
     }
   ]
 }
}

A problem may arise when the structure of a broken-down URL is incorrect, or the required (expected) fields are missing. Please refer to the Postman documentation for more information.

Here is an example of incomplete URL:

"url": { 
    "raw": "{{url}}/.well-known/openid-configuration?client_id={{clientId}}"
    }

2. Every environmental variable must have a value.

   The Schema Editor supports the Postman feature of dynamic variables. This allows you to generate random values per request, for example:

"variable": [
                {
                  "key": "batchResultId",
                  "value": "{{$guid}}"
                }

The dynamic variables can also be used to generate values when converting a Postman collection in to a .HAR file.

Can I upload an “imperfect” API schema without fixing the baseline values ahead of time?

Yes! You can upload a schema without any baseline values, and then review problems in-app and fix them, as simple as editing a single value.

Can I add Entrypoints to the project from legacy scans?

Not from the scan summary directly, but rerunning a previous scan will automatically add all relevant Entrypoints to the project (and link issues as needed).

Can I delete Entrypoints? And what will happen to its Issues?

Yes, you can delete EPs and their associated issues will remain as “unassociated”, both under the project and in the scans. Such issues can be associated with a different entrypoint later on.

How to Add Bright to the WAF Allowlist

This section provides information on how to add Bright to the WAF allowlist. For instructions, go to the necessary WAF type below, and then click the link to access the document.

Reblaze WAF

To add Bright to the allowlist, add Bright IP addresses as Bypass and add an OC policy according to the ACL Policies guide.

AKAMAI WAF, AKAMAI V2, Trellix and Akamai Collaboration

To modify an API Client IP allowlist for BrightSec, follow the instructions under the links below.

• Official documentation
• Non-official documentation

Cerber WP

The IP Access List (ACL) enables the users to restrict access to the WordPress admin dashboard, and vital WordPress features, and protect login and registration forms from access by unwanted computers and bots. For information on how to use the IP Access Lists, see Using IP Access Lists to Limit Access and Protect WordPress.

Siteguard

This WAF doesn't have ACL. For instructions on adding Bright to the Siteguard allowlist, see How to Limit Access to Website During Development.

Cloudflare CF-RAY, Cloudflare DNS WAF

Access Control Lists (ACLs) define allowed source IP addresses from where servers accept incoming data or control messages. For details, see the links below.

• Access Control Lists (ACLs)
• Allow Cloudflare IP Addresses

To add Bright to the Cloudflare allowlist, see Adding Bright DAST to the Allowlist on Cloudflare.

BlockDOS WAF

BlockDOS WAF has a cookie policy. Cookies consist of portions of code installed in the browser that assist the Owner in providing the Service according to the purposes described. For details on BlockDOS WAF Cookie Policy see Cookie Policy.

Wallarm

For adding IP address to the allowlist for Brightsec, see IP Address Whitelist.

OpenResty Lua WAF

lua-resty-waf is distributed with a number of rulesets that are designed to mimic the functionality of the ModSecurity CRS. For more information about rules, see lua-resty-waf - High-Performance WAF Built on the OpenResty Stack.

A10 Thunder

access-list extended: Configure an extended Access Control List (ACL) to permit or deny traffic based on source and destination IP addresses, IP protocol, and TCP/UDP ports. For details, see ACOS 1.0 Documentation - Access-List Extended.

BulletProof Security Pro

BulletProof Security Pro has a cookie policy. For information on how cookies are used on bulletproof.co.uk, the options for controlling the use of cookies, and what cookies are used, see Bulletproof cookie Policy.

Nemesida

Nemesida has a personal pane where administrators can set up correct rules. The appropriate sections are Add new user and Unlock Request functionality. For more information, see Nemesida WAF Cabinet.

ModSecurity

The following link provides an easy way to set up the allowlist based on IP addresses: How to whitelist an IP address in ModSecurity.

Gocache WAF

You need to add the BrightSec IP address to ACL. For documentation, see Customização do WAF.

📘

Note

The original documentation is in Portuguese. Please use Goolge translate to translate the page.

Imperva, Incapsula

For setting up Imperva Web Protection (Security Settings and ACL for Brightsec), see the documentation below.

• Web Protection - Security Settings
• Security Rule Use Case Examples
• Create and Manage Policies
• ACL Section

F5 ASM – BIG IP

APM® access control lists (ACLs) restrict user access to host and port combinations that are specified in access control entries (ACEs). An ACE can apply to Layer 4 (the protocol layer), Layer 7 (the application layer), or both. Layer 4 or Layer 7 ACL is used with network access, application access, or web access connections. For details, see Configuring Access Control Lists.

AWS WAF

For instructions on adding Bright to the AWS WAF allowlist, see AWS CloudFront.