Introduction to the Check Point Management API

Overview

R80 adds a new way to read information and to send commands to the Check Point management server. Just like it is possible to create objects, work on the security policy using the SmartConsole GUI, it is now possible to do the same using command line tools and through web-services.

Target audience

The management API was created with the following target audiences in mind:

Installation

The management APIs are installed as part of any R80 management server.

Although the management API server is installed on all management servers, it may not be active on some machines:

Security Management Server and Multi-Domain Server

There are different domains for the Multi-Domain Server and the Security Management Server, and each domain has its own API calls:

Using the Management APIs

There are four ways to communicate use the management APIs:

  1. Typing API commands from a dialog inside the SmartConsole GUI application.
  2. Typing API commands using the "mgmt_cli" executable (available in both Windows, Linux/Gaia flavors).
  3. Typing API commands using Gaia's secure shell (clish).
  4. Sending API commands over an https connection using web-services


Typing API commands from the SmartConsole GUI

Open the SmartConsole GUI and click the icon on the bottom left corner. In the dialog that opens, you can now type API commands.


Try the following commands:


Notice that after typing these commands, the objects myHost and myNetwork appear on the objects panel on the right side of the GUI.

A few more examples:

For a complete list of all the available commands and their arguments check the API reference part in this document.


Using the "mgmt_cli" tool

The mgmt_cli tool is installed as part of Gaia on all R80 gateways and can be used in scripts running in expert mode.
The mgmt_cli.exe tool is installed as part of the R80 SmartConsole installation (typically under C:\Program Files (x86)\CheckPoint\SmartConsole\R80\PROGRAM\) and can be copied to run on any Windows machine.
For a complete list of the mgmt_cli options, run "mgmt_cli" and hit Enter.

Examples:

The mgmt_cli tool uses the same syntax that is used inside the SmartConsole GUI but there is one important difference:
Calling mgmt_cli with '-s' or '--session-id' flag will execute 'add host' command leaving it to user to publish (or discard) the changes.
Although calling mgmt_cli with credentials (provided explicitly or entered by prompt) will result in performing four different operations:

The login command

A login command creates a "session". All changes that happen during this session can be accepted (published) or dropped (discarded) according to your decision.
Login command examples:
Example 1
Login to the local management server using username and password 
mgmt_cli login user me password secret
Example 2
Login to the local management server in short notation
mgmt_cli login -u me -p secret
Example 3
Login without username or password. CLI will prompt the user to provide them
mgmt_cli login
Example 4
Login into a remote management server located at 192.0.2.2 
mgmt_cli login user me password secret -m 192.0.2.2
Example 5
Login into a management domain called “my domain” on a remote multi-domain server whose MDS IP-address is 192.0.2.2
mgmt_cli login user me password secret domain "my domain" -m 192.0.2.2
Example 6
Login into a management domain in short notation
mgmt_cli login -u me -p secret -d "my domain" -m 192.0.2.2
Example 7
If administrator logged into the management server and wants to receive SuperUser permissions, "login-as-root" feature might be used. In this case providing additional login credentials is not required. 
mgmt_cli login --root true
Example 8
Logging in as root in short notation
mgmt_cli login -r true
Example 9
Logging into the management server with a client certificate issued from the SmartConsole
mgmt_cli login --client-cert path-to-certificate-file.p12 password secret
Example 10
Logging with a client certificate in short notation
mgmt_cli login -c path-to-certificate.p12 -p secret
Example 11
Logging with a client certificate without password. CLI will prompt the user to provide it
mgmt_cli login -c path-to-certificate.p12
Example 12
Part of command parameters can be provided as environment variables.
Parameter nameShort nameEnvironment variable
User name-uMGMT_CLI_USER
Password-pMGMT_CLI_PASSWORD
Domain-dMGMT_CLI_DOMAIN
Client certificate path-cMGMT_CLI_CLIENT_CERTIFICATE
Management server address-mMGMT_CLI_MANAGEMENT

Login is called when username and password are declared as environment variables 
    export MGMT_CLI_USER=me
    export MGMT_CLI_PASSWORD=secret
    mgmt_cli login
A typical response from a successful login command looks like this: 
    sid: "R9kLPZ7vNTk9iBY8xHmGWpHJ2Kn25PqqUsvfIs5mBqw"
    url: "https://192.0.2.2:443/web_api"
    uid: "f0cb44d3-2d64-41cb-8026-219af70cb5bb"
    session-timeout: 600
    login-message:
        header: "Warning"
        message: "This system is for authorized use only"

Tip:

Tip:


Using the Gaia CLI (clish)

To run management API commands in Gaia's shell, you need to log in as a management user first.

In Gaia's shell, type 

mgmt login
or 
mgmt login user myname
After that you remain in the familiar Gaia shell, but now you can use the management APIs.

Example: 
> mgmt login user <admin name>
Enter password: ******

> show interfaces
eth0
eth0.3
lo
> mgmt add host name myHost12 ip-address 3.3.3.3
> mgmt publish

        message "OK"
        number-of-published-changes     1

>


Using Web Services

Building applications that communicate with the Check Point management server has never been easier. All that is needed is to send an HTTPS Post request to the management server.

Web request structure

HTTP Post to: 

https://<managemenet server>:<port>/web_api/<command>
The default port number is 443

HTTP Headers 
content-Type: application/json
x-chkp-sid: <session ID token as returned by the login command>
The x-chkp-sid header is mandatory in all API calls except the login API.

Request payload 
Text in JSON format containing the different parameters

Responset structure

Returned value on success:

Returned value on failure:

Login example:

Request: 
HTTP Post to https://192.0.2.10/web_api/login
			
content-Type: application/json
{
    "user":"me",
    "password":"secret"
}
Response: 
Status: 200 OK
{
    "sid": "8478V00sYHvH_nBvIhDI203eu3clauAuB1iCEWOw_YY",
    "url": "https://192.0.2.10:443/web_api",
    "session-timeout": 600,
    "last-login-was-at": {
          "posix": 1430906758008,
          "iso-8601": "2015-05-06T13:05+0300"
    },
    "last-login-from": "127.0.0.1",
    "web-api-version": "1.0"
}

Create host example:

Request: 
HTTP Post to https://192.0.2.10/web_api/add-host
			
content-Type: application/json
X-chkp-sid:8478V00sYHvH_nBvIhDI203eu3clauAuB1iCEWOw_YY
			
{
    "name":"MyHost",
    "ip-address":"192.0.2.12"
}
Response: 
Status: 200 OK
{
    "uid": "9a8595e2-5791-487c-9dc4-45d3dbfea95e",
    "folder": {"uid": "5abe7131-5821-4ee9-90b7-70cccef264d4","name": "/Global Objects"},
    "domain": {"domain-type": "local domain","uid": "41e821a0-3720-11e3-aa6e-0800200c9fde","name": "SMC User"},
    "meta-info": {"lock": "unlocked","validation-state": "ok","read-only": false,"last-modify-time": {"posix": 1430913372359,"iso-8601": "2015-05-06T14:56+0300"},
    "last-modifier": "aa","creation-time": {"posix": 1430913372359,"iso-8601": "2015-05-06T14:56+0300"},"creator": "aa"},
    "tags": [ ],
    "name": "MyHost",
    "comments": "",
    "color": "black",
    "icon": "Objects/host",
    "groups": [ ],
    "nat-settings": {"auto-rule": false},
    "ipv4-address": "192.0.2.12",
    "ipv6-address": ""
}

A Sample Python script that use the web-service APIs:

import requests, json

def api_call(ip_addr, port, command, json_payload, sid):
    url = 'https://' + ip_addr + ':' + port + '/web_api/' + command
    if sid == '':
        request_headers = {'Content-Type' : 'application/json'}
    else:
        request_headers = {'Content-Type' : 'application/json', 'X-chkp-sid' : sid}
    r = requests.post(url,data=json.dumps(json_payload), headers=request_headers)
    return r.json()


def login(user,password):
    payload = {'user':user, 'password' : password}
    response = api_call('192.168.65.2', 443, 'login',payload, '')
    return response["sid"]

sid = login('my_username','secret')
print("session id: " + sid)

new_host_data = {'name':'new host name', 'ip-address':'192.168.1.1'}
new_host_result = api_call('192.168.65.2', 443,'add-host', new_host_data ,sid)
print(json.dumps(new_host_result))

publish_result = api_call('192.168.65.2', 443,"publish", {},sid)
print("publish result: " + json.dumps(publish_result))

logout_result = api_call('192.168.65.2', 443,"logout", {},sid)
print("logout result: " + json.dumps(logout_result))