DocumentationAPI ReferenceRelease Notes
Documentation

OpenAPI Specification and Drift Analysis

Suggest Edits

In addition to inspecting the OpenAPI specification of your APIs for security issues, Panoptica can also compare the specification to the traffic to your APIs to provide drift analysis. This enables you to improve your specifications, and discover any mismatch between the OpenAPI specification (the reference) and the real traffic around this API.

Specification analysis findings

Panoptica OpenAPI specification (OAS) analysis can detect various security findings, for example:

  • Missing definition: A definition of missing from the specification, for example, the format, type, patterns, or minimal/maximal value of an attribute, or the definition of a response code.
  • Invalid values: Certain values in the specification do not comply with the OpenAPI standard.
  • Unencrypted traffic: The specification permits unencrypted traffic.

Drift analysis finding types

Panoptica OpenAPI specification (OAS) drift analysis can detect the following drift types:

  • Shadow Endpoints: Traffic is detected to an endpoint that is not found in the provided specification.
  • Zombie Endpoints: Traffic is detected on an endpoint that is marked as deprecated in the specification.
  • Rogue Endpoints: Endpoints where one or several parameters observed in the traffic differ from the specification.

Similarly, individual endpoints can have:

  • Shadow parameters - A parameter is detected in the traffic that is not found in the provided specification.
  • Zombie parameters - A parameter is detected in the traffic that is marked as deprecated in the specification.
  • Rogue parameters - A parameter is detected in the traffic that has a different format compared to the specification. For example, the parameter in the traffic is a string, but it is marked as integer in the specification.

Additional findings resulting from these scans may include:

  • Authentication method mismatch: the traffic shows that the endpoint is accessed with authentication, but authentication is not mentioned in the specification, or the endpoint is accessed without authentication but the specification says that authentication is needed.
  • Role mismatch: a role has been provided in the traffic, but it is not mentioned on the specification, or a role is defined in the specification but is not present in the traffic.
  • Input body type mismatch: the body type doesn’t match the one defined in the specification.
  • Request parameter mismatch: parameters are missing from the traffic, or parameters not mentioned in the specification are observed in the traffic.
  • Shadow response code: the response code for an endpoint is not mentioned in the specification.
  • Response mismatch: the response body type/structure doesn’t match the one defined in the specification.

Prerequisites

The OpenAPI specification analysis doesn't have any prerequisites.

For the OAS drift analysis, you must have:

Upload an OpenAPI specification

To enable OAS Drift Analysis, you must upload an OpenAPI specification for the API by completing the following steps.

📘

Note

Uploading a new version of the specification:

  • Resets any findings that came from the usage of the previous version of the specification.
  • Resets the list of "unobserved" assets.
  1. Navigate to API Security under Workloads & Data.
  2. Click the API you want to update.
  3. Check the Uploaded Spec field.
    • If there is no OpenAPI Specification, click the three dots (•••) to the right of Uploaded Spec to add one.
    • If there is already an OpenAPI Specification uploaded, click the three dots (•••) to replace it, delete it, or view it in Swagger.

Check specification analysis

To see the results of the OpenAPI specification analysis of your APIs, navigate to API Security under Workloads & Data.

The Spec Uploaded column of the individual APIs displays a checkmark if an OpenAPI specification is available for the API.

Click the row of the API to open its details. The Uploaded Spec field shows the name of the uploaded OpenAPI specification file, while the Security Findings field shows a summary of security findings for this API, including the results of the specification analysis.

Click Open Full Details Page > Security findings to list the security findings of this API.

To show only the security findings that are the result of the OpenAPI specification analysis, use the Filter and select:

  • Category > Api-specification, or
  • Sources > OASAnalyzer

Check drift analysis

To see an overview of the drift of your APIs, navigate to API Security under Workloads & Data.

The Spec Uploaded column of the individual APIs displays a checkmark if an OpenAPI specification is available for the API.

Click the row of the API to open its details. The Uploaded Spec field shows the name of the uploaded OpenAPI specification file, while the Spec Drift field shows a summary of the drift analysis for this API.

Click Open Full Details Page > Endpoints to list the endpoints of this API. The Spec Drift field shows the drift analysis of the endpoint.

Click an endpoint to see its details. If Panoptica has detected any drifts, you can find the details in the Request Parameters > Drift Type and the Response Attributes > Drift Type fields.

Drift analysis limitations

  • Only OpenAPI v3 specifications are supported.
  • Combinations of objects in the specification (like "anyof", "oneof", "allof") are not handled.

Updated 5 months ago