MANAGEMENT REST API
LAB
R81 Training
Updated Mar. 11, 2021 ©2021 Check Point Software Technologies Ltd. 1
Rest API Lab
• Security needs to be agile and
efficient to keep pace with the
dynamic nature of today’s IT
infrastructure.
• Automation and granular delegation
are key to helping your staff reduce
operational overhead.
• With the R81 management API,
security teams can automate tasks
and create web portals for security
self-service.
©2021 Check Point Software Technologies Ltd. 2
REST API Lab
Enable the API
• Browse to:
https://192.168.101.2/api_docs
• The API is enabled. By default it is
limited to internal host access.
• This can be checked from the CLI also
using the command “api status”.
• Hint: to access the CLI use:
• The putty client on win-victim
• The console from CloudShare or
your local Workstation VM
• SmartConsole -> GATEWAYS &
SERVERS -> Actions -> Open Shell
• Web UI terminal
©2021 Check Point Software Technologies Ltd. 3
REST API Lab
Enable the API
In SmartConsole navigate to
MANAGE & SETTINGS -> Blades ->
Management API.
Click to open Advanced Settings. Management
API
Your instructor has already set access
to All IP addresses.
Click OK or Cancel.
©2021 Check Point Software Technologies Ltd. 4
From the API Reference Overview Introduction identify:
Review 1. The RAM needed to activate the API?
Questions 2. The number of methods to use the management API?
3. Which method sends an HTTP Post request with a
Content-Type of application/json?
©2021 Check Point Software Technologies Ltd. 5
From the API Reference Overview Introduction identify:
1. The RAM needed to activate the API?
1. 4 GB or more on management only deployments
Review and 8 GB or more on standalone deployments
Answers 2. The number of methods to use the management API?
2. 4 in all: SmartConsole, mgmt_cli executable, Gaia
clish shell and via HTTPS connections
3. Which method sends an HTTP Post request with a
Content-Type of application/json?
3. Web Services
©2021 Check Point Software Technologies Ltd. 6
REST API Lab
SmartConsole GUI
• In API Overview click SmartConsole CLI.
add host
• Copy the first example command “add host” with the two required name/value
pairs.
©2021 Check Point Software Technologies Ltd. 7
REST API Lab
SmartConsole GUI
To understand the command syntax, in the API Reference expand Network
Objects.
Click Host -> add host. Name and IP are required.
Browse tabs other than SmartConsole CLI to see the different syntax.
Add host
©2021 Check Point Software Technologies Ltd. 8
REST API Lab
SmartConsole GUI
• In SmartConsole click on the API command line icon in the
lower left.
• Paste or type the add host command into the CLI window and
press enter to create the myHost object.
• In the top middle of SmartConsole you may notice that the
yellow session icon increments.
• Searching for myHost in the right objects sidebar you’ll find
API the new object. Hint: select Network Objects -> Hosts.
command line • Return to the CLI window and press the up arrow. Modify the
command arguments slightly such and press enter to add
another host.
• > add host name myHost1 ip-address 192.0.2.101
• We can also add multiple objects from a file.
©2021 Check Point Software Technologies Ltd. 9
REST API Lab
SmartConsole GUI
Click to
Open a File
©2021 Check Point Software Technologies Ltd. 10
REST API Lab
SmartConsole GUI
• Open students.txt in the test-files/R80 folder.
• This creates 3 networks, a network group object and adds the 3 new
networks to the new group.
©2021 Check Point Software Technologies Ltd. 11
REST API Lab
SmartConsole GUI
• To debug the API, from expert mode in the CLI you can look for errors in
/etc/fw/log/api.elg.
• Enter publish to try to publish the changes and notice the error.
• Exit the window.
Exit
©2021 Check Point Software Technologies Ltd. 12
REST API Lab
SmartConsole GUI
• In SmartConsole go to MANAGE & SETTINGS -> Sessions -> View Sessions.
• Notice all of the changes are done in the current admin session and the
Application is SmartConsole.
• In SECURITY POLICIES click on Changes in the top middle of the window and
you can review the changes doen.
• Click Discard to discard the changes.
©2021 Check Point Software Technologies Ltd. 13
REST API Lab
Web services operational flow
A typical R81 API session starts with a login.
Login Send Rest
Action Publish Logout
https://<ip>/web_api/login https://<ip>/web_api/add-host https://<ip>/web_api/publish https://<ip>/web_api/logout
Install Policy
https://<ip>/web_api/install_policy
©2021 Check Point Software Technologies Ltd. 14
REST API Lab
Web Services
• It’s a good idea to create a separate
account for API access.
• Go to MANAGE & SETTINGS ->
Permissions & Administrators ->
Administrators.
• Click the new icon and create a new user
with the name api-user.
• Set the Permission Profile to Read Write
All.
• Set a password “Cpwins1!”.
• Uncheck User must change password.
• Click OK and publish.
©2021 Check Point Software Technologies Ltd. 15
REST API Lab
Web Services
• On Win-Victim Click Postman to launch the app from the
desktop.
• Click File/Settings Turn off SSL Certificate verification
• We have already imported the postman files click on
collections and you should see the R81 version
disable
Note: The file can also be downloaded from the Check Point community. Unzip the file to import it.
©2021 Check Point Software Technologies Ltd. 16
REST API Lab
Management API Versions
Note: the API Reference has a changelog and list of version releases.
©2021 Check Point Software Technologies Ltd. 17
REST API Lab
Web Services
In Postman click Collections to see the Web API (version 1.7).
Click Session Management -> login.
Notice they are all POST requests.
Collections
login
©2021 Check Point Software Technologies Ltd. 18
REST API Lab
Web Services
• In the API reference find Session
Management -> login in the Web
Services tab.
• Notice in the example that when
we login with username and
password the server response will
include a unique session ID that
we’ll capture and use for the entire
session.
©2021 Check Point Software Technologies Ltd. 19
REST API Lab
Web Services
• In Postman, click the Body tab.
• Note: you may have to expand the body window to see the text lines 1 -4.
• Hover over server and you’ll notice the variable is unresolved in the current
environment and no Environment is defined.
Server
Environment
Body
©2021 Check Point Software Technologies Ltd. 20
REST API Lab
Web Services
• Click the top right corner Manage Environments icon.
• Click Add.
Manage
Environments
©2021 Check Point Software Technologies Ltd. 21
REST API Lab
Web Services
• Enter R81 as the
name.
• Enter two keys.
• server:
https://192.168.101
.2/web_api
• session: <empty>
• Click Add to save
the environment.
• Click X to exit the
window.
©2021 Check Point Software Technologies Ltd. 22
REST API Lab
Web Services
• Click No Environment and select the new R81 environment.
• Change the Request Body user value to api-user.
• Change the Request Body password value to Cpwins1!
R81
update
©2021 Check Point Software Technologies Ltd. 23
REST API Lab
Web Services
• Click Send and you should receive a 200 OK response.
200 OK
©2021 Check Point Software Technologies Ltd. 24
REST API Lab
Web Services
• Manipulate the
window as
needed to shot
the response
body.
• Highlight the sid
in the response.
• Right click and
select Set R81 -> session
session to
capture the
session ID in the
session variable.
sid
©2021 Check Point Software Technologies Ltd. 25
REST API Lab
Web Services
• In the left side bar
collapse Session
Management and
expand Host, then
select add-host.
• Click the Body tab to
see the details of the
command arguments
and click Send.
• You should receive a
200 status OK.
add-host
©2021 Check Point Software Technologies Ltd. 26
REST API Lab
Web Services
• Notice that you can capture the code.
• Click Code and review the code snippets options as you like.
• Click X to close the window.
• To complete the process, in Session Management, send a publish and logout.
Code
©2021 Check Point Software Technologies Ltd. 27
REST API Lab
Web Services
• One of the new additions to the v1.6.1 API is the ability to query logs.
• Scroll down the options in the left side bar to Logs and expand.
• Click on show-logs, then click on Body to see the example to find todays Threat
Emulation logs.
©2021 Check Point Software Technologies Ltd. 28
REST API Lab
Web Services
• Return to SmartConsole
and navigate to LOGS &
MONITOR -> Logs tab.
• Pick a favorite query
such as Access ->
Identity Awareness ->
Login Activity.
• Click on the Option icon.
• Select Tools.
• Select Create an API
query.
• Notice the show-logs
code body.
©2021 Check Point Software Technologies Ltd. 29
REST API Lab
Web Services
• Go to LOGS & MONITOR and click + to open a new tab.
• Click Open Audit Log View.
• Notice the changes are all tracked.
©2021 Check Point Software Technologies Ltd. 30
REST API Lab
mgmt_cli
• mgmt_cli is an executable available on Windows and Gaia.
• Like web services, you can use mgmt_cli as part of a session;
• mgmt_cli login
• mgmt_cli <do something>
• mgmt_cli <publish or discard>
• mgmt_cli logout
• Or you can do the same in one mgmt_cli command. This one command does a
login, adds host7, publishes the change and logs out.
mgmt_cli add host name "host7" ip-address "10.10.10.7" --user "api-user" \
--password "Cpwins1!" --management 192.168.101.2
©2021 Check Point Software Technologies Ltd. 31
REST API Lab
mgmt_cli
• Open a DOS command window.
• One by one copy the commands below into the DOS command window.
• We first have to set the path to the mgmt_cli executable.
• As you like check the audit log to see the results of each command.
cd \Users\jroberts\Desktop\test-files\R80
set R81PATH="C:\Program Files (x86)\CheckPoint\SmartConsole\R81\PROGRAM"
%R81PATH%\mgmt_cli add host name "host7" ip-address "10.10.10.7" -u "api-user" -p "Cpwins1!" \
-m 192.168.101.2
%R81PATH%\mgmt_cli show host name "host7" -u "api-user" -p "Cpwins1!" -m 192.168.101.2
%R81PATH%\mgmt_cli delete host name "host7" -u "api-user" -p “Cpwins1!" -m 192.168.101.2
%R81PATH%\mgmt_cli show host name "host7" -u "api-user" -p "Cpwins1!" -m 192.168.101.2
Note: The copy may remove a “space” character causing an error when run.
©2021 Check Point Software Technologies Ltd. 32
REST API Lab
mgmt_cli
mgmt_cli also has a batch option.
In the folder test-files\R80 is a file csvfile.txt with the following contents.
name,ip-address,color,comments
csv-host1,10.10.10.101,blue,batch
csv-host2,10.10.10.102,blue,batch
csv-host3,10.10.10.103,blue,batch
Run the command below to create 3 host objects.
%R81PATH%\mgmt_cli add host -b csvfile.txt -u "api-user" -p "Cpwins1!" -m 192.168.101.2
Note: The copy may remove a “space” character causing an error when run.
©2021 Check Point Software Technologies Ltd. 33
REST API Lab
Wrapping commands in scripts
• With a basic understanding of the API commands, we can now wrap
commands in scripts. Here is an example from the Check Point community.
̶ Automating and Streamlining Security Operations
©2021 Check Point Software Technologies Ltd. 34
REST API Lab
Wrapping commands in scripts
The example files are in the test-files\R80
folder R80_mgmt_cli_scripts.tar file. To
transfer the files to the R81 management
server we need a user with bash set as the
shell.
Use an existing user named bob with the
password vpn123. /bin/bash
Or you can also create your own by logging
into the Gaia Web UI:
https://192.168.101.2
Select User Management -> Users.
Click Add, set the password, set the Role to
adminRole and set the Shell to /bin/bash.
©2021 Check Point Software Technologies Ltd. 35
REST API Lab
Wrapping commands in scripts
• Copy and paste the below into the DOS command window.
• Change the password and the username to match.
pscp R80_mgmt_cli_Scripts.tar bob@192.168.101.2:/home/admin/R80_mgmt_cli_Scripts.tar
Note: The copy may remove a “space” character causing an error when run.
©2021 Check Point Software Technologies Ltd. 36
REST API Lab
Wrapping commands in scripts
Login to the management server CLI as admin and change to expert mode.
Or login directly to a bash shell as your new user using putty. Hint: type
putty in the DOS cmd window to launch putty.
Change the directory to /home/admin:
cd /home/admin
Untar the scripts:
tar xvf R80_mgmt_cli_Scripts.tar
Change the directory to the new folder.
cd R80_mgmt_cli_Scripts
©2021 Check Point Software Technologies Ltd. 37
REST API Lab
Wrapping commands in scripts
Using the UNIX commands “ls” and “cat <filename>” you’ll notice the scripts:
Are modular
Use variables and loops to create 10 objects, services and rules
©2021 Check Point Software Technologies Ltd. 38
REST API Lab
Wrapping commands in scripts
On the Win-Victim -> Open the CheckMates-Mgmt_CLI.pdf in test-files\R80.
Step through the commands from top to bottom or go directly to the bottom
and enter the command to create all of the objects, services and rulebase.
bash Create_All
In SmartConsole, check the audit logs.
When the command finishes, review the new policy and objects as you like.
©2021 Check Point Software Technologies Ltd. 39
REST API Lab
Wrapping commands in scripts
©2021 Check Point Software Technologies Ltd. 40
1. Does the CheckMates example
use one command or multiple
commands to complete a session,
i.e. login, <do something>,
publish, logout?
Review
Questions 2. How is the session key captured
and used?
3. What is the –r option used in the
CheckMates example?
4. We’ve looked at management
APIs. Are there other APIs?
©2021 Check Point Software Technologies Ltd. 41
1. Does the CheckMates example use one command or multiple
commands to complete a session, i.e. login, <do something>,
publish, logout?
1. multiple commands to complete a session, i.e. login, <do
something>, publish, logout
2. How is the session key captured and used?
Review 2. In the first login command, the output is captured to a file
Answers
named id.txt “mgmt_cli -r true login > id.txt”. In subsequent
commands this is called using the –s parameter “mgmt_cli
publish -s id.txt”.
3. What is the –r option used in the CheckMates example?
3. Hint: check the usage “mgmt_cli -h”
4. We’ve looked at management APIs. Are there other APIs?
4. Yes, for example there’s an Identity Awareness API, a SandBlast
Threat Prevention API and you can use scripts to provision
virtual devices.
©2021 Check Point Software Technologies Ltd. 42
END OF REST API LAB
©2021 Check Point Software Technologies Ltd. 43
