2.7. API

2.7.1. Introduction

The API (Application Programming Interface) is the set of endpoints (also called resources or end of URL).
Each of these endpoints allows you to perform an action on the GCenter and return information without having to go through the graphical interface.
This facilitates the sharing and integration of GCenter features and data into existing architectures.
Each of these endpoints has a simple syntax.
These endpoints are predetermined: the list of these endpoints is limited and is displayed by theme (analysers ...).

Note

The list of endpoints is given in the Endpoints list.

The execution of these endpoints can be done:

  • Via SWAGGER (Use via the swagger GUI)
    This allows the use of endpoints and to understand its configuration and to test its execution and analyze its results
  • Via CURL (Use via CURL)
    This allows to execute a Curl request directly and not to go through the GUI

2.7.2. Use via the swagger GUI

Each endpoint of the API:

  • Performs a specific operation. Its name and description are indicated in the graphical interface (or in the Endpoints list)

  • Performs one of four possible methods: GET, DELETE, POST, PUT

  • Needs authentication rights that are the same as for the GUI (Operators or Administrators)

  • May need operating parameters (input and/or output): for example, in the case of a filter, the value of this filter must be indicated

All this information is visible in the swagger GUI and is therefore the documentation of all API endpoints.
The swagger GUI description is given in Overview of the API interface.
For implementation of the swagger interface, see the procedure in Using an endpoint API.

This interface enables to:

  • Have a list of existing endpoints (listed by theme)

  • Have details of possible parameters for running an endpoint

  • Have information on the expected result (data model and an example with default values)

  • Execute queries

  • Retrieve the Curl command equivalent to the request via the API

Note

A known bug affects the /api/alerts endpoint (see GCenter release note). It is recommended to use the elasticsearch API to query data on the/api/data/es/search endpoint.

2.7.3. Use via CURL

It is possible to execute an endpoint by a curl command.
This command is accessible via the swagger GUI after selecting the endpoint, entering any parameters and then starting the execution of the endpoint.
The curl command is displayed in the `Responses` area.

For a user called username and with operators rights.

Recovery of the API token:
curl -X POST "https://<hostname>/api/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"username\": \"username\", \"password\": \"password\"}" -k

where hostname is GCenter.

Answer:

{"token":"urxn5hlezbk3vnlgq1t45rifhg0vi951","expiration_date":"2021-04-13T16:26:45.743826"}

Sending a request:

curl -X POST "https://<hostname>/api/<endpoint> -H "accept: application/json" -H "Content-Type: application/json" -H "API-KEY: x0zc5py1e2lrppe6ws0kgc8le0oxm9hg" -d "{\"test\": \"test\"}" -k

Example of a query that will query elasticsearch on its suricata* indexes and retrieve 100 logs over the last 24 hours:

curl -X POST "https://<hostname>/api/<endpoint> -H "accept: application/json" -H "Content-Type: application/json" -H "API-KEY: x0zc5py1e2lrppe6ws0kgc8le0oxm9hg" -d "{ \"size\" : 100, \"query\" : { \"bool\": { \"must\": [], \"filter\": [ { \"match_all\": {} }, { \"range\": { \"@timestamp\": { \"gte\": \"now-24h\", \"lte\": \"now\" } } } ], \"should\": [], \"must_not\": [] } } }" -k

2.7.4. Authentication and access to the API

Access to the swagger graphical interface is via the GCenter web GUI and then press the `API` button.
Authentication allows access to the API (for more information, see paragraph Title bar).
Using curl request requires authentication to be done in the request.
This authentication is done using the name/password pairs or tokens defined in The `API Keys` section of the `Accounts` submenu.