Management API

CloudGuard WAF provides a collection of GraphQL APIs that allows to Authenticate, Create, Read, Update Delete any object in the system as well as Publish or Enforce a set of changes.

GraphQL is a strongly typed API query language. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server. This avoids both the problems of over and under-fetching data, while also allowing for a powerful and flexible API.

Authentication

Creating an API Key

Go to Account Settings -> API Keys and create a new API Key for the 'CloudGuard WAF' service. Configure the Expiration date.

After clicking on Create your Client ID and Secret Key will be shown for a single time. Copy it to a secure location as they are not retrievable once the window will be closed.

Using an API Key to authenticate

Before using the specific GraphQL API, you first need to create a valid token to Infinity Portal.

Infinity Portal uses REST API. Use the following REST API:

POST <server address>/auth/external

Use the relevant server address as documented here, to generate a JSON Web Token (JWT).

This token allows temporary usage of the application API using Bearer Authentication (as explained in RFC 6750) until token expiration or revocation. It should be used as Authorization: Bearer [token] header for each API call.

Example of adding the authorization bearer token "abcde-f12345f" to an API call using curl:

curl -H "Authorization: Bearer abcde-f12345f" https://<infinity portal address>/app/waf/graphql/v1

API Reference

View and usage without an external client (using GraphQL)

Under Support->API we provide a GraphQL-based interface for:

  1. Viewing all available functions, divided into query functions that are available for Read-Only users as well, and mutations functions which change configuration and are not available for Read-only Users.

  2. Running custom requests and seeing the result received from the backend.

The left hand screen allows you to modify GraphQL JSON queries. The middle screen shows the response upon clicking the play button. The right hand screen is the GraphQL documentation of all available functions.

Sending GraphQL requests from external sources

If you have a JWT temporary token using the authentication API described above, and you are familiar with creating a query or a mutation operation JSON body, then you can post such a JSON to the following URL with the JSON as the request body:

POST https://<infinity portal address>/app/waf/graphql/v1

Several clients (e.g. Postman) have a GraphQL mode that allows easily constructing the exact request body from the GraphQL JSON.

GraphQL methods

Most methods documented are about CRUD operations vs object in the database.

Read operations (queries) usually start with get* prefix, and GraphQL allows you to modify what exact fields you are interested in viewing. There are also read operations with the suffix *UsedBy which allow you to check for an object if it used by other objects (for example, a practice that is used by multiple assets and zones).

All non-Read operations are methods that are called mutations (as opposed to queries). For Create, Update and Delete operations on objects, the prefixes are usually new*, update* and delete*.

add*, move* and remove* are parallel prefixes for connecting between existing objects (for example, adding a practice to an asset).

share* methods are explained better in the objects structure overview – they are used for taking an existing object, which up until now has been used and owned by a single other object, and making them available to be used and shared by other objects as well (for example, taking an existing practice owned by a specific asset object, and making it globally available to be reused by additional assets and zones).

There are also additional special actions:

  • Agent revocation – revoke* methods

  • Publish configuration – A critical method to activate when the changes are completed, otherwise the objects will be locked for other administrators. There is also a method for discarding all changes.

  • Policy enforce operations – Sending a request to enforce the latest published policy by agents. The query method isEnforcePolicy provides information if a published policy is waiting to be enforced.

Object structure overview

The main hierarchy of objects in Infinity Next Management starts with an asset object (which can come in a variety of types) or a zone object (which represents a usually-dynamic group of assets according to a query).

This object can own other objects according to the following hierarchy:

In CloudGuard WAF's usage of GraphQL, an object can be owned by another object, or can be owned by a connection between 2 objects (and then it will have 2 owning IDs).

When creating an object that should be owned by a parent object, run the relevant get* method on the owning object to get its ID value prior to the object creation method call.

There are several objects in the behavior family. Some can be owned by an asset/zone object and some can be owned by the connection between an asset/zone and a practice.

  • The connection between an Asset/Zone and a Practice can own the following behavior object types:

    WebUserResponseBehavior

    ExceptionBehavior

  • A Web API or a Web Application asset can own the following behavior object type:

    TrustedSourceBehavior

Object sharing (visibility field)

Practices and behavior objects also have a visibility field that can have either the value of “Local” or “Shared”. A “Local” visibility object must contain an owning object ID and cannot be used by any other object in parallel. It will be deleted when the parent object is deleted as it is wholly owned by it.

However, through the share* methods you can make a “Local” visibility object into a “Shared” one which can be owned by multiple objects – Basically you are turning it into a globally used object which will not be deleted if any of the parent objects are deleted.

When creating a practice or a behavior object make sure you have IDs of the parent object/s by using the relevant get* method/s if the visibility is set to “Local”. An empty owning ID can only exist if the visibility is set to “Shared” during the object creation.

API tester

The GitHub repository infinitynext-mgmt-api-resources - includes the following:

  1. JSON file of the management GraphQL API postman collection to import.

  2. Example usage of the GraphQL API.

Last updated

Was this helpful?