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.

See here the official GraphQL documentation.

Authentication

Creating an API Key

Go to Global Settings->API Keys and create a new API Key for the 'Policy' 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.

The ID and Key provide access to your account from the Internet. Secure your keys very carefully. We strongly recommend to use a vault solution for holding your keys and to rotate them periodically.

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/i2/graphql/v1

API Reference

View and usage without an external client (using GraphiQL)

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

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.
Running custom requests and seeing the result received from the backend.

Configuration changes (mutation functions) done using this API will still require clicking on the Publish button in order to be saved in the database and unlocked for usage of other administrators, or by running the publishChanges API request.

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/i2/graphql/v1

The infinity portal address depends on the region you are working with, and can be seen in the Infinity Portal REST API documentation.

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

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.

The “Share” action is irreversible – A Shared object cannot be turned into a “Local” visibility object.

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.

When getting all objects, that can be either local or shared, the default behavior is to return only shared objects. A specific parameter is needed to be added to request to see the local objects as well. Specifically: getPractices will require includePrivatePractices to return local practice objects. getBehaviors will require includePrivateBehaviors to retun local behavior objects.