October 12, 2017 at 11:48

Check Point R80.10 API. Management through CLI, scripts and more

  • Tutorial


I am sure that everyone who has ever worked with Check Point had a complaint about the impossibility of editing the configuration from the command line . This is especially wild for those who previously worked with the Cisco ASA, where absolutely everything can be configured in the CLI. Check Point has the opposite: 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 have to click the mouse several times and drive in the ip-address. The same goes for creating a group of sites or massively enabling / disabling IPS signatures. Moreover, it is likely to make a mistake.

Relatively recently, a “miracle” happened. With the release of the new version of Gaia R80 , the possibility of using the API was announced , which opens up great opportunities for automation of 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 provide some practical examples of configuring CheckPoint 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 use this API in principle?


  1. System administrators who want to simplify or automate the routine tasks of setting up Check Point;
  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 products related to Check Point.

Typical circuit


And so, imagine a typical diagram with Check Point:



As usual, we have a gateway ( SG ), a management server ( SMS ) and an administrator console ( SmartConsole ). In this case, the usual process of configuring the gateway is as follows:



I.e. first you need to run SmartConsole on the administrator’s computer , with which we connect to the Management server ( SMS ). On SMS, security settings are made, and only then they are applied ( install policy ) to the gateway ( SG ).

When using the Management API , we can in principle skip the first item (launch SmartConsole) and apply API commands directly to the Management server (SMS).

Ways to use the API


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

1) Using the mgmt_cli utility


An example is # mgmt_cli add host name host1 ip-address 192.168.2.100
This command is launched from the command line of the Management server (SMS). I think the syntax of the command is clear - it creates host1 with the address 192.168.2.100.

2) Enter the command API through clish (in expert mode)


In fact, all you need is to log in to the command line ( mgmt login ) under the account that is used when connecting via SmartConsole (or the root account). Then you can enter the API commands (in this case there is no need to use the mgmt_cli utility before each command ). You can create full-fledged BASH scripts . An example 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: $ip\n"
    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 changes\n"
    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$1\n" #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 "$2\n" #print error message
		logout
		exit 0
	fi
}
# Script starts here. Call function "main".
main


If interested, you can watch the corresponding video:



3) Via SmartConsole, opening the CLI window


All you need to do is launch the CLI window directly from SmartConsole , 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 for managing the management server (I apologize for the tautology). Below we consider this method in more detail.

To summarize:


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

API enable


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

If it turns out that the api is turned off, it is quite simple to enable it via SmartConsole: Manage & Settings> Blades> Management API> Advanced Settings



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

Web requests + Python


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

1) Address 2) HTTP Headers 3) Request payload Text in JSON format containing the different parameters Example for calling various commands:

(https://:/web_api/) 



content-Type: application/json
x-chkp-sid: 








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) 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) Enabling Blades and Network Setup:

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) Change the 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) Adding an 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 policy setting, verifying command execution (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 the 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 the action for the 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 a 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, using the Web API you can add and remove networks, hosts, access roles, etc. It is possible to configure Antivirus, Antibot, IPS, VPN blades . It is even possible to install licenses using the run-script command . All Check Point APIs can be found here .

Check Point API + Postman


It is also convenient to use the 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 it. First you need to find Postman in the Google Chrome Store and install:



Using this utility, we can 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) that already contain all the necessary commands:



Here you will find a collection for R80.10 . After import, API command templates will be available to us:



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

Check point + ansible


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

Conclusion


This is perhaps the end of 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 broad opportunities for both system administrators and system integrators who work with Check Point products. Orchestration, automation, feedback from SIEM ... all this is now possible.

PS You can find more articles about Check Point as always in our Habr blog or in a blog on the website .

PSS For technical questions related to setting up Check Point, click here.

Only registered users can participate in the survey. Please come in.

Do you plan to use the API?

  • 69.2% Yes 9
  • 23% No 3
  • 7.6% already using 1
13 users voted. 3 users abstained.
Tags:

Also popular now: