Using Guardium REST APIs

Use the Guardium® REST API to include many Guardium API commands in your applications or anywhere that a REST API is useful.

Guardium REST API overview

The Guardium REST API serves as a wrapper for the rich set of Guardium API (GuardAPI) command-line interface functions. After you register the REST API client on the Guardium collector, as described in Calling REST APIs example, you can use REST API calls for many of the GuardAPI functions. Providing a REST interface to the Guardium API simplifies integrating Guardium into your system.

For more information about GuardAPI functions with REST API capabilities, see Guardium API A- Z Reference.

As shown in Figure 1, take the following steps to set up your Guardium system for the REST API:

Use the command-line interface (CLI) to register the client ID from the collector side. Each client needs to be registered only once. The CLI returns a client secret for the client ID.
Use the curl command-line tool from the REST client to send a request for an access token along with the client secret to the Guardium appliance.
After the REST client is authorized, you can use the access token to call the supported GuardAPI functions.

Tasks to enable the Guardium REST API — Figure 1. Getting started with the REST API

Example use cases

A few examples of when you might use a REST API:

I want the ability to dynamically get a small amount of audit data for a certain IP address without having to login to the Guardium GUI.
I want to populate an existing group, so I can update my policy to prevent unauthorized access to sensitive information.
I want to get a list of all users within a certain authorized access group.
I want my application development team to help identify which sensitive tables to monitor.
I want to script access to GuardAPIs without using "expect" scripting language, which requires me to code response text from the target system.

Calling REST APIs example

The following scenario describes how to use the register_oauth_clientGuardAPI to register the client and then call a GuardAPI function from the REST client.

Access to the collector from the CLI, and run the following grdapi command to register the application, as shown:

example.yourdomain.com> grdapi register_oauth_client client_id=client1 grant_types="password" redirect_uris="https://TestApp1" scope="read,write"
ID=0

The application returns the client secret, as shown in the following example:

{"client_id":"client1","client_secret":"b1f242a2-1e86-46d6-bf42-6298556c2eea","grant_types":"password","scope":"read,write","redirect_uri":"https://TestApp1"}
ok
example.yourdomain.com>

Note: You need to register the application only once.

From the REST client, include the client secret in a curl request for the access token:

C:\tools\curl-7.57.0-win64-mingw\bin>curl -k -X POST -d "client_id=client1&client_secret=b1f242a2-1e86-46d6-bf42-6298556
c2eea&grant_type=password&username=admin&password=********"  https://example.yourdomain.com:8443/oauth/token

Guardium returns the access token:


{"access_token":"29ff4bb4-e622-41cf-97d0-de695ebd756b","token_type":"bearer","expires_in":10799,"scope":"read write"}
C:\tools\curl-7.57.0-win64-mingw\bin>

Use the access token to call a Guardium API function from the REST API. The following example calls the equivalent o the list_datasource_by_id id=20000 function from the REST client.

C:\tools\curl-7.57.0-win64-mingw\bin>curl \
-k --header "Authorization:Bearer 29ff4bb4-e622-41cf-97d0-de695ebd756b" \
--include --header "Content-Type: application/json" \
-X GET https://example.yourdomain.com:8443/restAPI/datasource?id=20000

This REST API call returns the following information about the specified data source:

HTTP/1.1 200 OK
X-FRAME-OPTIONS: SAMEORIGIN
Set-Cookie: JSESSIONID=C7854CAF60CE7B3A6CD585A8173B3222; Path=/; Secure; HttpOnly
Cache-Control: max-age=86400
Expires: Tue, 16 Jan 2018 09:21:52 GMT
Access-Control-Allow-Methods: POST, GET,  PUT, DELETE
Access-Control-Allow-Headers: authorization, origin, X-Requested-With, Content-Type, Accept
Access-Control-Max-Age: 18000
Content-Type: application/json;charset=UTF-8
Content-Length: 914
Date: Mon, 15 Jan 2018 09:21:52 GMT
Server: SQL Guard
[
  {
    "DatasourceId": "https://example.yourdomain.com:8443/restAPI/datasource?id=20000",
    "DatasourceTypeId": "13",
    "Name": "System (9.70.148.141)",
    "Description": "null",
    "Host": "9.70.148.141",
    "Port": "0",
    "ServiceName": "",
      ...

Additional API examples

This example uses the POST verb to create a new data source:

curl -k --header "Authorization:Bearer 04ce5d90-8d89-4e9c-a060-ec94b4409a71" \
--include --header "Content-Type: application/json" \
-X POST --data '{"application":"Classifier","host":"192.168.1.54","name":"mydbserver","type":"TEXT:HTTPS"}' \
https://192.168.1.10:8443/restAPI/datasource

This example uses GET to return the status of all installed applications:

curl -k --header "Authorization:Bearer da186a7e-488d-4cd2-a35b-094b3cc4af86" \
--include --header "Content-Type: application/json" \
-X GET https://192.168.1.10:8443/restAPI/applications

This example updates an existing data source by its ID (which is 20001):

curl -k --header "Authorization:Bearer 04ce5d90-8d89-4e9c-a060-ec94b4409a71" \
--include --header "Content-Type: application/json" \
-X PUT --data '{"id":20001,"description":"My database server."}' \
https://192.168.1.10:8443/restAPI/update_datasource_by_id

This example deletes an application (1500):

curl -k --header "Authorization:Bearer 14da5202-f3c6-45d0-bc10-77604e6cede7" \
--include --header "Content-Type: application/json" \
-X DELETE --data '{"application_id": 1500}' https://192.168.1.10:8443/restAPI/applications

For information about which GuardAPI functions also have REST API calls, see Guardium API A- Z Reference.

For more information about Guardium REST API error codes, see Return Codes for Guardium REST APIs in the IBM Support database.