API Security

API Security

API Security 1
 Contents

Contents
Imperva API Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
API Security Taxonomy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
API Host. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
API Resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
basePath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
API Endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
API Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Discovered API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
OAS API (Open API Specs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
My APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Shadow API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
New API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
New API and Shadow API Identification Flow Chart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Data Classification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Data Label. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
API Security Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
API Security Onboarding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Dashboards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Discovered APIs Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Policy Enforcement Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Discovered APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
My APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Site-level Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
API-level Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
API Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Data Classification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
API Authentication Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
API Authentication State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
API Authentication Discovery Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Add Authentication Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

API Security
 Contents

API Inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
API Authentication State and OWASP API Top 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Default List of Authentication Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Excessive Data Exposure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Identifying APIs with Excessive Data Exposure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Excessive Data Exposure Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Setting Up Excessive Data Exposure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
API Inventory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Default Thresholds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Verification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
OAS File Assessment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Generating Assessment Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
View Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
OAS File Security Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Generating Test Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Test Execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
API Calls for Verification Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Mass Assignment Vulnerability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Detection and Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Policies and Security Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Default Policy Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Imperva Data Classification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
API Security API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
API Security API Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
API Security Clarifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

API Security
 API Security

Imperva API Security

Imperva API Security is part of the Imperva Cloud Application Security suite, allowing you to protect your APIs. The
features and services available to you depend on your license.

APIs are the cornerstone of the digital transformation. They allow organizations to develop applications in innovative
architectures, automate B2B processes, connect IoT devices, and are the backend for mobile applications. As more
and more organizations go through the digital transformation, the use of APIs surges. With this surge, attacks on APIs
are also on the rise. Hence, organizations have to adopt a new approach to protect their APIs.

API Security is available under the account-level on the Cloud Security Console as an add-on to the CloudWAF.
Enabling API Security does not negatively impact your application because API Security performs API inspections in
an out-of-band manner.

The add-on API Security is purpose-built to address application specific threats against custom APIs. It is not
uncommon for APIs in production to deviate from API specifications due to the lack of API documentation or frequent
changes. There are also categories of data exfiltration attacks leveraging schema conforming API calls that cannot be
detected by API Schema Protection. The key first step to protect applications against these new categories of threats is
to discover the APIs, their structure in order to differentiate from API endpoint detection, and identify sensitive
information that is being transferred using the APIs.

The API Security add-on provides a comprehensive, data driven API Discovery, which enables you to:

• Understand your API exposure surface with complete and up to date, inventory of your APIs and their
configuration.
• Identify contextually sensitive data.
• Protect your APIs with a positive security model even if you don’t have an OAS file. With an ongoing learning
mechanism, API Discovery constantly learns the structure of the APIs whenever they are updated.
• Gain tighter protection of your APIs on top of the existing OAS files provided by the development teams.
• Decide on the appropriate security level for each API endpoint according to the sensitivity of the data returned
by it.
• Download a specifications file of the discovered endpoints
• Use analytics and display Data Classification so that you can know which API endpoint transfers PII and other
sensitive information.

Additional capabilities:

• Allows users to see security events per API endpoint and automatically creates and enforces a positive security
model layer from the customer’s Open API specification document (i.e. Swagger).
• Integrates with API management platforms through designated APIs and open source tools, making security an
integral part of API lifecycle management.
• Automatically disables Captcha cookie challenge and Javascript challenge on API traffic.
• Leverages the SaaS infrastructure and the CDN, WAF, BOT and DDoS capabilities of Imperva Application Security
suite, and uses the same management portal.

API Security 4
 API Security

API Security Taxonomy

The following topics explain the API Security terms.

• API Host
• API Resource
• API
• API Endpoint
• API Specification
• Discovered API
• OAS API (Open API Specs)
• My APIs
• Shadow API
• New API
• New API and Shadow API Identification Flow Chart
• Data Classification

API Security 5
 API Security

API Host
This is the application host that supports an API.

API Host: Host

Example:

API Host

api.imperva.com

mysite.mycompany.com

Note: Technically, an API Host is the value of the HTTP Host header. There can be a number of
destination servers that support the same API Host.

API Security 6
 API Security

API Resource
The complete path where information can be accessed or operated within an API.

Example:

API Resource: /mysite/operational-status, /shopping-cart/item/1/info, /api/v1/employee/12312/status

API Resource = URL-Path

For RESTful APIs, a resource contains "basePath" and "Path".

• basePath
• Path

API Security 7
 API Security

basePath

A logical entity that groups resources pertaining to a similar version of an implementation, a similar code base within
an implementation, or a similar feature within the product.

API Security 8
 API Security

Path

The logical location after the basePath where the resource is accessible.

Example

With reference to the examples described in API Resource.

API Resource basePath Path

/mysite/operational-status / /mysite/operational-status

/shopping-cart/item/1/info /shopping-cart /item/1/info

/api/v1/employee/12312/status /api/v1/employee /12312/status

Hence, API Resource = basePath + Path

It is important to note that an API Resource does not describe anything about the location (i.e. the host or the server).
At the same time, an API Resource is not referred to by itself and is always used in conjunction with the definition of an
API or an API specification which incorporates the host or the server details.

Hence, when using API Resource by itself it means the following:

API Resource = API Host, basePath + Path

Example

API Host API Resource basePath Path

api.imperva.com /mysite/operational-status / /mysite/operational-status

mysite.mycompany.com /api/v1/employee/12312/status /api/v1/employee /12312/status

API Security 9
 API Security

API
An API is a programmatic interface to a service that allows you to perform a set of actions. As such, there are different
types of interfaces and hence different types of API formats. A primary format of the APIs is called REST/JSON APIs. In
regards to REST/JSON, an API is defined as the combination of the API Host and basePath.

API = API Host + API basePath

Example

API Host basePath

api.imperva.com /

mysite.mycompany.com /api/v1/employee

API Security 10
 API Security

API Endpoint
An API Endpoint describes the location and how an API Resource must be accessed within an API. So it has to provide
the information: "how", "where", "what".

In the HTTP world used by REST APIs, "how" is the Operation or Method. "Where" is the Host. "What" is the Resource
(URL path or basePath + Path).

API Endpoint = API Method, API Host, basePath + Path

Example

API Method API Host basePath Path

GET api.imperva.com / /mysite/operational-status

POST imperva.com /shopping-cart /item/1/info

HEAD mysite.mycompany.com /api/v1/employee /12312/status

API Security 11
 API Security

API Specification
An API Specification defines the detailed information related to an API and its Endpoints. In case of REST/JSON APIs, it
is typically a file that documents details of each individual API identified by the API Host + API basePath. Within this is
a collection of Paths and under each Path is defined the details of the methods that can be operated and the expected
input/output for each of them. A simplified hierarchical representation of an API Specification is as follows:

API Security 12
 API Security

API Security 13
 API Security

Discovered API
The APIs that have been identified as part of the discovery process by the discovery engine. Usually the discovery
engine starts with a learning process. Once it has gained enough confidence, it will baseline the API. Hence
"Discovered API" has two states: In progress (a.k.a Learning), and Baselined.

API Security 14
 API Security

OAS API (Open API Specs)

The APIs that have been uploaded using an Open API specification file. This file could be a swagger file or an open API
Specification.

API Security 15
 API Security

My APIs
The collection of APIs that were configured for analytics, risk analysis, threat detection and protection policies. This
collection can be created by using the two sources of APIs that we currently support - APIs from the Discovered API
list, APIs from the OAS API files.

API Security 16
 API Security

Shadow API
Shadow APIs are defined with respect to the My APIs.

For an API that is being inspected, we consider two entities. Its API Host and API basePath.

When the API Host and API basePath match those provided within My APIs and if:

• Any new Path is identified in traffic, it is defined as a Shadow API

• Any new Method is identified for an existing Path, it is defined as a Shadow API
• Any new Parameter (either in request or response) is identified for an existing Path and Method, it is defined as a
Shadow API
• Any missing required Parameter is identified for an existing Path and Method, it is defined as a Shadow API
• Any different data type is identified for an existing Parameter of an existing Path and Method, it is defined as a
Shadow API

API Security 17
 API Security

New API
New APIs are defined with respect to the My APIs.

For an API that is being inspected, we consider two entities. Its API Host and API basePath.

When the API Host match with the hosts provided within My APIs and if:

• Any new API basePath is identified that is not part of existing basePaths for this host, it is defined as a New API

Additionally, when the API Host for the API being inspected does not match any host defined in My APIs, it is defined
as a New API.

API Security 18
 API Security

API Security 19
 API Security

New API and Shadow API Identification Flow Chart

API Security 20
 API Security

API Security 21
 API Security

Data Classification
Data classification gives you visibility over which API endpoint transfers PII information and the ability to decide on
the appropriate security level for each API endpoint according to the sensitivity of the data returned. The data
classification is shown by Labels that are added to the endpoint. For more see, Imperva Data Classification.

• Data Label

API Security 22
 API Security

Data Label

A Label is a system tag assigned to an entity.

The Data Label is a tag that is assigned based on the property of the entity’s data. For example, an API Endpoint can
be assigned a Data Label "SSN" which indicates that the entity (here it is an API Endpoint) has an element (may be a
path parameter) that contains SSN values.

A Data Label contains secondary level label information. For example, "US-Address" is a Data Label. Within "US-
Address", Zip-Code is a secondary level label.

API Security 23
 API Security

API Security Prerequisites

Prior to setting up Imperva API Security you need to:

1. Onboard a site to Imperva Cloud WAF for the domain the API is using. Refer to Onboarding a Site – Web
Protection and CDN for detailed instructions on how to perform this.

You will be able to protect any API under that domain/sub-domain once the site is configured.

2. [Optional] Enable content based error responses. Under the website, go to Origin and Network > General and
under the Additional Settings section, select the Enable content based error responses check box. For
details, see Error Responses.

Note: Error responses are returned in JSON or XML format, based on the Accept or Content-type
HTML request headers. By default, error responses are returned in HTML format only.

API Security 24
 API Security

API Security Onboarding

API Security can be purchased by contacting an Imperva sales representative.

Once you have purchased API Security, you can access it from the Imperva Cloud Security Console.

From the Imperva Cloud Security Console:

1. Log in to your my.imperva.com account.

2. On the top menu bar, click Application.
3. On the sidebar, click API Security. and select the page you want to go to from the drop down.

API Security 25
 API Security

Dashboards
The Dashboards page is comprised of two tabs:

• Discovered APIs
• Policy Enforcement

• Discovered APIs Dashboard

• Policy Enforcement Dashboard

API Security 26
 API Security

Discovered APIs Dashboard

The Discovered APIs Dashboard reflects the statistics for the APIs that have been baselined during the discovery
process (they do not include the statistics for APIs that are in-progress). It presents a predefined page containing the
following widgets:

• Hosts: This widget lets you see and set the API hosts you want to view or see them all.
• Time range: This widget lets you see and set the time period that you wish to view the information for on the
dashboard. The available time periods are: Last 24 hours, Last 7 days (default), Last 30 days, Last 90 days and
Custom.
• Show only new APIs: a check box that when selected, sets all widgets to indicate statistics only about the new
APIs that were discovered since the last baseline.
• API Calls: This widget lets you see the total number of API calls
• Client Apps: This widget lets you see the total number of applications
• Client User-Agents: This widget lets you see the total number of user-agents
• Client Countries: This widget lets you see the total number of countries the APIs are spread over.
• API Hosts: This widget lets you see the top API hosts for your account and the volume of API calls running
through them. Here you can:
• View all the API hosts by clicking Expand, which opens a popup page showing all the API hosts for your
account. You can filter to see all the new API hosts by selecting the checkbox.
• Download the list of all API hosts to a CSV file by clicking .
• API Resources: This widget lets you see the top API resources for your account and the volume of API calls
running through them. Here you can:
• View all the API resources by clicking Expand, which opens a popup page showing all the API resources
for your account. You can filter to see all the new API resources by selecting the checkbox.
• Download the information to a CSV file by clicking .
• API Endpoints: This widget lets you see the top API endpoints for your account and the volume of API calls
running through them. You can download the information to a CSV file by clicking .
• View all the API endpoints by clicking Expand, which opens a popup page showing all the API
endpoints for your account. You can filter to see all the new API endpoints by selecting the checkbox.
• Download the information to a CSV file by clicking .
• API Endpoint Overview: This widget lets you see new API Endpoints that carry sensitive data and have
unauthenticated risks seen for the first time in last 30-days.
• Labels Identified: The total number of identified labels
• Labeled API Endpoints: The total number of labeled API endpoints
• Risky API Endpoints: The total number of risky API endpoints
• OWASP API Top 10 Risks: The total number of OWASP API Top 10 Risks
• Other Risks: The total number of risks that are not OWASP API Top 10 Risks
• A table showing the labeled API endpoints and their associated data labels API risks and call volume
(compared to the previous time range).
• Security Risks and Vulnerabilities: This widget lets you see the:
• Top Data Labels Identified: The distribution of the top data labels that were identified. You can filter
the data to show all data labels, sensitive only data labels or non-sensitive only data labels. In addition
you can download the information to a CSV file by clicking .

API Security 27
 API Security

• Top Risks Discovered: The top risks from other API threats such as unauthenticated APIs and excessive
data exposure. In addition you can download the information to a CSV file by clicking .

Note: For more details including a list of the supported data labels, see Imperva Data Classification

• Hosting Providers: This widget lets you see the top providers and their call volume.
• Geographic Location: This widget lets you see, geographically, the top countries with the most volume of API
calls. You can select to see the top locations by client or by destination. In addition you can download the
information to a CSV file by clicking .

API Security 28
 API Security

Policy Enforcement Dashboard

The Policy Enforcement Dashboard presents a predefined page containing widgets that give a quick informative, and
in some widgets drill down capabilities, of the site's APIs that are protected on your system. These widgets are:

• API Host: This widget lets you see and set the API hosts you want to view or see them all.
• Time range: This widget lets you see and set the time period that you wish to view the information for on the
dashboard. The available time periods are: Last 24 hours, Last 7 days (default), Last 30 days, Last 90 days and
Custom.
• API Calls: This widget lets you see blocked and alerted violations versus clean traffic. Since a single request may
contain numerous security violations, each such single action may act upon numerous violations.
• Top Attacks by Country: This widget lets you see the API and WAF violations by country of origin. A single API
request may violate both API and WAF rules and therefore may contain numerous violations.
• Top Attacked APIs: This widget lets you see your most attacked APIs. In addition:
• You can select multiple APIs, press Filter by Selection to have the dashboard show aggregated
detailed information about the selected APIs.
• You can search for a specific API or APIs.
• Top Attacked Endpoints: This widget lets you see your most attacked endpoints. In addition:
• You can select multiple endpoints, press Filter by Selection to have the dashboard show aggregated
detailed information about the selected endpoints.
• You can search for a specific endpoint or endpoints.
• API Violations Detected: This widget lets you see the detected API violations. An API request may violate both
API and WAF rules. In addition, you can download this widget as a PNG file by clicking .
• Other Violations Detected: This widget lets you see the detected WAF violations. An API request may violate
both API and WAF rules. In addition, you can download this widget as a PNG file by clicking .

API Security 29
 API Security

Inventory
The Inventory page is comprised of these tabs:

• Discovered APIs
• My APIs

API Security 30
 API Security

Discovered APIs
The Discovered APIs tab presents a predefined page containing widgets that give a quick informative view, and in
some widgets drill down capabilities, of the discovered APIs that are protected on your system. These widgets are:

• Hosts: This widget lets you see and set the API hosts you want to view or see them all.
• API Endpoints: The total number of API endpoints
• API Discovery Status: The total number of Baselined and In Progress APIs
• API Endpoints Data Labels: The total number of API endpoints with data labels, the total number of API
endpoints with sensitive data labels and the total number of API endpoints with non-sensitive data labels
• API Endpoints with Risks: The total number of API endpoints with risks, the total number of API endpoints with
OWASP API risks and the total number of API endpoints with other risks
• APIs Inventory: This widget lets you see a table listing of all the APIs discovered. The table indicates the
endpoints, the data labels for each endpoint, the API risks (see API Inventory), the date this API was discovered
and the status of discovery (baselined - All params have been discovered and final specification is ready, in
progress - Endpoint is still in learning phase or design issue - Endpoint is badly designed and dynamic
parameters are found. Further parameter discovery is stopped and the endpoint discovery for matching URLs is
skipped). You can search for specific endpoints using the Search field, filter the results shown in the widget by
clicking the Filters button, download the information to a CSV file by clicking and download the
information as a zip file containings Swagger specification files. Clicking on an endpoint, opens a page showing
you details about the endpoint. These details consist of the:
• API Specifications: Here you can see the Authentication Location (see API Inventory), and the Request
details (Query Parameters and Body). You can filter to see all object types or select the one you want to
see, see objects that are required/optional or all, and objects with data labels only, with sensitive data
labels only or all. In addition you can see the Response details (HTTP response code 500 and HTTP
response code 200). You can filter to see all object types or select the one you want to see, see objects
that are required/optional or all, and objects with data labels only, with sensitive data labels only or all.
You can download the details with the filters you set as a JSON file by clicking the Copy as JSON
button.
• API Instances: Here you can see the sampled API instances.
• API Hosts: This widget lets you see a list, by endpoint, of the discovered hosts. For each host the amount of API
endpoints is indicated. You can search for specific endpoints using the Search field. In addition, you can
download the information to a CSV file by clicking .
• Data Labels: This widget lets you see a list, by endpoint, of the discovered data category labels. For each data
category label the amount of API endpoints is indicated. You can search for specific endpoints using the Search
field. In addition, you can download the information to a CSV file by clicking .
• API Risks: This widget lets you see a list, by endpoint, of the API endpoints that carry sensitive data and have
unauthenticated risks and API endpoints with excessive data exposure risks. You can search for specific
endpoints using the Search field. In addition, you can download the information to a CSV file by clicking
.

API Security 31
 API Security

My APIs
The My APIs tab presents a predefined page containing widgets that give a quick informative view, and in some
widgets drill down capabilities, of the discovered APIs and manually uploaded APIs that are protected on your system.
These widgets are:

• Hosts: This widget lets you see and set the API hosts you want to view or see them all.
• Hosts: The total number of hosts
• API Resources: The total number of API resources
• API Endpoints: The total number of API endpoints
• APIs from the Source: The total number of OAS files, Discovered and Merged APIs (merged APIs are results of
the API Schema Protection solution that if you used it prior to using the new add-on solution)
• Unique Data Labels: The number of unique data labels
• APIs Inventory: This widget lets you see a table listing of all the APIs and endpoints. The table indicates the
APIs/Endpoints, the host for each API, the data labels for each API, the source of each API (OAS file, Discovered
or Merged) and the policy action (Default or Modified). You can search for specific endpoints using the Search
field, filter the results shown in the widget by clicking the Filters button, and download the information to a CSV
file by clicking . Clicking on an API, opens a list of the associated endpoints. You can delete an API by

clicking on .

In addition, you can upload an OAS file by clicking on the Add OAS File button. For more information, see
Adding an OAS File. For discovered APIs you can apply policies by clicking on the Download Swagger
Specification button, open the swagger and make the modifications, and then upload again using the Add OAS
File button. Once you have uploaded the swagger, you can see and edit the policies in the Policies page. For
more information, see Policies.

• API Hosts: This widget lets you see a list, by endpoint, of the discovered hosts. For each host the amount of API
endpoints is indicated. You can search for specific endpoints using the Search field. In addition, you can
download the information to a CSV file by clicking .
• Data Labels: This widget lets you see a list, by endpoint, of the discovered data category labels. For each data
category label the amount of API endpoints is indicated.

In addition, you can add an OAS file from this tab.

To add APIs:

1. Click the Add OAS File button. The Add OAS File page is displayed.
2. Under Swagger Details, drag and drop a swagger file or click Upload file and locate the OAS file you want to
upload.
3. Select it and click Open.
4. In Description, type a description that will help in recognizing the API in the dashboard.

If the OAS file already contains a description, it will appear in the field and you can modify it as desired.

5. In Apply to, select the host from the drop down.

6. In Base Path, select the relevant base path.

API Security 32
 API Security

If the OAS file contains one base path, it will appear in the field and you can not modify it.

If the OAS file contains multiple base paths and the selected base path contains variables, the Desired Base
Path field is displayed where you need to enter a base path that will replace the variables.

7. Under Set Violation Actions, select the action that should be taken when an New Paths, New Methods,
Missing Required Parameters and Invalid Parameters Data Type API violation attack occurs.

You can select the default action and each time the actions are modified under the Site-level Policy, in the
Policies page, they modify this current API as well. If you select a custom action for each API, it is not impacted
by the modification done on the Site Configuration page and can be modified after the API is added. For details
on how to edit an endpoint, see View API Details.

8. Click Add File.

API Security 33
 API Security

Policies
The Policies page is comprised these sections:

• Site-level Policy
• API-level Policy

API Security 34
 API Security

Site-level Policy
In this section, you can see a table of your websites. This table consists of columns showing, for each website, the
following violation types and the action that was set to be performed when the violation occurs.

• New Paths - Violations that occur when a request was sent to an undefined API path
• New Methods - Violations that occur when the URL was directed to an existing path but with an unspecified
method
• New Parameters - Violations that occur when the swagger requires you to supply a certain parameter in a certain
endpoint (usually defined as required: true), but the current request did not have this parameter supplied
• Missing Required Parameters - Violations that occur when the swagger requires you to supply a certain
parameter value in a certain endpoint (e.g. type: boolean), but the current request had no value for this
parameter.
• Invalid Parameters Data Type - Violations that occur when the swagger requires you to supply a certain
parameter value in a certain endpoint (e.g. type: boolean), but the current request had a different value for
this parameter (e.g. a number 123)
• Other Traffic - Violations that occur when the traffic does not belong to the APIs defined in the OAS file or is
integrated from API Discovery.

For each website you can edit the violation action values by clicking the Edit button. In addition, you can perform a
search for a particular website and filter the table to show only the desired violation types and the desired violation
action.

API Security 35
 API Security

API-level Policy
In this section, you can see a table of your APIs. This table consists of columns showing, for each API, its host and the
following violation types and the action that was set to be performed when the violation occurs.

• New Paths - Violations that occur when a request was sent to an undefined API path
• New Methods - Violations that occur when the URL was directed to an existing path but with an unspecified
method
• New Parameters - Violations that occur when the swagger requires you to supply a certain parameter in a certain
endpoint (usually defined as required: true), but the current request did not have this parameter supplied
• Missing Required Parameters - Violations that occur when the swagger requires you to supply a certain
parameter value in a certain endpoint (e.g. type: boolean), but the current request had no value for this
parameter.
• Invalid Parameters Data Type - Violations that occur when the swagger requires you to supply a certain
parameter value in a certain endpoint (e.g. type: boolean), but the current request had a different value for
this parameter (e.g. a number 123)

You can click on an API, which opens a list of associated endpoints that shows their set violation actions. For each API
or endpoint you can edit the violation action values by clicking the Edit button. In addition, you can perform a search
for a particular API or endpoint and filter the table to show only the desired violation types and the desired violation
action.

API Security 36
 API Security

Settings
The Settings page is comprised of these sections:

• API Discovery
• Data Classification
• API Authentication Discovery
• Excessive Data Exposure

API Security 37
 API Security

API Discovery
In this section, you can see a list of all your websites. For each website you can enable Discovery and Automatic
Integration.

Automatic integration enables integrating the discovered results with your existing APIs in order to start monitoring
and protecting the discovered APIs quickly. When activated, the discovered endpoints are added to the table in the My
APIs tab under Inventory. When disabled, the discovery results are only stored in the Discovered APIs tab under
Inventory.

Automatic integration is applied only on APIs for which new endpoints were discovered after automatic integration
was enabled.

If you enable API Discovery and then disable it:

• API Discovery stops the continuous learning process, but leaves the discovered endpoints intact.
• All APIs discovered and manually uploaded up to the disabling point will be shown.

If you enable Automatic Integration and API Discovery is enabled:

• If no additional endpoints were discovered by the discovery engine compared to the uploaded OAS file, no
information is presented.
• If API Discovery identifies an endpoint that did not exist in an uploaded OAS file, The API containing the
discovered endpoint is marked as added in the Source column in the My APIs tab.
• When the discovered results contain endpoints that already exist in an already manually uploaded OAS file, the
discovered endpoints are marked as duplicates, and do not change the violation actions settings of the existing
endpoint.
• If the existing manual uploaded OAS file is updated and the imported endpoints already exist in the discovered
APIs, the imported endpoints are grayed out (i.e. The currently active configuration takes precedence).

When an API is deleted:

• Any duplicate endpoints from any other API may become "active", but have an "Alert" policy defined for them.
This is in order not to block traffic if this is unwanted or unexpected.
• The settings in the Site Level Positive Security Model becomes active for that traffic and if it is in Blocking mode,
this API will be blocked.

If you experience unwanted results, you can:

• Mark them as Ignore Violations. This allows the traffic to pass through, as it was before the discovery process
found them.
• Delete them.

Discovery results are always integrated with violations actions set to Default. The Default policy for automatically
integrated APIs is Ignore for New Paths and New Methods violations and Alert for other violations. This way, no traffic
is blocked because of the integration. Imperva recommends changing this setting to Blocking mode.

API Security 38
 API Security

Data Classification
This section is only available for users with the Advanced license.

In this section, you can see a list of all the data labels. For each data label you can set it as sensitive and if it is visible.
In addition you can see the last date when these settings were modified.

When you set the data labels to Visible, they are displayed in the Discovered APIs tab under the Dashboards page and
in the Discovered APIs and My APIs tabs under the Inventory page.

API Security 39
 API Security

API Authentication Discovery

Application services implementing APIs must support and only serve calls that are authenticated by validating the
authentication information within the calls. Lack of authentication of API calls is considered a serious risk for APIs
especially if such APIs also carry sensitive data. As DevOps teams are constantly creating and updating APIs, it is
extremely important for security teams to have visibility into APIs and more importantly the state of the
authentication within these APIs.

The API Authentication Discovery feature identifies and baselines the authentication state of the APIs within your
environment.

• API Authentication State

• API Authentication Discovery Settings
• API Inventory
• API Authentication State and OWASP API Top 10
• Best Practices
• Default List of Authentication Locations

API Security 40
 API Security

API Authentication State

An API consists of a number of API endpoints. The calls made to the API endpoints carry the authentication
information at a certain location, referred to as Authentication Location. The authentication location could be within
the http headers, http url path parameters, http url query parameters, and http request body.

Typically the authentication location for all endpoints for an API remains the same. In certain exception scenarios, a
particular API endpoint may have a different authentication location compared to others within the same API.

Few examples of authentication locations are:

• HTTP request header called authorization (represented as http-req-header-authorization)

• HTTP request cookie header key called token (represented as http-req-header-cookie-token)
• HTTP request url query parameter called api-key (represented as http-req-url-query-api-key)

Using machine-learned heuristics, Imperva API Security builds the list of authentication locations for each site defined
in Imperva CloudWAF. As part of the discovery process, for each successful call, denoted by a 200 OK HTTP response
code, the system inspects for the presence of at least one of the authentication locations and a valid value.
Additionally, over a period of time, the discovery process builds enough confidence and subsequently tags the API
endpoint with its authentication state. There are three possible states:

• Unknown: When the system starts or when enough confidence has not been established, the API endpoint is in
this state.
• Authenticated: When the system has enough confidence with the identification of the authentication
information within the API calls, it is assigned this state.
• Unauthenticated: When the system has enough confidence about the absence of any authentication
information within the API calls, it is assigned this state.

The system also provides capabilities to add additional authentication locations and the ability to disable the feature
at both the site level or at an API endpoint level.

As part of the discovery process, API Security identifies the current risks within APIs in your environment. The state of
API authentication plays a direct role in the level of API Risk. The Authenticated state means no weight on the API
Risk. The Unauthenticated state means a high weight on the API Risk for an API Endpoint. Consider the scenario
where an API endpoint is Unauthenticated and also is categorized to carry sensitive PII data as part of the data
classification discovery process. This means a critical risk for the API endpoint and drastically increases overall API risk
level.

As part of the discovery and baselining process, the authentication state is assigned to an API endpoint after certain
confidence is achieved for its state. The algorithm considers a number of factors in an observation time window such
as:

• Total number of API Calls

• Unique number of API calls
• Unique number of Src IPs
• Unique number of values per authentication location (a.k.a token values)
• Count of API Calls that do not match any authentication location

API Security 41
 API Security

These factors are aggregated for a certain number of total API calls. Once the aggregated number is reached, various
conditions are evaluated for both authenticated and unauthenticated states. These cover scenarios such as a small
and large diversity of tokens from large and small distribution of sources, hit rate of calls with no match in
authentication locations, etc. The conditions lead to an aggregated confidence which beyond certain threshold tags
the API endpoint with its state. If no such confidence can be reached, API endpoint remains in the initial unknown
state.

API Security 42
 API Security

API Authentication Discovery Settings

All the settings and configurations related to the discovery of the API Authentication state are in the API Security
Settings page. The section is divided into two tab:

• Website Settings - In this tab, you can configure the location of the authentication information in your APIs. You
can enable or disable API authentication discovery for any listed website. For each enabled website, you can
include, or not, the authentication locations you want to include in the discovery process. You can view or add
exceptions and see the last modified date and by whom. In addition, you can add authentication locations from
websites not listed, perform search queries and filter the results.

Note: By default, there are a number of locations defined for every site. For each and every
successful API call being inspected for that site, the system looks for the presence of at least one
location and corresponding value. Hence there is no requirement to define the locations at an API
level or at an API endpoint level.

• Future Defaults - In this tab, you can enable authentication discovery for future websites that are onboarded.
You can configure the default settings applicable to those future websites such as include, or not, the
authentication locations you want to include in the discovery process, add authentication locations from
websites not listed, perform search queries and filter the results. In addition, you can delete authentication
location settings which are not used. When deleted it is removed from both the Future DefaultS and Website
Settings tabs.

• Add Authentication Locations

• Exceptions

API Security 43
 API Security

Add Authentication Locations

To add a new authentication location:

1. In the API Security Settings page, under the Website Authentication Location Settings section click the Website
Settings tab.
2. Click the The Add Add Authentication Location button. The Add Authentication Location window is
displayed.
3. In Location name, type the authentication location, in normalized format, of the authentication information in
your APIs. For more information on normalized format, see the below section.
4. In Applicable to, select if you want to include this location for all websites currently configured or to specific
websites.

If you select all websites, you can also set that this location is used for future websites that are onboarded. If
you select specific websites, you cannot set for future websites.

5. Click the Add Authentication Location button.

6. Click the Save Changes button (on the top of the page).

Normalized Format

The basic supported normalized format is:

Protocol-direction-entity_type-(>)parameter_name

Where:

Protocol:- The protocol of the event as seen on the wire (only http is supported)

Direction:- The direction of the event (request(req) side or response(rsp) side)

Entity-type:- The location where the parameter was seen. Possible values: path, query, body, header, cookie, set-
cookie

Example:

Header

Assuming a header called Authorization (headers are case insensitive)

http-req-header-Authorization

Cookie

Cookie: PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; _gat=1

http-req-Cookie-PHPSESSID

http-req-Cookie-csrftoken

API Security 44
 API Security

Query

URLPath: /api/v1/user?auth=1&user_name=joe

http-req-query->auth

http-req-query->user_name

Body

Json body example:

“token”:1,

“first_name”:”joe”,

“location”: { “country”:”England”}

Normalized keys:

http-req-body->token

http-req-body->first_name

http-req-body->location->country

SOAP Example:

SOAP is slightly different from the others as there is a layer in the body itself before the parameters are defined. The
layer is called the Envelope layer.

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>

<auth>abcd</auth>

</soapenv:Body>

</soapenv:Envelope>

Normalized key:

http-req-body->Envelope->Body->auth

API Security 45
 API Security

API Security 46
 API Security

Exceptions

Since you may have different applications and environments, you may need to add exceptions in cases such as:

• You are already aware that an API does not have authentication but considers it as not risky due to it being
protected by an IP based ACL rule.
• The location that you would like to define to be searched by the system is not supported by the system.
• You believe that there are false positives and would like to ignore this feature for specific API endpoints.

Exceptions are per site and are limited to disabling or enabling the API authentication discovery process for specific
API endpoints.

To add exceptions to the discovery process:

1. Under the Website Settings tab, click next to the desired website/location.
2. Select Add Exception. The Add Exception window is displayed.
3. For each listed API endpoint, select the Enable checkbox, or clear it.
4. Click the Add Exception button.

API Security 47
 API Security

API Inventory

In the API Security Inventory > Discovered APIs page, under the API Inventory section, the table contains a column
called API Risks that indicates, for each endpoint, if the API was identified to be Unauthenticated. If you included a

new authentication location and want the risk to be relearned, click and select Relearn API risks. This restarts
the learning process to identify the authentication state for this particular endpoint. Additionally the filters provide an
option to filter the data within the Inventory table using filters such as API Risks, Authentication State, etc.

Clicking on the API endpoint, opens the details page for that endpoint. In this page you can see the Authentication
state for the endpoint. Based on the current state, relevant information is displayed as follows:

• An API Endpoint for which authentication information was identified.

• An API Endpoint which is determined to be unauthenticated.
• An API Endpoint with authentication state discovery in progress

API Security 48
 API Security

API Authentication State and OWASP API Top 10

OWASP API Top 10 defines the critical API vulnerabilities observed in application API implementations. The
unauthenticated API risk is part of OWASP API Top 10 and is defined by "API2: Broken User Authentication"

API Security 49
 API Security

Best Practices

Imperva recommends following these best practice when configuring API Authentication Discovery:

• Turn on the feature for your site. This starts the discovery of the authentication state with the out-of-box list of
authentication location entities.
• Once the state discovery is completed, generate a filter in the Inventory page to identify all the APIs that have
unauthenticated API Risks.
• Work with your development team to identify if there are additional authentication locations that need to be
considered. If you obtain a new list, add it using the Add Authentication Location button in the API Security
Settings page.
• If the development team has provided a justification for a particular or a set of API endpoints to not have
authentication, per your organization security policy, add an exception for those API endpoints using the Add
Exceptions button in the API Security Settings page
• Once an acceptable discovery has been achieved, start to generate your API Risk reports on regular time
intervals to assess the risks of your API environment.

API Security 50
 API Security

Default List of Authentication Locations

The following is the list of the out of box authentication locations:

Parameter name Location

token header

x-token header

access_token header

x-access_token header

access-token header

x-access-token header

accesstoken header

x-accesstoken header

api_key header

x-api_key header

apikey header

x-apikey header

API Security 51
 API Security

Parameter name Location

api-key header

x-api-key header

secret-key header

x-secret-key header

secret_key header

x-secret_key header

secretkey header

x-secretkey header

auth header

x-auth header

token query_string

access_token query_string

access-token query_string

accesstoken query_string

API Security 52
 API Security

Parameter name Location

api_key query_string

apikey query_string

api-key query_string

secret-key query_string

secret_key query_string

secretkey query_string

authorization query_string

auth query_string

token post_body

access_token post_body

access-token post_body

accesstoken post_body

api_key post_body

apikey post_body

API Security 53
 API Security

Parameter name Location

api-key post_body

secret-key post_body

secret_key post_body

secretkey post_body

authorization post_body

auth post_body

authorization header

x-authorization header

sig header

signature header

sig query_string

signature query_string

sig post_body

signature post_body

API Security 54
 API Security

API Security 55
 API Security

Excessive Data Exposure

Excessive Data Exposure in APIs implies that APIs in your application environment are providing excessive data in
response to API call requests. An application client such as a web application or a mobile application makes an API
request to your application service. Based on the type of request, the response may contain data that is returned back
to the client. The client then uses this data to provide the required information to the end user. If an application is
designed such that it is returning huge amounts of data for each API call request, it may lead to potential data leak.
Such an API design is qualified to be risky towards excessive data exposure.

Excessive Data Exposure has been assigned as the 3rd of the OWASP API Top 10 due to the nature of this vulnerability
and the impact it could cause for business applications. A real world example of this is the exposure of the PII
information in Amazon’s Ring Neighbors App.

• Identifying APIs with Excessive Data Exposure

• Excessive Data Exposure Settings
• API Inventory
• Best Practices
• Default Thresholds

API Security 56
 API Security

Identifying APIs with Excessive Data Exposure

An API consists of a number of API endpoints. Imperva API Security discovers these endpoints and also learns about
the structure and the data type being returned for each of these endpoints. The data being returned is also classified
via the data classification engine. Within an API call response, we may have the following:

If the number of parameters for each of the three groups exceeds their respective thresholds, the API endpoint is
categorized to be vulnerable towards excessive data exposure. The thresholds are customizable by the customers for
each of the endpoints.

API Security 57
 API Security

Excessive Data Exposure Settings

All the settings and configurations related to the excessive data exposure are in the API Security Settings page. The
settings are configured at a site level. For a site that would be on-boarded in the future, you can use the Future
Defaults section to apply only the sites which are on-boarded in future.

• Setting Up Excessive Data Exposure

• Exceptions

API Security 58
 API Security

Setting Up Excessive Data Exposure

To setup excessive data exposure:

1. In the API Security Settings page, under the Website Excessive Data Exposure Settings section click the Website
Settings tab.
2. For each website set values for:
◦ Response Parameters - The number of response parameters that when exceeded categorizes the
endpoint with excessive data exposure risk. This number cannot be less than 1.
◦ With Data Labels - The number of parameters with a data label that when exceeded categorizes the
endpoint with excessive data exposure risk. This number cannot be less than 1 or greater than the
number set for Response Parameters.
◦ With Sensitive Data Labels - The number of parameters with a sensitive data label that when exceeded
categorizes the endpoint with excessive data exposure risk. This number cannot be less than 1 or greater
than the number set for With Data Labels.
◦ Enable - Select this check box to set excessive data exposure detection for this website.
3. Click the Save Changes button (on the top of the page).

API Security 59
 API Security

Exceptions

Since you may have different applications and environments, you may need to add exceptions in cases such as:

• The customer is already aware that an API endpoint has a large number of response parameters and is designed
in that way due to specific needs of a business partner who is consuming such API response data.
• The customer is using a legacy application which is indeed returning a large number of parameters with
sensitive data.

Exceptions are per site and are limited to disabling or enabling Excessive Data Exposure for specific API endpoints and
changing the thresholds.

To add exceptions to the Excessive Data Exposure settings:

1. Under the Website Settings tab, click next to the desired website.
2. Select Add Exception. The Add Exception window is displayed.
3. For each listed API endpoint, select the Enable checkbox, or clear it and change the thresholds as desired.
4. Click the Add Exception button.

API Security 60
 API Security

API Inventory

In the API Security Inventory > Discovered APIs page, under the API Inventory section, the table contains a column
called API Risks that indicates, for each endpoint, if the API was identified to have excessive data exposure risk. If you

included a new excessive data exposure risk and want the risk to be relearned, click and select Relearn API
risks. This restarts the learning process to identify the authentication state for this particular endpoint. Additionally
the filters provide an option to filter the data within the Inventory table using filters such as API Risks, etc.

API Security 61
 API Security

Best Practices

Imperva recommends following these best practice when configuring Excessive Data Exposure:

• Turn on the feature for your site. This starts the identification of API Endpoints with excessive data exposure
risk.
• Once the identification is completed, generate a filter in Inventory to identify all the APIs that have excessive
data exposure API risk.
• Work with your development team to identify if there are valid reasons for these API endpoints to return
excessive data.
• If the development team has provided a justification for a particular or a set of risky API endpoints, per your
organization's security policy, add an exception for those API endpoints using the Add Exceptions option in
settings.
• Start to generate your API Risk reports on regular cadence to assess the risks of your API environment.

API Security 62
 API Security

Default Thresholds

The following are the default thresholds:

• Number of response parameters: 100

• Number of parameters with data labels: 20
• Number of parameters with sensitive data labels: 10

API Security 63
 API Security

Verification
The API Security Verification page is designed to help with auditing security best practices and to verify basic security
vulnerabilities based on the OpenAPI Specification file. There are two workflows under Verification:

• Providing the OAS file manually. This enables you to perform Spec file assessment and/or test package
generation.
• Choosing the hosts that have baselined APIs to perform the test package generation only.

• OAS File Assessment

• Generating Assessment Report
• View Reports
• OAS File Security Tests
• Generating Test Package
• Test Execution
• API Calls for Verification Sequence

API Security 64
 API Security

OAS File Assessment

The Spec file assessment is done to audit security best practices and determine problematic issues in the Spec file.
The system internally runs multiple checks to analyze the specification and provides a risk calculation in the form of a
report.

API Security 65
 API Security

Generating Assessment Report

To generate the Assessment report:

1. Under API Security, click on the Verification tab.

2. Click on Add API Bundle. The Add API Bundle page is displayed.
3. Select Add manually, and upload the OpenAPI Specification file or a zip file consisting of multiple specification
files.
4. Select the Generate OAS assessment report check box and click Generate. The Verification page is displayed
showing the uploaded file or bundle with the test status showing In progress. Depending on the number of
spec files in the file bundle or the size of the specification file, the test generation may take up to five minutes.

API Security 66
 API Security

View Reports
Once the test generation is complete, the tests status changes to Ready.

To execute the test:

1. Click next to the desired file and select Download Assessment Test to download the test package.
2. Extract the zip file and go to that directory.
3. Go to the sparc_report directory.
4. Double click on the index.html file to open the report.

Note: The Assessment test can only be run for manually uploaded OpenAPI Specification files and
not for discovered APIs.

API Security 67
 API Security

OAS File Security Tests

The second type of tests under Verification involve generating a security test package based on input OpenAPI
Specification file. This test package contains necessary code to execute the tests against applications whose OpenAPI
Spec file was given as input. Then you can run these Security tests against the application. The current version of the
backend tool that executes the tests is called ImpACT and makes use of FuzzDB as the fuzzing pattern database.

The test produces an easy to understand report with a summary and detailed information on vulnerabilities found
during the execution of the tests. This may include findings such as authorization/authentication bypasses, SQL and
OS command injections, path traversal issues and other OWASP Top 10 API vulnerabilities. The report also provides
links to commands that can easily reproduce the issue.

To execute these tests, you need to have Python version 3.8 or greater and pip installed on your machine.

API Security 68
 API Security

Generating Test Package

To generate the test package:

1. Under API Security, click on the Verification tab.

2. Click on Add API Bundle. The Add API Bundle page is displayed.
3. Select Add manually, and upload the OpenAPI Specification file or a zip file consisting of multiple specification
files manually.
4. Select the desired test and click Generate. The Verification page is displayed showing the uploaded file or
bundle with the test status showing In progress. Depending on the number of spec files in the file bundle or the
size of the specification file, the test generation may take up to five minutes.

-OR-

Select Discovered APIs, to have the system consume the generated spec file from the backend based on the
discovered APIs to generate the test package. Select the Generate security test check box and click Generate.
The Verification page is displayed showing the uploaded file or bundle with the Security test status showing In
progress. Depending on the number of spec files in file bundle or the size of specification file, the test
generation may take up to five minutes.

5. Follow the procedure described in View Reports.

API Security 69
 API Security

Test Execution
Once the test generation is complete, the test status changes to Ready.

To execute the test:

1. Click next to the desired file and select Download Test to download the test package.
2. Move the downloaded file to a resource/system from where the test application can be run.

Note: The application has to be the one whose OpenAPI Specification file was used to generate the
test package.

3. Extract the zip file and go to that directory.

4. Refer to the file impact_user_guide.pdf for further instructions on how to run the tests.
5. After the tests are successfully finished the HTML based report containing the summary and found issues can be
found in the new_report folder. The HTML based report is saved with the name
report_summary_<timestamp>.html.
6. Double click on the html file to open the report.

API Security 70
 API Security

API Calls for Verification Sequence

The sequence of API calls for verification:

Manually Uploaded File:

1. Retrieve all action types.

2. Upload the OAS file with the required actions types.
3. Poll Retrieve all actions until status is done for the action.
4. Once status is done for each action type, Call Download the reports API with the Action ID and the Action Type
ID.
5. If action needs to be deleted then call Delete the action with the Action ID.

Discovery Flow:

1. Upload the discovered APIs.

2. Perform steps 3 to 5 from the Manually Uploaded File procedure.

API Security 71
 API Security

Mass Assignment Vulnerability

Mass assignment implies supplying more parameters than what is usually observed within legitimate calls for an API
accessed by a user. A vulnerable API implementation would consume the additional parameters and assign them
internally. For example, updating the respective columns in a database record with values assigned to the additional
parameters.

Mass assignment has been assigned as the 6th of the OWASP API Top 10 due to the nature of this vulnerability and the
impact it could cause for business applications. A real world example of this is the Harbor Cloud Native Registry
privilege escalation.

• Detection and Protection

• Policies and Security Events
• Default Policy Configuration
• Best Practices

API Security 72
 API Security

Detection and Protection

Imperva Cloud WAF detects mass assignment attempts and protects against these malicious API calls using the API
Schema Protection feature. As part of this feature, you can upload the specification for an API or use the continuous
API discovery feature to automatically integrate discovered APIs into schema protection. A new violation type called
New Parameters is provided. By selecting this violation type and choosing the appropriate action, you can protect
your APIs against mass assignment.

API Security 73
 API Security

Policies and Security Events

To protect against mass assignment:

1. Go to the API Security Policies page.

2. Under the Site-level Policy and API-level policy sections, click the Edit button next to the desired website, API or
endpoint.
3. Select the desired action value for the New Parameters violation type.
4. Click Save.
5. When an API call violates the New Parameters condition, a security event is generated. In the Imperva Cloud
Security Console, on the sidebar, click Security Events.
6. Locate the API Specification Violation section and verify it is set to INVALID_PARAM_NAME.

API Security 74
 API Security

Default Policy Configuration

The New Parameters violation type is set to Ignore by default in both Site-level Policy and API-level Policy sections.

API Security 75
 API Security

Best Practices
Imperva recommends following these best practice when configuring Mass Assignment:

• Build a baseline API specification either by uploading the latest specification from the developers or using the
API Discovery’s Automatic Integration feature
• Once the baselined APIs are available, set the New Parameters violation type to Alert
• Review any of the violation security events to ensure they are indeed true positives.
• Once the confidence of the true positives is established, change the violation action to Block Request.

API Security 76
 API Security

Imperva Data Classification

Data classification gives you visibility over which API endpoint transfers PII information and the ability to decide on
the appropriate security level for each API endpoint according to the sensitivity of the data returned. It is enabled by
default for all endpoints (discovery and manual upload), and relies on both requests and responses. Data
classification is shown by labels that are added to the endpoint. Some labels are considered more sensitive and
others less.

The following table lists the supported data labels.

Supported Data Labels

ID Data Label Category Data Label Subcategory

1 address country

2 address city-usa

3 address state-usa

4 address zipcode-usa

5 address streetaddr

6 automotive vin

7 automotive sellercodes

8 financialinfo bankaccountname

9 financialinfo bankaccountnum

10 financialinfo cashbalance

API Security 77
 API Security

ID Data Label Category Data Label Subcategory

11 financialinfo iban

12 financialinfo bankroutingnum-usa

13 creditcard cardnum

14 creditcard cvv

15 creditcard encodedccinfo

16 generalinfo email

17 generalinfo phonenum

18 govtid dl-usa

19 govtid corporatenum-jpn

20 govtid passportnum

21 govtid individualnum-jpn

22 govtid natlid-isr

23 govtid natlinsurancenum-uk

24 govtid ssn-aus

API Security 78
 API Security

ID Data Label Category Data Label Subcategory

25 govtid sin-can

26 govtid ssn-usa

27 govtid brazilrg

28 govtid brazilcpf

29 govtid brazilcnpj

30 govtid ssn-italy

31 ipaddress ipv4

32 ipaddress ipv6

33 name firstorlastname

34 name fullname

35 sentence english

API Security 79
 API Security

API Security API

Imperva enables you to manage API Security using APIs.

Note: For a dynamic version of the Swagger content that can be used to Try it out, see API Security
Protection API Definition.

Authentication

In order to use the API, the client must be authenticated by Imperva. To authenticate, send your API ID and API key
using the x-API-Id and x-API-Key request headers. For example:

x-API-Id: 12345

x-API-Key: 123**************789

To create and manage API keys with granular permissions and sub account access, see API Key Management.

The API functionality available for your use is based on the roles and permissions assigned to your user. Use of the API
does not require additional permissions beyond that.

Integration

To integrate easily with Imperva API Security, Imperva provides open source tools allowing customers to manage API
Security seamlessly and easily into their CI\CD process or into their API lifecycle management. These tools are hosted
in GitHub and managed by the open source community. For additional information, see https://github.com/imperva/
cloud-api-security-integration.

API Security 80
 API Security

API Security API Definition

This topic describes the API for Imperva Advanced API Security. For full feature documentation, see Imperva API
Security.
More information: https://helloreverb.com
Contact Info: [email protected]
Version: 1.0.0
All rights reserved
Access
http://apache.org/licenses/LICENSE-2.0.html
Methods
Models

Table of Contents

API

• post /api/{siteId}
• delete /api/{siteId}/{apiId}
• get /api
• get /api/{siteId}
• get /api/{siteId}/all
• get /api/{siteId}/{apiId}
• get /api/file/{siteId}/{apiId}
• post /api/{siteId}/{apiId}

DiscoveryAccountSettings

• post /v2/discovery/account/settings/auth-parameter-location
• delete /v2/discovery/account/settings
• get /v2/discovery/account/settings
• post /v2/discovery/account/settings

DiscoveryHosts

• get /v2/discovery/hosts

DiscoveryInventory

• get /v2/discovery/inventory/endpoints/files
• get /v2/discovery/inventory/endpoints
• get /v2/discovery/inventory/endpoints/{endpointId}
• delete /v2/discovery/inventory/endpoints/risks

DiscoverySiteSettings

• get /v2/discovery/sites/{siteId}/settings
• get /v2/discovery/sites/settings

API Security 81
 API Security

• post /v2/discovery/sites/{siteId}/settings
• post /v2/discovery/sites/settings

DiscoveryStatistics

• get /v2/discovery/statistics/classification/from/{from-timestamp}/to/{to-
timestamp}
• get /v2/discovery/statistics/usage/from/{from-timestamp}/to/{to-timestamp}
• get /v2/discovery/statistics/geolocation/from/{from-timestamp}/to/{to-
timestamp}
• get /v2/discovery/statistics/volume/from/{from-timestamp}/to/{to-timestamp}

Endpoint

• get /endpoint/{apiId}
• get /endpoint/{apiId}/{endpointId}
• post /endpoint/{apiId}/{endpointId}

SiteConfiguration

• get /config/site
• get /config/site/{siteId}
• post /config/site/{siteId}

Verification

• delete /v2/shift-left/actions/{actionId}
• get /v2/shift-left/actions/{actionId}/actionType/{actionTypeId}
• get /v2/shift-left/actions/action-types
• get /v2/shift-left/actions
• post /v2/shift-left/files/discovery
• post /v2/shift-left/files/oas

Up
post /api/{siteId}
Add an API (addApi)
Adds an API specification to a site

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

Consumes
This API call consumes the following media types via the Content-Type request header:

• multipart/form-data

API Security 82
 API Security

Form parameters
apiSpecification (required)
Form Parameter — format: binary
basePath (required)
Form Parameter —
description (required)
Form Parameter —
oasFileName (required)
Form Parameter —
specificationViolationAction (required)
Form Parameter —
validateHost (required)
Form Parameter —
violationActions (required)
Form Parameter —

Return type
AddApiResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"duplicateEndpointsList" : [ {
"fullPath" : "/api/{param}",
"method" : "GET",
"id" : 1234567890
}, {
"fullPath" : "/api/{param}",
"method" : "GET",
"id" : 1234567890
} ],
"resultMessage" : "API 10 was added successfully",
"apiId" : 1234
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 83
 API Security

Responses

200

Success AddApiResponse

400

Bad request SimpleTextErrorResponse

409

API Conflict SimpleTextErrorResponse

422

Failed to parse the API specification document ParserErrorResponse

500

Internal error SimpleTextErrorResponse

Up
delete /api/{siteId}/{apiId}
Delete an API (deleteApi)
Deletes an API from a site in the account

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
siteId (required)
Path Parameter — The site ID format: int64

Return type
SimpleTextSuccessResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : "value"
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

API Security 84
 API Security

• application/json

Responses

200

Success SimpleTextSuccessResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
get /api
Retrieve all APIs for the account (getAllApis)
Retrieves details of all protected APIs for all sites in the account

Return type
GetApisResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : [ {
"apiSource" : "USER",
"hostName" : "example.com",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"creationTime" : 1556735907,
"siteId" : 1234567,
"siteName" : "example.com",
"description" : "This is an example API",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907,
"specificationViolationAction" : "ALERT_ONLY"
}, {

API Security 85
 API Security

"apiSource" : "USER",
"hostName" : "example.com",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"creationTime" : 1556735907,
"siteId" : 1234567,
"siteName" : "example.com",
"description" : "This is an example API",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907,
"specificationViolationAction" : "ALERT_ONLY"
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetApisResponse

500

Internal error SimpleTextErrorResponse

Up
get /api/{siteId}
Retrieve all APIs for a site (getAllSiteApis)
Retrieves details of all protected APIs for a specific site in the account

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

API Security 86
 API Security

Return type
GetApisResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : [ {
"apiSource" : "USER",
"hostName" : "example.com",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"creationTime" : 1556735907,
"siteId" : 1234567,
"siteName" : "example.com",
"description" : "This is an example API",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907,
"specificationViolationAction" : "ALERT_ONLY"
}, {
"apiSource" : "USER",
"hostName" : "example.com",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"creationTime" : 1556735907,
"siteId" : 1234567,
"siteName" : "example.com",
"description" : "This is an example API",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907,
"specificationViolationAction" : "ALERT_ONLY"
} ]
}

API Security 87
 API Security

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetApisResponse

500

Internal error SimpleTextErrorResponse

Up
get /api/{siteId}/all
Retrieve all APIs and endpoints for a site (getAllSiteApisWithEndpoints)
Retrieves details of all protected APIs and their endpoints for a specific site in the account

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

Return type
GetApisWithEndpointsResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : [ {
"apiSource" : "USER",
"hostName" : "example.com",
"endpoints" : [ {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",

API Security 88
 API Security

"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
}, {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
} ],
"creationTime" : 1556735907,
"siteName" : "example.com",
"description" : "This is an example API",
"specificationViolationAction" : "ALERT_ONLY",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"siteId" : 1234567,
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,

API Security 89
 API Security

"lastModified" : 1556735907
}, {
"apiSource" : "USER",
"hostName" : "example.com",
"endpoints" : [ {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
}, {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
} ],

API Security 90
 API Security

"creationTime" : 1556735907,
"siteName" : "example.com",
"description" : "This is an example API",
"specificationViolationAction" : "ALERT_ONLY",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"siteId" : 1234567,
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetApisWithEndpointsResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
get /api/{siteId}/{apiId}
Retrieve an API (getApi)
Retrieves details of a specific API

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
siteId (required)

API Security 91
 API Security

Path Parameter — The site ID format: int64

Return type
GetApiResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"apiSource" : "USER",
"hostName" : "example.com",
"oasFileName" : "bank.yaml",
"basePath" : "/api",
"creationTime" : 1556735907,
"siteId" : 1234567,
"siteName" : "example.com",
"description" : "This is an example API",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"lastModified" : 1556735907,
"specificationViolationAction" : "ALERT_ONLY"
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetApiResponse

400

Bad request SimpleTextErrorResponse

API Security 92
 API Security

500

Internal error SimpleTextErrorResponse

Up
get /api/file/{siteId}/{apiId}
Download the API's OAS file, which was manually uploaded or automatically discovered. If the API source is mixed, the
result is the manually uploaded file. (getApiFile)
Download the manually uploaded or automatically discovered OAS file for a specific API. If the API source is mixed, the
result is the manually uploaded file.

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
siteId (required)
Path Parameter — The site ID format: int64

Return type
DownloadApiSpecificationDtoResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : "value"
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success DownloadApiSpecificationDtoResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

API Security 93
 API Security

Up
post /api/{siteId}/{apiId}
Update an API (updateApi)
Updates any or all of the optional parameters.

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
siteId (required)
Path Parameter — The site ID format: int64

Consumes
This API call consumes the following media types via the Content-Type request header:

• multipart/form-data

Form parameters
apiSpecification (optional)
Form Parameter — format: binary
description (optional)
Form Parameter —
oasFileName (optional)
Form Parameter —
specificationViolationAction (optional)
Form Parameter —
validateHost (optional)
Form Parameter —
violationActions (optional)
Form Parameter —

Return type
AddApiResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"duplicateEndpointsList" : [ {
"fullPath" : "/api/{param}",
"method" : "GET",
"id" : 1234567890
}, {
"fullPath" : "/api/{param}",
"method" : "GET",

API Security 94
 API Security

"id" : 1234567890
} ],
"resultMessage" : "API 10 was added successfully",
"apiId" : 1234
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success AddApiResponse

400

Bad request SimpleTextErrorResponse

409

API Conflict SimpleTextErrorResponse

422

Failed to parse the API specification document ParserErrorResponse

500

Internal error SimpleTextErrorResponse

Up
post /v2/discovery/account/settings/auth-parameter-location
Add authentication location (addAuthLocation)

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body AuthParameterLocationDto (optional)
Body Parameter — Authentication location details

API Security 95
 API Security

Return type
AuthParameterLocationResponse

Example data
Content-Type: application/json
{
"data" : [ {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
}, {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success AuthParameterLocationResponse

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
delete /v2/discovery/account/settings
Delete only the removed discovery account settings (deleteDiscoveryAccountSettings)
Delete only the removed discovery account settings

API Security 96
 API Security

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body DiscoveryAccountSettings (optional)
Body Parameter — Discovery Account Settings

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

204

Success

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/account/settings
Retrieve the discovery account settings (getDiscoveryAccountSettings)
Retrieve the discovery account settings

Return type
GetDiscoveryAccountSettingsResponse

Example data
Content-Type: application/json
{
"data" : {
"dataLabelSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"visible" : true,

API Security 97
 API Security

"dataLabel" : "ssn",
"lastModifiedUser" : "John Doe",
"sensitive" : true,
"lastModified" : 1556735907
}, {
"auditString" : "auditString",
"accountId" : 12345,
"visible" : true,
"dataLabel" : "ssn",
"lastModifiedUser" : "John Doe",
"sensitive" : true,
"lastModified" : 1556735907
} ],
"authenticationEnabled" : true,
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
}
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 98
 API Security

Responses

200

Success GetDiscoveryAccountSettingsResponse

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
post /v2/discovery/account/settings
Update only the changed discovery account settings (updateDiscoveryAccountSettings)
Update only the changed discovery account settings

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body DiscoveryAccountSettings (optional)
Body Parameter — Discovery Account Settings

Return type
GetDiscoveryAccountSettingsResponse

Example data
Content-Type: application/json
{
"data" : {
"dataLabelSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"visible" : true,
"dataLabel" : "ssn",
"lastModifiedUser" : "John Doe",
"sensitive" : true,
"lastModified" : 1556735907
}, {
"auditString" : "auditString",
"accountId" : 12345,

API Security 99
 API Security

"visible" : true,
"dataLabel" : "ssn",
"lastModifiedUser" : "John Doe",
"sensitive" : true,
"lastModified" : 1556735907
} ],
"authenticationEnabled" : true,
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
}
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetDiscoveryAccountSettingsResponse

400

Bad request ApiFailureResponse

API Security 100

 API Security

500

Internal error ApiFailureResponse

Up
get /v2/discovery/hosts
Retrieve account's discovered hosts (getHosts)

Return type
GetHostsResponse

Example data
Content-Type: application/json
{
"data" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetHostsResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/inventory/endpoints/files
Download all OAS files of the discovered APIs to a compressed ZIP file (getDiscoveredApiFiles)

API Security 101

 API Security

Download all OAS files of the discovered APIs, for all hosts or selected hosts in the query, to a compressed ZIP file. The
ZIP file format is account-&lt;account_id&gt;-api-files.zip and the ZIP file name format is &lt;host_name&gt;-
&lt;base_path&gt;-discovery.json. Underscore is used as the delimiter for the basePath.

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/zip

Responses

200

Success

404

Not Found ApiFailureResponse

500

Internal Server Error ApiFailureResponse

Up
get /v2/discovery/inventory/endpoints
Retrieve all discovered endpoints (getDiscoveredEndpoints)
Retrieve all discovered endpoints for the account or for the specified hosts. If no host id is provided - retrieve all
discovered endpoints for all hosts

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Return type
GetDiscoveredEndpointsResponse

Example data
Content-Type: application/json
{
"data" : {
"summary" : {

API Security 102

 API Security

"numberOfLabels" : 7,
"numberOfEndpointsWithRisks" : "{"OWASP": 1,"other": 20"}",
"numberOfEndpoints" : 2,
"numberOfResources" : 5,
"numberOfApiDiscoveryStatuses" : "{"IN_PROGRESS": 1,"BASELINED": 20"}",
"numberOfEndpointsWithDataLabels" : "{"sensitive": 2,"non-sensitive": 5","t
otal": 7"}",
"numberOfHosts" : 5
},
"endpointsNumberByRisk" : [ {
"numberOfEndpoints" : 1,
"risk" : "unauthenticated"
}, {
"numberOfEndpoints" : 1,
"risk" : "unauthenticated"
} ],
"endpoints" : [ {
"hostName" : "example.com",
"authenticationInfo" : {
"authParameterLocations" : [ {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
}, {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
} ],
"status" : "status"
},
"method" : "GET",
"resource" : "/api/users",
"hostId" : 12345,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false
} ],
"discoveryDate" : 1657886850000,
"risks" : [ "risks", "risks" ],
"siteId" : 1234567,
"riskTypes" : [ "OWASP", "OWASP" ],
"id" : 1234567890,

API Security 103

 API Security

"risksInfo" : [ {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
}, {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
} ],
"dataExposureInfo" : {
"status" : "status"
},
"status" : "BASELINED"
}, {
"hostName" : "example.com",
"authenticationInfo" : {
"authParameterLocations" : [ {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
}, {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
} ],
"status" : "status"
},
"method" : "GET",
"resource" : "/api/users",
"hostId" : 12345,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false
} ],
"discoveryDate" : 1657886850000,
"risks" : [ "risks", "risks" ],
"siteId" : 1234567,
"riskTypes" : [ "OWASP", "OWASP" ],
"id" : 1234567890,
"risksInfo" : [ {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",

API Security 104

 API Security

"risk" : "EXCESSIVE_DATA_EXPOSURE"
}, {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
} ],
"dataExposureInfo" : {
"status" : "status"
},
"status" : "BASELINED"
} ],
"endpointsNumberByHost" : [ {
"hostName" : "example.com",
"numberOfEndpoints" : 0,
"hostId" : 12345
}, {
"hostName" : "example.com",
"numberOfEndpoints" : 0,
"hostId" : 12345
} ],
"endpointsNumberByLabel" : [ {
"numberOfEndpoints" : 6,
"label" : "generalinfo:email"
}, {
"numberOfEndpoints" : 6,
"label" : "generalinfo:email"
} ]
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetDiscoveredEndpointsResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

API Security 105

 API Security

Up
get /v2/discovery/inventory/endpoints/{endpointId}
Retrieve detailed information for the endpoint (getEndpointDrillDown)

Path parameters
endpointId (required)
Path Parameter — endpoint ID format: int64

Return type
GetEndpointDrillDownResponse

Example data
Content-Type: application/json
{
"data" : {
"hostName" : "example.com",
"request" : {
"queryParamList" : [ {
"dataTypes" : "["type":"String","children":[ {\n "name": "id",
\n "dataTypes": ["type" : "String",\n] "required": true,\
n "labels": [\n {\n "name": "generalinfo:email",
\n "sensitive": false,\n "visible": true\n }
\n ]\n }]]",
"name" : "id",
"required" : false,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false
} ]
}, {
"dataTypes" : "["type":"String","children":[ {\n "name": "id",
\n "dataTypes": ["type" : "String",\n] "required": true,\
n "labels": [\n {\n "name": "generalinfo:email",
\n "sensitive": false,\n "visible": true\n }
\n ]\n }]]",
"name" : "id",
"required" : false,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false

API Security 106

 API Security

} ]
} ],
"contentTypeToRequestBody" : {
"key" : [ null, null ]
}
},
"authenticationInfo" : {
"authParameterLocations" : [ {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
}, {
"useForFutureWebSites" : true,
"siteIds" : "1234567",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http-req-header-x-jwt"
} ],
"status" : "status"
},
"method" : "GET",
"resource" : "/api/users",
"responses" : {
"key" : {
"contentTypeToResponseBody" : {
"key" : [ null, null ]
}
}
},
"endpointStatisticsSummary" : {
"numberOfParametersWithDataLabels" : "{"sensitive": 2,"non-sensitive": 5","
total": 7"}",
"numberOfParametersByDataLabel" : {
"key" : 0
}
}
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 107

 API Security

Responses

200

Success GetEndpointDrillDownResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

Up
delete /v2/discovery/inventory/endpoints/risks
Relearn risk data (relearnRisk)
Deletes the current risk data and adds new risk data by relearning

Query parameters
endpointIds (optional)
Query Parameter — endpointIds

Return type
ApiSuccessResponse

Example data
Content-Type: application/json
{
"data" : { },
"meta" : { }
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success ApiSuccessResponse

API Security 108

 API Security

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/sites/{siteId}/settings
Retrieve discovery settings for a site (getSiteDiscoverySettings)
Retrieve discovery settings for a site

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

Return type
GetSiteDiscoverySettingsResponse

Example data
Content-Type: application/json
{
"data" : {
"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,

API Security 109

 API Security

"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,
"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetSiteDiscoverySettingsResponse

API Security 110

 API Security

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/sites/settings
Retrieve the discovery settings for all sites in the account (getSitesDiscoverySettings)
Retrieve the discovery settings for all sites in the account

Return type
GetSiteDiscoverySettingsListResponse

Example data
Content-Type: application/json
{
"data" : [ {
"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",

API Security 111

 API Security

"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,
"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907
}, {
"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {

API Security 112

 API Security

"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,
"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 113

 API Security

Responses

200

Success GetSiteDiscoverySettingsListResponse

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
post /v2/discovery/sites/{siteId}/settings
Update the site's discovery settings (updateOneSiteDiscoverySettings)
Update the site's discovery settings with one of the optional parameters for each site

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body SiteDiscoverySettings (optional)
Body Parameter — Discovery settings

Return type
GetSiteDiscoverySettingsResponse

Example data
Content-Type: application/json
{
"data" : {
"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,

API Security 114

 API Security

"lastModifiedUser" : "John Doe",

"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,
"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",

API Security 115

 API Security

"lastModifiedUser" : "John Doe",

"lastModified" : 1556735907
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetSiteDiscoverySettingsResponse

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
post /v2/discovery/sites/settings
Update the site's discovery settings (updateSitesDiscoverySettings)
Update the site's discovery settings with one of the optional parameters for each site

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body SiteDiscoverySettings (optional)
Body Parameter — Discovery settings

Return type
GetSiteDiscoverySettingsListResponse

Example data
Content-Type: application/json
{
"data" : [ {

API Security 116

 API Security

"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,
"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,

API Security 117

 API Security

"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907
}, {
"authenticationEnabled" : true,
"siteName" : "example.com",
"discoveryIncludeOnlyPaths" : "["/api", "/service"]",
"authParameterSettings" : [ {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
}, {
"auditString" : "auditString",
"accountId" : 12345,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"authParameterLocation" : "http->req->header->jwt",
"enabled" : true
} ],
"excessiveDataExposureSettings" : {
"excessiveDataExposureEnabled" : true,
"responseParameterWithSensitiveDataLabelLimit" : 100,
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907,
"responseParameterLimit" : 100,
"responseParameterWithDataLabelLimit" : 100
},
"relatedHosts" : [ {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
}, {
"hostName" : "example.com",
"hostId" : 12345,
"siteId" : 1234567,
"siteName" : "example.com"
} ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 12345,
"isDiscoveryEnabled" : true,

API Security 118

 API Security

"endpointSettings" : [ {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
}, {
"hostname" : "example.com",
"authenticationEnabled" : true,
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
} ],
"siteId" : 1234567,
"discoveryExcludePaths" : "["/test"]",
"lastModifiedUser" : "John Doe",
"lastModified" : 1556735907
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetSiteDiscoverySettingsListResponse

400

Bad request ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/statistics/classification/from/{from-timestamp}/to/{to-timestam
p}
Retrieve account level baselined endpoints' classification statistics (getDashboardClassificationStatistics)
Retrieve account level baselined endpoints' classification statistics

Path parameters
from-timestamp (required)

API Security 119

 API Security

Path Parameter — format: int64

to-timestamp (required)
Path Parameter — format: int64

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Return type
GetDashboardClassificationStatisticsSuccessfulResponse

Example data
Content-Type: application/json
{
"data" : {
"topRisksVolumeStatistics" : [ {
"volume" : 2,
"risk" : "Unauthenticated",
"percent" : 7
}, {
"volume" : 2,
"risk" : "Unauthenticated",
"percent" : 7
} ],
"resourcesClassificationStatistics" : [ {
"resourceDetails" : {
"hostname" : "example.com",
"resourceUrl" : "v1/data"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"labels" : [ null, null ]
}, {
"resourceDetails" : {
"hostname" : "example.com",
"resourceUrl" : "v1/data"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"labels" : [ null, null ]
} ],
"endpointsClassificationStatistics" : [ {
"endpointDetails" : {
"hostname" : "example.com",
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
},
"risks" : [ "risks", "risks" ],

API Security 120

 API Security

"isFirstTimeSeenInCurrentTimePeriod" : true,
"risksInfo" : [ {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
}, {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
} ],
"labels" : [ null, null ]
}, {
"endpointDetails" : {
"hostname" : "example.com",
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
},
"risks" : [ "risks", "risks" ],
"isFirstTimeSeenInCurrentTimePeriod" : true,
"risksInfo" : [ {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
}, {
"owaspTag" : "owaspTag",
"riskType" : "OWASP",
"risk" : "EXCESSIVE_DATA_EXPOSURE"
} ],
"labels" : [ null, null ]
} ],
"sensitiveClassificationVolumeStatistics" : [ {
"volume" : 5,
"label" : "generalinfo:email",
"percent" : 5
}, {
"volume" : 5,
"label" : "generalinfo:email",
"percent" : 5
} ],
"nonSensitiveClassificationVolumeStatistics" : [ null, null ],
"labelsIdentified" : {
"trendPercent" : 1,
"currentCount" : 0,
"trendDirection" : "UP",
"previousCount" : 6
},
"allClassificationVolumeStatistics" : [ null, null ],
"hostsClassificationStatistics" : [ {

API Security 121

 API Security

"hostDetails" : {
"hostname" : "example.com"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false
} ]
}, {
"hostDetails" : {
"hostname" : "example.com"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"labels" : [ {
"name" : "generalinfo:email",
"sensitive" : false
}, {
"name" : "generalinfo:email",
"sensitive" : false
} ]
} ]
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetDashboardClassificationStatisticsSuccessfulResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/statistics/usage/from/{from-timestamp}/to/{to-timestamp}

API Security 122

 API Security

Retrieve account level baselined endpoints' usage statistics (getDashboardGeneralStatistics)

Retrieve account level baselined endpoints' usage statistics

Path parameters
from-timestamp (required)
Path Parameter — format: int64
to-timestamp (required)
Path Parameter — format: int64

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Return type
GetDashboardGeneralStatisticsSuccessfulResponse

Example data
Content-Type: application/json
{
"data" : {
"clientApps" : 6,
"clientCountries" : 5,
"clientUserAgents" : 1,
"apiCalls" : 0
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetDashboardGeneralStatisticsSuccessfulResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

API Security 123

 API Security

Up
get /v2/discovery/statistics/geolocation/from/{from-timestamp}/to/{to-timestamp}
Retrieve account level baselined endpoints' geolocation statistics (getDashboardGeolocationStatistics)
Retrieve account level baselined endpoints' geolocation statistics

Path parameters
from-timestamp (required)
Path Parameter — format: int64
to-timestamp (required)
Path Parameter — format: int64

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Return type
GetDashboardGeolocationStatisticsSuccessfulResponse

Example data
Content-Type: application/json
{
"data" : {
"clientGeolocationCountryStatisticsDto" : [ {
"code" : "US",
"currentCallVolume" : 0,
"name" : "United States",
"currentCallPercent" : 6
}, {
"code" : "US",
"currentCallVolume" : 0,
"name" : "United States",
"currentCallPercent" : 6
} ],
"destinationGeolocationCountryStatisticsDto" : [ null, null ]
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 124

 API Security

Responses

200

Success GetDashboardGeolocationStatisticsSuccessfulResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/discovery/statistics/volume/from/{from-timestamp}/to/{to-timestamp}
Retrieve account level baselined endpoints' volume statistics (getDashboardVolumeStats)
Retrieve account level baselined endpoints' volume statistics

Path parameters
from-timestamp (required)
Path Parameter — format: int64
to-timestamp (required)
Path Parameter — format: int64

Query parameters
hostIds (optional)
Query Parameter — Comma separated list of host ids

Return type
GetDashboardVolumeStatisticsSuccessfulResponse

Example data
Content-Type: application/json
{
"data" : {
"resourcesVolumeStatistics" : [ {
"currentCallVolume" : 1,
"resourceDetails" : {
"hostname" : "example.com",
"resourceUrl" : "v1/data"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 5
}, {
"currentCallVolume" : 1,

API Security 125

 API Security

"resourceDetails" : {
"hostname" : "example.com",
"resourceUrl" : "v1/data"
},
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 5
} ],
"endpointsVolumeStatistics" : [ {
"endpointDetails" : {
"hostname" : "example.com",
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
},
"currentCallVolume" : 5,
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 2
}, {
"endpointDetails" : {
"hostname" : "example.com",
"method" : "POST",
"endpointId" : 1234567890,
"endpointUrl" : "/v1/data"
},
"currentCallVolume" : 5,
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 2
} ],
"hostsResourceStatTrend" : {
"trendPercent" : 1,
"currentCount" : 0,
"trendDirection" : "UP",
"previousCount" : 6
},
"hostsVolumeStatistics" : [ {
"hostDetails" : {
"hostname" : "example.com"
},
"currentCallVolume" : 0,
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 6
}, {
"hostDetails" : {
"hostname" : "example.com"
},
"currentCallVolume" : 0,
"isFirstTimeSeenInCurrentTimePeriod" : true,
"currentCallPercent" : 6
} ]

API Security 126

 API Security

}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetDashboardVolumeStatisticsSuccessfulResponse

400

Bad input error ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /endpoint/{apiId}
Retrieve all endpoints (getAllUserFacingEndpoints)
Retrieve details on all endpoints for an API

Path parameters
apiId (required)
Path Parameter — The API ID format: int64

Return type
GetEndpointsResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : [ {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"

API Security 127

 API Security

}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
}, {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

API Security 128

 API Security

Responses

200

Success GetEndpointsResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
get /endpoint/{apiId}/{endpointId}
Retrieve an endpoint (getUserFacingEndpoint)
Retrieve details for an endpoint

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
endpointId (required)
Path Parameter — The endpoint ID format: int64

Return type
GetEndpointResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"path" : "/api/{param}",
"sensitiveDataClassificationList" : [ {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
}, {
"lastSeen" : 1556735907,
"location" : "RESPONSE",
"classification" : "large_us_city",
"locationPath" : "users/user/name/address"
} ],
"method" : "GET",
"violationActions" : {

API Security 129

 API Security

"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY"
},
"id" : 1234,
"specificationViolationAction" : "ALERT_ONLY",
"duplicateOfEndpointId" : 1234
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetEndpointResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
post /endpoint/{apiId}/{endpointId}
Update an endpoint (updateEndpoint)
Update an endpoint API Specification Violation Action

Path parameters
apiId (required)
Path Parameter — The API ID format: int64
endpointId (required)
Path Parameter — The endpoint ID format: int64

Consumes
This API call consumes the following media types via the Content-Type request header:

• multipart/form-data

API Security 130

 API Security

Form parameters
specificationViolationAction (optional)
Form Parameter —
violationActions (optional)
Form Parameter —

Return type
UpdateEndpointResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"endpointId" : 1234567890
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success UpdateEndpointResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
get /config/site
Retrieve the all site configuration in account (getSiteConfigurationForAccount)
Retrieve all the site configurations in account

Query parameters
filterActiveOnly (optional)

API Security 131

 API Security

Query Parameter —

Return type
GetSiteConfigurationsResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : [ {
"nonApiRequestViolationAction" : "nonApiRequestViolationAction",
"discoveryExcludeBasePath" : [ "discoveryExcludeBasePath", "discoveryExcludeB
asePath" ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 6,
"discoveryEnabled" : true,
"siteId" : 0,
"siteName" : "example.com",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"discoveryIncludeBasePath" : [ "discoveryIncludeBasePath", "discoveryIncludeB
asePath" ],
"lastModified" : 1556735907,
"apiOnlySite" : true
}, {
"nonApiRequestViolationAction" : "nonApiRequestViolationAction",
"discoveryExcludeBasePath" : [ "discoveryExcludeBasePath", "discoveryExcludeB
asePath" ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 6,
"discoveryEnabled" : true,
"siteId" : 0,
"siteName" : "example.com",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"discoveryIncludeBasePath" : [ "discoveryIncludeBasePath", "discoveryIncludeB
asePath" ],
"lastModified" : 1556735907,

API Security 132

 API Security

"apiOnlySite" : true
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetSiteConfigurationsResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
get /config/site/{siteId}
Retrieve the site configuration for a given site (getSiteConfigurationForSite)
Retrieve all the site configuration of a specific site

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

Return type
GetSiteConfigurationResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"nonApiRequestViolationAction" : "nonApiRequestViolationAction",
"discoveryExcludeBasePath" : [ "discoveryExcludeBasePath", "discoveryExcludeB
asePath" ],
"isAutomaticDiscoveryApiIntegrationEnabled" : true,
"accountId" : 6,

API Security 133

 API Security

"discoveryEnabled" : true,
"siteId" : 0,
"siteName" : "example.com",
"violationActions" : {
"invalidMethodViolationAction" : "ALERT_ONLY",
"invalidParamNameViolationAction" : "ALERT_ONLY",
"invalidParamValueViolationAction" : "ALERT_ONLY",
"missingParamViolationAction" : "ALERT_ONLY",
"invalidUrlViolationAction" : "ALERT_ONLY"
},
"discoveryIncludeBasePath" : [ "discoveryIncludeBasePath", "discoveryIncludeB
asePath" ],
"lastModified" : 1556735907,
"apiOnlySite" : true
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetSiteConfigurationResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
post /config/site/{siteId}
Update site configuration (updateSiteConfiguration)
Update site configuration with one of the optional parameters

Path parameters
siteId (required)
Path Parameter — The site ID format: int64

API Security 134

 API Security

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body SiteConfigurationResponse (optional)
Body Parameter — Settings for attack policy and more

Return type
UpdateSiteConfigurationResponse

Example data
Content-Type: application/json
{
"isError" : false,
"value" : {
"siteId" : 12345
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success UpdateSiteConfigurationResponse

400

Bad request SimpleTextErrorResponse

500

Internal error SimpleTextErrorResponse

Up
delete /v2/shift-left/actions/{actionId}
Delete an action (deleteAction)
Deletes a specified action from the account.

API Security 135

 API Security

Path parameters
actionId (required)
Path Parameter — The ActionId format: int64

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

204

No Content

404

Resource not found ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/shift-left/actions/{actionId}/actionType/{actionTypeId}
Download reports (downloadResults)
Downloads the requested reports for a specified action

Path parameters
actionId (required)
Path Parameter — Action Id format: int64
actionTypeId (required)
Path Parameter — Action Type Id format: int64

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/zip

Responses

200

Success

API Security 136

 API Security

400

Bad Request ApiFailureResponse

404

Resource not found ApiFailureResponse

500

Internal error ApiFailureResponse

Up
get /v2/shift-left/actions/action-types
Retrieve all action types for an account (getActionTypes)
Retrieves details of all action types for the account

Return type
GetActionTypesResponse

Example data
Content-Type: application/json
{
"data" : [ {
"actionType" : "SECURITY_TEST_PKG",
"actionTypeId" : 123,
"actionTypeDisplayName" : "Generate security test"
}, {
"actionType" : "SECURITY_TEST_PKG",
"actionTypeId" : 123,
"actionTypeDisplayName" : "Generate security test"
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetActionTypesResponse

API Security 137

 API Security

500

Internal error ApiFailureResponse

Up
get /v2/shift-left/actions
Retrieve all actions for an account (getActions)
Retrieves details of all actions for the account

Return type
GetActionsResponse

Example data
Content-Type: application/json
{
"data" : [ {
"apiBundleName" : "Test.zip",
"actionId" : 123,
"lastModifiedUser" : "lastModifiedUser",
"source" : "Discovery",
"lastModified" : "2000-01-23T04:56:07.000+00:00",
"actionTypes" : [ {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
}, {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
} ]
}, {
"apiBundleName" : "Test.zip",
"actionId" : 123,
"lastModifiedUser" : "lastModifiedUser",
"source" : "Discovery",
"lastModified" : "2000-01-23T04:56:07.000+00:00",
"actionTypes" : [ {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
}, {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"

API Security 138

 API Security

} ]
} ]
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success GetActionsResponse

500

Internal error ApiFailureResponse

Up
post /v2/shift-left/files/discovery
Upload discovered APIs (uploadDiscoveredHostsSpecFiles)
Uploads the OAS file containing discovered APIs for a selected host

Consumes
This API call consumes the following media types via the Content-Type request header:

• application/json

Request body
body string (optional)
Body Parameter — Selected host ids

Return type
UploadFileSuccessResponse

Example data
Content-Type: application/json
{
"data" : {
"apiBundleName" : "Test.zip",
"actionId" : 123,
"lastModifiedUser" : "lastModifiedUser",
"source" : "Discovery",

API Security 139

 API Security

"lastModified" : "2000-01-23T04:56:07.000+00:00",
"actionTypes" : [ {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
}, {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
} ]
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success UploadFileSuccessResponse

500

Internal error ApiFailureResponse

Up
post /v2/shift-left/files/oas
Upload an OAS file (uploadFile)
Uploads an OAS file manually.

Consumes
This API call consumes the following media types via the Content-Type request header:

• multipart/form-data

Form parameters
actionTypes (optional)
Form Parameter —
file (optional)
Form Parameter — format: binary

API Security 140

 API Security

Return type
UploadFileSuccessResponse

Example data
Content-Type: application/json
{
"data" : {
"apiBundleName" : "Test.zip",
"actionId" : 123,
"lastModifiedUser" : "lastModifiedUser",
"source" : "Discovery",
"lastModified" : "2000-01-23T04:56:07.000+00:00",
"actionTypes" : [ {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
}, {
"errMsg" : "Error in processing request",
"id" : 123,
"type" : "SECURITY_TEST_PKG",
"status" : "IN_PROGRESS"
} ]
}
}

Produces
This API call produces the following media types according to the Accept request header; the media type will be
conveyed by the Content-Type response header.

• application/json

Responses

200

Success UploadFileSuccessResponse

400

Bad Request ApiFailureResponse

500

Internal error ApiFailureResponse

API Security 141

 API Security

Models
Methods

Table of Contents

1. Action
2. ActionType
3. ActionTypeMap
4. AddApiResponse
5. AddApiResponseValue
6. ApiFailureResponse
7. ApiResponse
8. ApiSuccessResponse
9. ApiViolationActions
10. ApiWithEndpointResponse
11. AuthParameterLocationDto
12. AuthParameterLocationResponse
13. AuthParameterSettings
14. AuthenticationInfo
15. ClassificationRiskVolumeStatistics
16. ClassificationStatistics
17. ClassificationVolumeStatistics
18. DataExposureInfo
19. DataLabelSettings
20. DataTypeDto
21. DiscoveredApisSummary
22. DiscoveredEndpoint
23. DiscoveryAccountSettings
24. DownloadApiSpecificationDtoResponse
25. DuplicateEndpointResponse
26. EndpointClassificationStatistics
27. EndpointDetails
28. EndpointDrillDown
29. EndpointResponse
30. EndpointSettingsDto
31. EndpointStatisticsSummary
32. EndpointViolationActions
33. EndpointVolumeStatistics
34. EndpointsPerHost
35. EndpointsPerLabel
36. ExcessiveDataExposureSettings
37. GeolocationCountryStatistics
38. GeolocationStatistics
39. GetActionTypesResponse
40. GetActionsResponse
41. GetApiResponse
42. GetApisResponse

API Security 142

 API Security

43. GetApisWithEndpointsResponse
44. GetDashboardClassificationStatisticsSuccessfulResponse
45. GetDashboardGeneralStatisticsSuccessfulResponse
46. GetDashboardGeolocationStatisticsSuccessfulResponse
47. GetDashboardVolumeStatisticsSuccessfulResponse
48. GetDiscoveredEndpointsResponse
49. GetDiscoveryAccountSettingsResponse
50. GetEndpointDrillDownResponse
51. GetEndpointResponse
52. GetEndpointsResponse
53. GetHostsResponse
54. GetSiteConfigurationResponse
55. GetSiteConfigurationsResponse
56. GetSiteDiscoverySettingsListResponse
57. GetSiteDiscoverySettingsResponse
58. Host
59. HostClassificationStatistics
60. HostDetails
61. HostVolumeStatistics
62. InventoryDiscoveryData
63. Label
64. NumberOfEndpointsByRisks
65. ParameterDrillDown
66. ParserErrorResponse
67. RequestDrillDown
68. ResourceClassificationStatistics
69. ResourceDetails
70. ResourceStatTrend
71. ResourceVolumeStatistics
72. ResponseDrillDown
73. RiskInfo
74. SensitiveDataClassification
75. SimpleTextErrorResponse
76. SimpleTextSuccessResponse
77. SiteConfigurationResponse
78. SiteDiscoverySettings
79. UpdateEndpointResponse
80. UpdateEndpointResponseValue
81. UpdateSiteConfigurationResponse
82. UpdateSiteConfigurationResponseValue
83. UploadFileSuccessResponse
84. UsageStatistics
85. VolumeStatistics

Action Up
apiBundleName (optional)
String API Bundle Name

API Security 143

 API Security

example: Test.zip
source (optional)
String Source Name
example: Discovery
lastModifiedUser
String
lastModified
Date format: date-time
actionId (optional)
Long Action Id format: int64
example: 123
actionTypes (optional)
array[ActionTypeMap] Action Types

ActionType Up
actionTypeId (optional)
Long ActionTypeId format: int64
example: 123
actionType (optional)
String Action Type
example: SECURITY_TEST_PKG
actionTypeDisplayName (optional)
String Action Type Display Name
example: Generate security test

ActionTypeMap Up
id (optional)
Long Action Type Map Id format: int64
example: 123
type (optional)
String Action Type
example: SECURITY_TEST_PKG
status (optional)
String Action Type Map Status
example: IN_PROGRESS
errMsg (optional)
String Error Message
example: Error in processing request

AddApiResponse Up
value (optional)
AddApiResponseValue
isError (optional)
Boolean States if an error occurred
example: false

API Security 144

 API Security

AddApiResponseValue Up
apiId (optional)
Long The API specification ID format: int64
example: 1234
resultMessage (optional)
String Additional information on the action taken
example: API 10 was added successfully
duplicateEndpointsList (optional)
array[DuplicateEndpointResponse] A list of objects representing duplicate endpoints which were not added as part of
the action taken because they exist in another API

ApiFailureResponse Up
errors
Object

ApiResponse Up
specificationViolationAction (optional)
String The action taken when an API Specification Violation occurs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
violationActions (optional)
ApiViolationActions
id (optional)
Long The API ID format: int64
example: 1234
siteId (optional)
Long The site ID format: int64
example: 1234567
siteName (optional)
String The site’s domain name
example: example.com
hostName (optional)
String The API's host name
example: example.com
basePath (optional)
String The API's basePath
example: /api
description (optional)
String The API's description in the dashboard
example: This is an example API
lastModified (optional)

API Security 145

 API Security

Long The last modified timestamp format: int64

example: 1556735907
creationTime (optional)
Long The timestamp when this api was created format: int64
example: 1556735907
apiSource (optional)
String The source from which the API was created
Enum:
USER
DISCOVERY
MIXED
example: USER
oasFileName (optional)
String Uploaded oas file name
example: bank.yaml

ApiSuccessResponse Up
data
Object
meta
Object

ApiViolationActions Up
missingParamViolationAction (optional)
String The action taken when a missing parameter Violation occurs. Assigning DEFAULT will inherit the action from
parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidParamValueViolationAction (optional)
String The action taken when an invalid parameter value Violation occurs. Assigning DEFAULT will inherit the action
from parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidParamNameViolationAction (optional)
String The action taken when an invalid parameter name Violation occurs. Assigning DEFAULT will inherit the action
from parent object, DEFAULT is not applicable for site-level configuration APIs

API Security 146

 API Security

Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidUrlViolationAction (optional)
String The action taken when an invalid URL Violation occurs. Assigning DEFAULT will inherit the action from parent
object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidMethodViolationAction (optional)
String The action taken when an invalid method Violation occurs. Assigning DEFAULT will inherit the action from
parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY

ApiWithEndpointResponse Up
specificationViolationAction (optional)
String The action taken when an API Specification Violation occurs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
violationActions (optional)
ApiViolationActions
id (optional)
Long The API ID format: int64
example: 1234
siteId (optional)

API Security 147

 API Security

Long The site ID format: int64

example: 1234567
siteName (optional)
String The site’s domain name
example: example.com
hostName (optional)
String The API's host name
example: example.com
basePath (optional)
String The API's basePath
example: /api
description (optional)
String The API's description in the dashboard
example: This is an example API
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
creationTime (optional)
Long The timestamp when this api was created format: int64
example: 1556735907
apiSource (optional)
String The source from which the API was created
Enum:
USER
DISCOVERY
MIXED
example: USER
oasFileName (optional)
String Uploaded oas file name
example: bank.yaml
endpoints
array[EndpointResponse]

AuthParameterLocationDto Up
authParameterLocation (optional)
String Authentication location name
example: http-req-header-x-jwt
siteIds (optional)
array[Long] SiteIds format: int64
example: 1234567
useForFutureWebSites (optional)
Boolean Enable same configuration for future website on-boarding
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
lastModifiedUser (optional)
String The last modified user
example: John Doe

API Security 148

 API Security

AuthParameterLocationResponse Up
data
array[AuthParameterLocationDto]

AuthParameterSettings Up
authParameterLocation (optional)
String Authentication location name
example: http->req->header->jwt
accountId (optional)
Long The account ID format: int64
example: 12345
enabled (optional)
Boolean Enable or disable the authentication location
example: true
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
lastModifiedUser (optional)
String The last modified user
example: John Doe
auditString
String

AuthenticationInfo Up
status (optional)
String The status of the authentication locations identified
authParameterLocations (optional)
array[AuthParameterLocationDto] The authentication locations identified

ClassificationRiskVolumeStatistics Up
risk (optional)
String The type of the risk
example: Unauthenticated
volume (optional)
Long format: int64
percent (optional)
Integer format: int32

ClassificationStatistics Up
labelsIdentified (optional)
ResourceStatTrend
labeledHosts (optional)
ResourceStatTrend
labeledResources (optional)
ResourceStatTrend

API Security 149

 API Security

labeledEndpoints (optional)
ResourceStatTrend
riskyEndpoints (optional)
ResourceStatTrend
endpointsOWASPTop10Risks (optional)
ResourceStatTrend
endpointsOtherRisks (optional)
ResourceStatTrend
hostsClassificationStatistics (optional)
array[HostClassificationStatistics] The collection of hosts which had any label in the time window
resourcesClassificationStatistics (optional)
array[ResourceClassificationStatistics] The collection of resources which had any label in the time window
endpointsClassificationStatistics (optional)
array[EndpointClassificationStatistics] The collection of endpoints which had a label in the time window
sensitiveClassificationVolumeStatistics (optional)
array[ClassificationVolumeStatistics] The collection of endpoints which had sensitive label in the time window
nonSensitiveClassificationVolumeStatistics (optional)
array[ClassificationVolumeStatistics] The collection of endpoints which had non sensitive label in the time window
allClassificationVolumeStatistics (optional)
array[ClassificationVolumeStatistics] The collection of endpoints which had both sensitive and non sensitive label in
the time window
topRisksVolumeStatistics (optional)
array[ClassificationRiskVolumeStatistics] The collection of endpoints that had top risks in the time window
risksIdentified (optional)
ResourceStatTrend

ClassificationVolumeStatistics Up
label (optional)
String The name of the label
example: generalinfo:email
volume (optional)
Long format: int64
percent (optional)
Integer format: int32

DataExposureInfo Up
status (optional)
String The status of the Data Exposure

DataLabelSettings Up
dataLabel (optional)
String The data label
example: ssn
accountId (optional)
Long The account ID format: int64
example: 12345
sensitive (optional)

API Security 150

 API Security

Boolean Is this data label sensitive

example: true
visible (optional)
Boolean Is this data label visible
example: true
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
lastModifiedUser (optional)
String The last modified user
example: John Doe
auditString
String

DataTypeDto Up
type (optional)
String The type of the parameter
example: String
children (optional)
array[ParameterDrillDown] Other ParameterDrillDown that are children of this current parameter
example: "type":"String","children":[ { "name": "id", "dataTypes": ["type" : "String", ] "required": true, "labels":
[ { "name": "generalinfo:email", "sensitive": false, "visible": true } ] }]

DiscoveredApisSummary Up
numberOfHosts (optional)
Long The total number of hosts for all endpoints format: int64
numberOfResources (optional)
Long The total number of resources for all endpoints format: int64
numberOfEndpoints (optional)
Long The total number of endpoints for the account format: int64
numberOfLabels (optional)
Long The total number of labels for all endpoints format: int64
numberOfApiDiscoveryStatuses (optional)
map[String, Long] The number of endpoints per discovery status format: int64
example: "{\"IN_PROGRESS\": 1,\"BASELINED\": 20\"}"
numberOfEndpointsWithRisks (optional)
map[String, Long] The discovered API risks format: int64
example: "{\"OWASP\": 1,\"other\": 20\"}"
numberOfEndpointsWithDataLabels (optional)
map[String, Long] Number of sensitive and non-sensitive data labels format: int64
example: "{\"sensitive\": 2,\"non-sensitive\": 5\",\"total\": 7\"}"

DiscoveredEndpoint Up
id (optional)
Long The endpoint ID format: int64
example: 1234567890
labels

API Security 151

 API Security

array[Label]
method (optional)
String The endpoint HTTP method
Enum:
POST
GET
PUT
PATCH
DELETE
HEAD
OPTIONS
example: GET
risks (optional)
array[String] The discovered API risks
risksInfo (optional)
array[RiskInfo] The discovered API risks' information
authenticationInfo (optional)
AuthenticationInfo
dataExposureInfo (optional)
DataExposureInfo
hostId (optional)
Long The ID of the host to which endpoint belongs format: int64
example: 12345
siteId (optional)
Long The ID of the site to which host belongs format: int64
example: 1234567
hostName (optional)
String The name of the host to which endpoint belongs
example: example.com
resource (optional)
String The resource (url) to which endpoint belongs
example: /api/users
status (optional)
String The discovery status for the endpoint
Enum:
BASELINED
IN_PROGRESS
UNDER_INVESTIGATION
DESIGN_ISSUE
example: BASELINED
discoveryDate (optional)
Long The time when endpoint discovery started format: int64
example: 1657886850000
riskTypes
array[String]
Enum:

API Security 152

 API Security

DiscoveryAccountSettings Up
dataLabelSettings (optional)
array[DataLabelSettings] Data label settings
authenticationEnabled (optional)
Boolean
authParameterSettings (optional)
array[AuthParameterSettings] Authentication location settings
excessiveDataExposureSettings (optional)
ExcessiveDataExposureSettings

DownloadApiSpecificationDtoResponse Up
value (optional)
String
isError (optional)
Boolean States if an error occurred
example: false

DuplicateEndpointResponse Up
id (optional)
Long The endpoint ID format: int64
example: 1234567890
fullPath (optional)
String The endpoint full path
example: /api/{param}
method (optional)
String The endpoint HTTP method
Enum:
POST
GET
PUT
PATCH
DELETE
HEAD
OPTIONS
example: GET

EndpointClassificationStatistics Up
endpointDetails (optional)
EndpointDetails
labels (optional)
array[Label]
hostsResourceStatTrend (optional)
ResourceStatTrend
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean
risks (optional)

API Security 153

 API Security

array[String] The discovered API risks

risksInfo (optional)
array[RiskInfo] The discovered API risks info

EndpointDetails Up
endpointId (optional)
Long The endpoint ID format: int64
example: 1234567890
endpointUrl (optional)
String The endpoint url
example: /v1/data
hostname (optional)
String The host’s name
example: example.com
method (optional)
String
example: POST

EndpointDrillDown Up
hostName (optional)
String The name of the host to which endpoint belongs
example: example.com
method (optional)
String The method of the endpoint
example: GET
resource (optional)
String The resource (url) to which endpoint belongs
example: /api/users
authenticationInfo (optional)
AuthenticationInfo
request (optional)
RequestDrillDown
responses (optional)
map[String, ResponseDrillDown]
endpointStatisticsSummary (optional)
EndpointStatisticsSummary

EndpointResponse Up
specificationViolationAction (optional)
String The action taken when an API Specification Violation occurs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT

API Security 154

 API Security

example: ALERT_ONLY
violationActions (optional)
EndpointViolationActions
id (optional)
Long The endpoint ID format: int64
example: 1234
path (optional)
String The endpoint path
example: /api/{param}
method (optional)
String The endpoint HTTP method
Enum:
POST
GET
PUT
PATCH
DELETE
HEAD
OPTIONS
example: GET
duplicateOfEndpointId (optional)
Long The ID of the endpoint that this endpoint is the duplicate of format: int64
example: 1234
sensitiveDataClassificationList (optional)
array[SensitiveDataClassification] Sensitive data classification list for this endpoint

EndpointSettingsDto Up
endpointId (optional)
Long The endpoint ID format: int64
example: 1234567890
endpointUrl (optional)
String The endpoint url
example: /v1/data
hostname (optional)
String The host’s name
example: example.com
method (optional)
String
example: POST
authenticationEnabled (optional)
Boolean
excessiveDataExposureSettings (optional)
ExcessiveDataExposureSettings

EndpointStatisticsSummary Up
numberOfParametersWithDataLabels (optional)
map[String, Integer] Number of total, sensitive and non-sensitive data labels for all parameters format: int32
example: "{\"sensitive\": 2,\"non-sensitive\": 5\",\"total\": 7\"}"

API Security 155

 API Security

numberOfParametersByDataLabel (optional)
map[String, Integer] Number of parameters for a specific label format: int32

EndpointViolationActions Up
missingParamViolationAction (optional)
String The action taken when a missing parameter Violation occurs. Assigning DEFAULT will inherit the action from
parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidParamValueViolationAction (optional)
String The action taken when an invalid parameter value Violation occurs. Assigning DEFAULT will inherit the action
from parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY
invalidParamNameViolationAction (optional)
String The action taken when an invalid parameter name Violation occurs. Assigning DEFAULT will inherit the action
from parent object, DEFAULT is not applicable for site-level configuration APIs
Enum:
ALERT_ONLY
BLOCK_REQUEST
BLOCK_USER
BLOCK_IP
IGNORE
DEFAULT
example: ALERT_ONLY

EndpointVolumeStatistics Up
endpointDetails (optional)
EndpointDetails
currentCallVolume (optional)
Long format: int64
currentCallPercent (optional)
Integer format: int32
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean

API Security 156

 API Security

EndpointsPerHost Up
hostId (optional)
Long The host ID format: int64
example: 12345
hostName (optional)
String The host name
example: example.com
numberOfEndpoints (optional)
Long The number of endpoints for the specific host format: int64

EndpointsPerLabel Up
label (optional)
String The name of the label
example: generalinfo:email
numberOfEndpoints (optional)
Long The number of endpoints per specific label format: int64

ExcessiveDataExposureSettings Up
excessiveDataExposureEnabled (optional)
Boolean
responseParameterLimit (optional)
Integer Response parameters limit format: int32
example: 100
responseParameterWithDataLabelLimit (optional)
Integer Response parameters with data label limit format: int32
example: 100
responseParameterWithSensitiveDataLabelLimit (optional)
Integer Response parameters with sensitive data label limit format: int32
example: 100
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
lastModifiedUser (optional)
String The last modified user
example: John Doe

GeolocationCountryStatistics Up
name (optional)
String The country name
example: United States
code (optional)
String The country code
example: US
currentCallVolume (optional)
Long format: int64
currentCallPercent (optional)

API Security 157

 API Security

Integer format: int32

GeolocationStatistics Up
clientGeolocationCountryStatisticsDto (optional)
array[GeolocationCountryStatistics]
destinationGeolocationCountryStatisticsDto (optional)
array[GeolocationCountryStatistics]

GetActionTypesResponse Up
data
array[ActionType]

GetActionsResponse Up
data
array[Action]

GetApiResponse Up
value (optional)
ApiResponse
isError (optional)
Boolean States if an error occurred
example: false

GetApisResponse Up
value (optional)
array[ApiResponse]
isError (optional)
Boolean States if an error occurred
example: false

GetApisWithEndpointsResponse Up
value (optional)
array[ApiWithEndpointResponse]
isError (optional)
Boolean States if an error occurred
example: false

GetDashboardClassificationStatisticsSuccessfulResponse Up
data
ClassificationStatistics

GetDashboardGeneralStatisticsSuccessfulResponse Up
data

API Security 158

 API Security

UsageStatistics

GetDashboardGeolocationStatisticsSuccessfulResponse Up
data
GeolocationStatistics

GetDashboardVolumeStatisticsSuccessfulResponse Up
data
VolumeStatistics

GetDiscoveredEndpointsResponse Up
data
InventoryDiscoveryData

GetDiscoveryAccountSettingsResponse Up
data
DiscoveryAccountSettings

GetEndpointDrillDownResponse Up
data
EndpointDrillDown

GetEndpointResponse Up
value (optional)
EndpointResponse
isError (optional)
Boolean States if an error occurred
example: false

GetEndpointsResponse Up
value (optional)
array[EndpointResponse]
isError (optional)
Boolean States if an error occurred
example: false

GetHostsResponse Up
data
array[Host]

GetSiteConfigurationResponse Up
value (optional)

API Security 159

 API Security

SiteConfigurationResponse
isError (optional)
Boolean States if an error occurred
example: false

GetSiteConfigurationsResponse Up
value (optional)
array[SiteConfigurationResponse]
isError (optional)
Boolean States if an error occurred
example: false

GetSiteDiscoverySettingsListResponse Up
data
array[SiteDiscoverySettings]

GetSiteDiscoverySettingsResponse Up
data
SiteDiscoverySettings

Host Up
hostId (optional)
Long The host ID format: int64
example: 12345
hostName (optional)
String The host's domain name
example: example.com
siteId (optional)
Long The site external ID format: int64
example: 1234567
siteName (optional)
String The site's domain name
example: example.com

HostClassificationStatistics Up
hostDetails (optional)
HostDetails
labels (optional)
array[Label]
hostsResourceStatTrend (optional)
ResourceStatTrend
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean

API Security 160

 API Security

HostDetails Up
hostname (optional)
String The host's name
example: example.com

HostVolumeStatistics Up
hostDetails (optional)
HostDetails
currentCallVolume (optional)
Long format: int64
currentCallPercent (optional)
Integer format: int32
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean

InventoryDiscoveryData Up
endpoints (optional)
array[DiscoveredEndpoint]
endpointsNumberByHost (optional)
array[EndpointsPerHost]
endpointsNumberByLabel (optional)
array[EndpointsPerLabel]
endpointsNumberByRisk (optional)
array[NumberOfEndpointsByRisks]
summary (optional)
DiscoveredApisSummary

Label Up
name (optional)
String The name of the label
example: generalinfo:email
sensitive (optional)
Boolean An indication whether the label is sensitive
example: false

NumberOfEndpointsByRisks Up
risk (optional)
String The type of risk
example: unauthenticated
numberOfEndpoints (optional)
Long The number of endpoints for a specific risk format: int64

ParameterDrillDown Up
name (optional)

API Security 161

 API Security

String The name of the parameter

example: id
dataTypes (optional)
array[DataTypeDto] The type of the parameter
example: ["type":"String","children":[ { "name": "id", "dataTypes": ["type" : "String", ] "required": true, "labels":
[ { "name": "generalinfo:email", "sensitive": false, "visible": true } ] }]]
required (optional)
Boolean An indication whether the parameter is required
example: false
labels (optional)
array[Label]

ParserErrorResponse Up
value (optional)
array[String]
isError (optional)
Boolean States if an error occurred
example: true

RequestDrillDown Up
queryParamList (optional)
array[ParameterDrillDown]
contentTypeToRequestBody (optional)
map[String, array[ParameterDrillDown]]

ResourceClassificationStatistics Up
resourceDetails (optional)
ResourceDetails
labels (optional)
array[Label]
resourceStatTrend (optional)
ResourceStatTrend
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean

ResourceDetails Up
resourceUrl (optional)
String
example: v1/data
hostname (optional)
String The host's name
example: example.com

ResourceStatTrend Up
currentCount (optional)

API Security 162

 API Security

Long format: int64

previousCount (optional)
Long format: int64
trendPercent (optional)
Integer format: int32
trendDirection (optional)
String
Enum:
UP
DOWN
NEUTRAL

ResourceVolumeStatistics Up
resourceDetails (optional)
ResourceDetails
currentCallVolume (optional)
Long format: int64
currentCallPercent (optional)
Integer format: int32
isFirstTimeSeenInCurrentTimePeriod (optional)
Boolean

ResponseDrillDown Up
contentTypeToResponseBody (optional)
map[String, array[ParameterDrillDown]]

RiskInfo Up
risk (optional)
String The discovered API risk
Enum:
EXCESSIVE_DATA_EXPOSURE
UNAUTHENTICATED
riskType (optional)
String The discovered API risk type
Enum:
OWASP
OTHER
owaspTag (optional)
String The OWASP tag associated with the risk

SensitiveDataClassification Up
classification (optional)
String The classification of the sensitive value
example: large_us_city
lastSeen (optional)
Long The time this sensitive value was seen last format: int64

API Security 163

 API Security

example: 1556735907
locationPath (optional)
String The detailed location of the sensitive value in the location (response body) including any parent objects
example: users/user/name/address
location (optional)
String The location of the sensitive value
example: RESPONSE

SimpleTextErrorResponse Up
value (optional)
String
isError (optional)
Boolean States if an error occurred
example: true

SimpleTextSuccessResponse Up
value (optional)
String
isError (optional)
Boolean States if an error occurred
example: false

SiteConfigurationResponse Up
siteId (optional)
Long The site id format: int64
accountId (optional)
Long The account Id format: int64
siteName (optional)
String The site name
example: example.com
apiOnlySite
Boolean
nonApiRequestViolationAction
String
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
violationActions (optional)
ApiViolationActions
discoveryEnabled (optional)
Boolean
discoveryExcludeBasePath (optional)
array[String]
discoveryIncludeBasePath (optional)
array[String]
isAutomaticDiscoveryApiIntegrationEnabled (optional)
Boolean

API Security 164

 API Security

SiteDiscoverySettings Up
siteId (optional)
Long The site ID format: int64
example: 1234567
accountId (optional)
Long The account ID format: int64
example: 12345
siteName (optional)
String The site name
example: example.com
lastModified (optional)
Long The last modified timestamp format: int64
example: 1556735907
lastModifiedUser (optional)
String The last modified user
example: John Doe
relatedHosts (optional)
array[Host]
isDiscoveryEnabled (optional)
Boolean
discoveryExcludePaths (optional)
array[String] Exclude discovery from these specific base paths
example: ["/test"]
discoveryIncludeOnlyPaths (optional)
array[String] Set discovery for these specific base paths only
example: ["/api", "/service"]
isAutomaticDiscoveryApiIntegrationEnabled (optional)
Boolean
authenticationEnabled (optional)
Boolean
authParameterSettings (optional)
array[AuthParameterSettings] Authentication location settings
excessiveDataExposureSettings (optional)
ExcessiveDataExposureSettings
endpointSettings (optional)
array[EndpointSettingsDto] Enable or disable endpoint exceptions

UpdateEndpointResponse Up
value (optional)
UpdateEndpointResponseValue
isError (optional)
Boolean States if an error occurred
example: false

UpdateEndpointResponseValue Up
endpointId (optional)
Long The API endpoint ID format: int64

API Security 165

 API Security

example: 1234567890

UpdateSiteConfigurationResponse Up
value (optional)
UpdateSiteConfigurationResponseValue
isError (optional)
Boolean States if an error occurred
example: false

UpdateSiteConfigurationResponseValue Up
siteId (optional)
Long The Site ID format: int64
example: 12345

UploadFileSuccessResponse Up
data
Action

UsageStatistics Up
apiCalls (optional)
Long format: int64
clientApps (optional)
Long format: int64
clientUserAgents (optional)
Long format: int64
clientCountries (optional)
Long format: int64

VolumeStatistics Up
hostsVolumeStatistics (optional)
array[HostVolumeStatistics]
resourcesVolumeStatistics (optional)
array[ResourceVolumeStatistics]
endpointsVolumeStatistics (optional)
array[EndpointVolumeStatistics]
hostsResourceStatTrend (optional)
ResourceStatTrend
resourcesResourceStatTrend (optional)
ResourceStatTrend
endpointsResourceStatTrend (optional)
ResourceStatTrend
newHostsResourceStatTrend (optional)
ResourceStatTrend
newResourcesResourceStatTrend (optional)
ResourceStatTrend

API Security 166

 API Security

newEndpointsResourceStatTrend (optional)
ResourceStatTrend

API Security 167

 API Security

API Security Clarifications

This topic addresses further clarifications on issues in API Security.

• Labeling does not work for National ID Israel, Canadian SSN

• Credit card: cvv is not labeled.
• IP address, SSN is not labeled if the same API also carries credit card
• When you have multiple data types for a given param only one type is shown
• If a parameter has multiple data types, the Inventory page shows all labels observed, but the drill-down page
shows only one type and its corresponding labels
• Non-API verbs like HEAD,OPTIONS, CONNECT and TRACE are not processed
• When Discovery is enabled for a specific website the defined policy affects the discovery as follows:
• If the Other traffic violation is set to BLOCK, new APIs are not learned (no new BasePaths)
• If the Invalid URL violation is set to BLOCK, new endpoints are not learned (no new endpoints under
the existing BasePaths that are affected by the BLOCK configuration)
• If the Invalid method violation is set to BLOCK, new endpoints on existing resources are not learned
(no new endpoints for existing endpoint paths that are affected by the BLOCK configuration)
• When Discovery and Automatic Integration are enabled, a discovered endpoint that is baselined, is
automatically merged to the My APIs section and is protected only if the hostname of the endpoint is equal to
the site name.

Note: All alternative domains for a site are protected under API Security according to the
configuration found in the My APIs and in the Policies sections.

API Security 168