Skip to main content

Set Dynamic Analysis URL scan settings for an organization with the REST API

You can use the Dynamic Analysis API to configure the following URL scan settings for an organization. These settings apply to all analyses and scans in an organization.

  • Custom user agents
  • Custom hosts
  • Concurrent browsers
  • Blocklists

The scan settings you configure at the scan level override the scan settings at both the analysis level and organization level. The scan settings you configure at the analysis level override settings at the organization level. If you do not configure scan settings at the analysis or scan level, all analyses and scans in an organization inherit the settings from that organization.

To complete this task:

  1. In the JSON input file, enter values for the following properties:

    • blacklist_configuration
    • org_info
    • visibility
    • user_agent

  2. To specify a custom header for a user agent, set "type: "CUSTOM". If you use a predefined user agent, such as Internet Explorer 11, you cannot include a custom_header field.

  3. Send the following request to apply the settings to the organization you specify for {your_organization_ID}:

http --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/orgs/scan_setting?org_id={your_organization_ID} < input.json

For the URL scan settings at the organization level, the following example JSON payload specifies to:

  • Exclude (blacklist) a specific file for one URL and all directories/subdirectories for a second URL. See directory_restriction_type Values.
  • Prevent a DNS lookup for a custom host.
  • Limit the number of concurrent browsers to five.
  • Set a custom header for a custom user agent. 
{
  "blacklist_configuration": {
    "blackList": [
      {
        "url": "http://www.example.com/block1/my_file.txt",
        "http_and_https": true,
        "directory_restriction_type": "FILE"
      },
      {
        "url": "http://www.example.com/block2/",
        "http_and_https": true,
        "directory_restriction_type": "DIRECTORY_AND_SUBDIRECTORY"
      }
    ]
  },
  "custom_hosts": [
    {
      "host_name": "my.custom.host",
      "ip_address": "127.0.0.1"
    }
  ],
  "max_browsers": 5,
  "user_agent": {
    "type": "DEFAULT",
    "custom_header": "string",
    "customerHeader": "string"
  }
}

directory_restriction_type values​

The following values are case-sensitive:

  • DIRECTORY_AND_SUBDIRECTORY: applies to the directory and all of its subdirectories in the specified URL. The default.
  • FOLDER_ONLY: applies only to the directory in the specified URL.
  • FILE: applies only to the file in the specified URL.
  • API_ENDPOINT: applies only to the API endpoint in the specified URL.
  • NONE: no restrictions. Applies to all directories, subdirectories, and files in the specified URL.