Check Point R80.10 API. Control via CLI, scripts and more

I am sure that everyone who has ever worked with Check Point, there was a complaint about inability to edit the configuration from the command line. This is especially wild for those who have previously worked with Cisco ASA, where absolutely everything can be configured in the CLI. At Check Point, the opposite is true - all security settings were performed exclusively from the graphical interface. However, some things are completely inconvenient to do through the GUI (even as convenient as Check Point). For example, the task of adding 100 new hosts or networks turns into a long and tedious procedure. For each object, you will have to click the mouse several times and enter the ip-address. The same goes for creating a group of sites or mass enabling/disabling IPS signatures. In this case, there is a high probability of making a mistake.

Relatively recently, a “miracle” happened. With the release of the new version Gaia R80 possibility was announced API usage, which opens up wide opportunities for automating settings, administration, monitoring, etc. Now you can:

• create objects;
• add or edit access-lists;
• enable/disable blades;
• configure network interfaces;
• install policies;
• and much more.

To be honest, I don’t understand how this news passed by Habr. In this article, we will briefly describe how to use the API and give some practical examples. CheckPoint settings using scripts.

I would like to make a reservation right away, the API is used only for the Management server. Those. it is still impossible to manage gateways without a Management server.

Who can possibly benefit from this API?

1. System administrators who want to simplify or automate routine Check Point configuration tasks;
2. Companies that want to integrate Check Point with other solutions (virtualization systems, ticket systems, configuration management systems, etc.);
3. System integrators who want to standardize settings or create additional Check Point-related products.

Typical scheme

And so, let's imagine a typical scheme with Check Point:

As usual we have a gateway (SG), control server (SMS) and admin console (smart console). In this case, the usual gateway configuration process is as follows:

Those. first you need to run on the administrator's computer smart console, with which we connect to the Management server (SMS). Security settings are performed on SMS, and only then applied (install policy) to the gateway (SG).

Using Management API, we can basically skip the first step (launching the SmartConsole) and apply API commands directly to the Management Server (SMS).

Ways to use the API

There are four main ways to edit the configuration using the API:

1) Using the mgmt_cli utility

Example - # mgmt_cli add host name host1 ip-address 192.168.2.100
This command is run from the Management Server (SMS) command line. I think the syntax of the command is clear - host1 is created with the address 192.168.2.100.

2) Enter API commands via clish (in expert mode)

Basically, all you need to do is log in at the command line (mgmt login) under the account that is used when connecting via SmartConsole (or root account). Then you can already enter API commands (in this case, there is no need to use the utility before each command mgmt_cli). You can create complete BASH scripts. An example of a script that creates a host:

bash script

#!/bin/bash

main() {
    clear

    #LOGIN (don't ask for username and password, user is already logged in to Management server as 'root' user)
    mgmt_cli login --root true > id_add_host.txt
    on_error_print_and_exit "Error: Failed to login, check that the server is up and running (run 'api status')"

    #READ HOST NAME
    printf "Enter host name:n"
    read -e host_name
    on_empty_input_print_and_exit "$host_name" "Error: The host's name cannot be empty."

    #READ IP ADDRESS
    printf "nEnter host IP address:n"
    read -e ip
    on_empty_input_print_and_exit "$ip" "Error: The host's IP address cannot be empty."

    #CREATE HOST
    printf "Creating new host: $host_name with IP address: $ipn"
    new_host_response=$(mgmt_cli add host name $host_name ip-address $ip -s id_add_host.txt 2> /dev/null)
    on_error_print_and_exit "Error: Failed to create host object. n$new_host_response"

    #PUBLISH THE CHANGES
    printf "nPublishing the changesn"
    mgmt_cli publish --root true -s id_add_host.txt &> /dev/null
    on_error_print_and_exit "Error: Failed to publish the changes."

    #LOGOUT
    logout
	
	printf "Done.n"
}

logout(){
	mgmt_cli logout --root true -s id_add_host.txt &> /dev/null
}

on_error_print_and_exit(){
    if [ $? -ne 0 ]; then
        handle_error "$1" 
	fi
}

handle_error(){
    printf "n$1n" #print error message
    mgmt_cli discard --root true -s id_add_host.txt &> /dev/null
    logout
    exit 1
}

on_empty_input_print_and_exit(){
	if [ -z "$1" ]; then
		printf "$2n" #print error message
		logout
		exit 0
	fi
}

# Script starts here. Call function "main".
main

If you are interested, you can watch the corresponding video:

3) Via SmartConsole by opening the CLI window

All you need to do is open the window CLI straight from smart console, as shown in the picture below.

In this window, you can immediately start entering API commands.

4) Web Services. Use HTTPS Post request (REST API)

In our opinion, this is one of the most promising ways, because. allows you to “build” entire applications according to management server management (sorry for the tautology). We'll look at this method in a little more detail below.

To summarize:

1. API+cli more suitable for people who are used to Cisco;
2. API + shell to apply scripts and perform routine tasks;
3. REST API for automation.

Enable API

By default, the API is enabled on management servers with more than 4GB of RAM and standalone configurations with more than 8GB of RAM. You can check the status with the command: api status

If it turns out that the api is disabled, then it is quite simple to enable it through the SmartConsole: Manage & Settings > Blades > Management API > Advanced Settings

Then publish (Publish) changes and execute the command api restart.

web requests + python

To execute API commands, you can use Web requests using Python and libraries requests, json. In general, the structure of a web request consists of three parts:

1)Address

(https://<managemenet server>:<port>/web_api/<command>) 

2) HTTP headers

content-Type: application/json
x-chkp-sid: <session ID token as returned by the login command>

3) Request payload

Text in JSON format containing the different parameters

Example for calling various commands:

def api_call(ip_addr, port, command, json_payload, sid):
    url = 'https://' + ip_addr + ':' + str(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,verify=False)
    return r.json()                                        
'xxx.xxx.xxx.xxx' -> Ip address GAIA

Here are a few typical tasks that you most often encounter when administering Check Point.

1) An example of authorization and logout functions:

Script

    payload = {‘user’: ‘your_user’, ‘password’ : ‘your_password’}
    response = api_call('xxx.xxx.xxx.xxx', 443, 'login',payload, '')
    return response["sid"]

    response = api_call('xxx.xxx.xxx.xxx', 443,'logout', {} ,sid)
    return response["message"]

2) Turning on the blades and setting up the network:

Script

new_gateway_data = {'name':'CPGleb','anti-bot':True,'anti-virus' : True,'application-control':True,'ips':True,'url-filtering':True,'interfaces':
                    [{'name':"eth0",'topology':'external','ipv4-address': 'xxx.xxx.xxx.xxx',"ipv4-network-mask": "255.255.255.0"},
                     {'name':"eth1",'topology':'internal','ipv4-address': 'xxx.xxx.xxx.xxx',"ipv4-network-mask": "255.255.255.0"}]}
new_gateway_result = api_call('xxx.xxx.xxx.xxx', 443,'set-simple-gateway', new_gateway_data ,sid)
print(json.dumps(new_gateway_result))

3) Changing firewall rules:

Script

new_access_data={'name':'Cleanup rule','layer':'Network','action':'Accept'}
new_access_result = api_call('xxx.xxx.xxx.xxx', 443,'set-access-rule', new_access_data ,sid)
print(json.dumps(new_access_result))

4)Add Application layer:

Script

add_access_layer_application={ 'name' : 'application123',"applications-and-url-filtering" : True,"firewall" : False}
add_access_layer_application_result = api_call('xxx.xxx.xxx.xxx', 443,'add-access-layer', add_access_layer_application ,sid)
print(json.dumps(add_access_layer_application_result))

set_package_layer={"name" : "Standard","access":True,"access-layers" : {"add" : [ { "name" : "application123","position" :2}]} ,"installation-targets" : "CPGleb"}
set_package_layer_result = api_call('xxx.xxx.xxx.xxx', 443,'set-package', set_package_layer ,sid)
print(json.dumps(set_package_layer_result))

5) Publish and install the policy, check the execution of the command (task-id):

Script

publish_result = api_call('xxx.xxx.xxx.xxx', 443,"publish", {},sid)
print("publish result: " + json.dumps(publish_result))
new_policy = {'policy-package':'Standard','access':True,'targets':['CPGleb']}
new_policy_result = api_call('xxx.xxx.xxx.xxx', 443,'install-policy', new_policy ,sid)
print(json.dumps(new_policy_result)

task_id=(json.dumps(new_policy_result ["task-id"]))
len_str=len(task_id)
task_id=task_id[1:(len_str-1)]
show_task_id ={'task-id':(task_id)}
show_task=api_call('xxx.xxx.xxx.xxx',443,'show-task',show_task_id,sid)
print(json.dumps(show_task))

6) Add host:

Script

new_host_data = {'name':'JohnDoePc', 'ip-address': '192.168.0.10'}
new_host_result = api_call('xxx.xxx.xxx.xxx', 443,'add-host', new_host_data ,sid)
print(json.dumps(new_host_result))

7) Add Threat Prevention field:

Script

set_package_layer={'name':'Standard','threat-prevention' :True,'installation-targets':'CPGleb'}
set_package_layer_result = api_call('xxx.xxx.xxx.xxx', 443,'set-package',set_package_layer,sid)
print(json.dumps(set_package_layer_result))

8) View the list of sessions

Script

new_session_data = {'limit':'50', 'offset':'0','details-level' : 'standard'}
new_session_result = api_call('xxx.xxx.xxx.xxx', 443,'show-sessions', new_session_data ,sid)
print(json.dumps(new_session_result))

9) Create a new profile:

Script

add_threat_profile={'name':'Apeiron', "active-protections-performance-impact" : "low","active-protections-severity" : "low or above","confidence-level-medium" : "prevent",
  "confidence-level-high" : "prevent", "threat-emulation" : True,"anti-virus" : True,"anti-bot" : True,"ips" : True,
  "ips-settings" : { "newly-updated-protections" : "staging","exclude-protection-with-performance-impact" : True,"exclude-protection-with-performance-impact-mode" : "High or lower"},
  "overrides" : [ {"protection" : "3Com Network Supervisor Directory Traversal","capture-packets" : True,"action" : "Prevent","track" : "Log"},
                  {"protection" : "7-Zip ARJ Archive Handling Buffer Overflow", "capture-packets" : True,"action" : "Prevent","track" : "Log"} ]}
add_threat_profile_result=api_call('xxx.xxx.xxx.xxx',443,'add-threat-profile',add_threat_profile,sid)
print(json.dumps(add_threat_profile_result))  

10) Change action for IPS signature:

Script

set_threat_protection={
  "name" : "3Com Network Supervisor Directory Traversal",
  "overrides" : [{ "profile" : "Apeiron","action" : "Detect","track" : "Log","capture-packets" : True},
    { "profile" : "Apeiron", "action" : "Detect", "track" : "Log", "capture-packets" : False} ]}
set_threat_protection_result=api_call('xxx.xxx.xxx.xxx',443,'set-threat-protection',set_threat_protection,sid)
print(json.dumps(set_threat_protection_result))

11) Add your service:

Script

add_service_udp={    "name" : "Dota2_udp", "port" : '27000-27030',
"keep-connections-open-after-policy-installation" : False,
"session-timeout" : 0, "match-for-any" : True,
"sync-connections-on-cluster" : True,
"aggressive-aging" : {"enable" : True, "timeout" : 360,"use-default-timeout" : False  },
"accept-replies" : False}
add_service_udp_results=api_call('xxx.xxx.xxx.xxx',443,"add-service-udp",add_service_udp,sid)
print(json.dumps(add_service_udp_results))

12) Add category, site or group:

Script

add_application_site_category={  "name" : "Valve","description" : "Valve Games"}
add_application_site_category_results=api_call('xxx.xxx.xxx.xxx',443,"add-application-site-category",add_application_site_category,sid)
print(json.dumps(add_application_site_category_results))

add_application_site={    "name" : "Dota2", "primary-category" : "Valve",  "description" : "Dotka",
  "url-list" : [ "www.dota2.ru" ], "urls-defined-as-regular-expression" : False}
add_application_site_results=api_call('xxx.xxx.xxx.xxx',443,"add-application-site " , 
add_application_site , sid)
print(json.dumps(add_application_site_results))

add_application_site_group={"name" : "Games","members" : [ "Dota2"]}
add_application_site_group_results=api_call('xxx.xxx.xxx.xxx',443,"add-application-site-group",add_application_site_group,sid)
print(json.dumps(add_application_site_group_results))

In addition, with the help WebAPI you can add and remove networks, hosts, access roles, etc. Blades can be configured Antivirus, Antibot, IPS, VPN. It is even possible to install licenses using the command run-script. All Check Point API commands can be found here.

Check Point API + Postman

It is also convenient to use Check Point Web API in conjunction with Postman. Postman has desktop versions for Windows, Linux, and MacOS. In addition, there is a plugin for Google Chrome. We will use them. First you need to find Postman in the Google Chrome Store and install:

With this utility, we will be able to generate Web requests to the Check Point API. In order not to remember all the API commands, it is possible to import the so-called collections (templates), which already contain all the necessary commands:

Here you will find collection for R80.10. After importing, API command templates will become available to us:

In my opinion, it is very convenient. You can get started developing applications using the Check Point API very quickly.

Check Point + Ansible

I would also like to point out that there is Ansible module for the CheckPoint API. The module allows you to manage configurations, but it is not so convenient for solving exotic problems. Writing scripts in any programming language provides more flexible and convenient solutions.

Hack and predictor Aviator

On this, perhaps, we will finish our short review of the Check Point API. In my opinion, this feature was very long-awaited and necessary. The appearance of the API opens up very wide opportunities for both system administrators and system integrators who work with Check Point products. Orchestration, automation, SIEM feedback... it's all possible now.

PS More articles about Check Point as always you can find in our blog Habr or on the blog Online.

PSS For technical questions related to configuring Check Point, you can here

Only registered users can participate in the survey. Sign in, you are welcome.

Are you planning to use the API?

• 70,6%Yes12

• 23,5%No4

• 5,9%Already using1

17 users voted. 3 users abstained.

Source: habr.com