REST API

Introduction

A REST API is available to allow Endpoint Privilege Management data to be configured, customized, and retrieved by other software. The API is web-based and uses industry standard modern components, connectors, and data elements within a distributed and secure enterprise environment.

The REST API is bundled with the main installation and configured in pbinstall:

15  Install REST Services?         [yes]
72  REST Service installation directory?       [/usr/lib/beyondtrust/pb/rest]

The menu response shown above installs the REST API web server components. When installing any server components, REST API installation becomes mandatory.

73  Install REST API sample code?  [yes]
74  REST API sample code directory?            [/usr/local/lib/pbrest]

The menu response shown above installs the Java and scripting example code.

The API can be used with Endpoint Privilege Management for Unix and Linux v7.1.0 and later.

Architecture Overview

Functionality

Settings

• Get All Settings: Gets all of the settings from pb.settings (or equivalent). Each setting has one of 4 distinct types:
  • String
  • Boolean
  • List of Strings
  • altsubmitmasters: Has a special list of Endpoint Privilege Management for Unix and Linux objects
• Get Individual Settings: Gets an individual setting as specified on the URL.
• Put Setting: Puts (modify) a setting into the pb.settings file. The type must correspond to the original setting type.
• Get Settings file as attachment: Retrieves the whole pb.settings file as a binary attachment.

License

• License Get: Retrieves the text value of the license.

Policy

• Policy List Dir: Lists all of the files in a given directory (without checking if they are iologs). This would be limited to policydir if defined. Some system directories cannot be listed for security.
• Policy (Script) Get Lines: Gets a script-based policy file as an ordered array of lines, making line based modifications to the policy file easier.
• Policy (Script) Get Full File: Gets the full script-based policy file as a long string.
• Policies (CSV) Get All: Retrieves an array of CSV policies. Elements are generally strings or arrays of strings.
• Policy (CSV) Get (by name): Retrieves a given named CSV policy.
• Policy (CSV) Put (by name): Puts a given CSV policy, named on the URL.
• Policy (Script) Set New Policy File: Creates a new (optionally empty) policy script file. Directory is limited by policydir if it is set. Parent directories are not created.
• Policy check: Checks policy in a similar manner to pbcheck.
• Get Policy file as attachment: Retrieves a full policy file as a binary attachment.

IO Logs

• IO Log Get: Retrieves an IO log file. Output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
• IO Log List Dir: Lists all of the files in a given directory (without checking if they are IO logs). Filter can be specified as a regular expression to filter output. Some system directories cannot be listed for security.
• IO Log Get Variables: Retrieves the log variables from the specified IO log.
• Get IO Log file as attachment: Retrieves an IO log file as a binary attachment.
• IO Log search: Searches a list of IO logs, specified with a glob style wildcard parameter file, for the query string <query>. This is a similar format to the SOLR search string in which you have a regular expression query, with keyword:value values. For example, stdout:.*inittab searches for any IO logs that incorporate the word inittab in the output. All of the standard keyword values that can be extracted from IO logs can be used in the search criteria. Regular expression matches are not made across newlines.
• IO Log Replay: Retrieves and interprets an IO log file ready to be output by a GUI. Override terminal emulation using the parameter term, and the output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
• IO Log Get: Retrieves an IO log file. Output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.
• IO Log List Dir: List all of the files in a given directory (without checking if they are IO logs). Filter can be specified as a regular expression to filter output. Some system directories cannot be listed for security.
• IO Log Get Variables: Retrieves the log variables from the specified IO log.
• Get IO Log file as attachment: Retrieves an IO log file as a binary attachment.
• IO Log search: Search a list of IO logs, specified with a glob style wildcard parameter file, for the query string <query>. This is a similar format to the SOLR search string where you have a regular expression query, with keyword:value values. For example, stdout:.*inittab searches for any IO logs that incorporate the word inittab in the output. All of the standard keyword values that can be extracted from IO logs can be used in the search criteria. Regular expression matches are not made across newlines.
• IO Log Replay: Retrieves and interprets an IO log file ready to be output by a GUI. Override terminal emulation using the parameter term, and the output can be limited by len and start parameters so that individual parts of the log can be retrieved in chunked form.

Event Logs

• Event Log Get: Retrieves the specified event log.
• Get Event Log file as attachment: Retrieves the specified event log as a binary attachment.

Key File

• Key Get: Gets the specified pb.key file as a base64 encoded string.
• Key Set: Sets the specified pb.key to the base64 encoded string.
• Create a new key: Creates a new specified pb.key file and generates random contents.
• Get Key file as attachment: Retrieves the specified pb.key file as a binary attachment.

SOLR

• Solr Get: Retrieves SOLR search results based upon the supplied criteria.

Authentication

REST is a stateless protocol, which is strongly stressed and adhered to, and so each and every call must authenticate itself to the REST service. Endpoint Privilege Management for Unix and Linux REST API will use an authentication method developed by Amazon Web Services that uses a pre-shared key and HMAC signature.

An Application ID, devised by the administrator, is input into a key store maintenance program that stores the ID alongside a randomly generated Application Key, and specified ACLs that specify what access the Application ID has. The Application Key is output, and these two together form the authentication mechanism.

The Application ID and a timestamp (epoch seconds) of information are hashed together using the Application Key to make an MD5 HMAC signature that is appended onto the URL of each call. It checks the timestamp to make sure it is relatively recent, retrieves the Application ID, and produces the HMAC using the same parameters to make sure the authentication is valid. The key store is encrypted by default, and can be relocated using configuration in pb.settings.

Installation and Configuration

The REST API is bundled in tar files and package installers.

Prerequisites

• A suitable web server that supports Fast CGI protocol, configured to support Fast CGI modules and HTTPS/SSL (with a suitable certificate). This includes the enabling of any firewalls to allow HTTPS access.
• Endpoint Privilege Management for Unix and Linux v7.1.0 or above preinstalled and configured.
• Root access on the host that will provide REST API to enable the installation of the module.
• For development with the Java example sources, a Java 7 JDK is required, and the Eclipse IDE project files are provided for convenience.

The REST API must be installed on different Endpoint Privilege Management for Unix and Linux hosts, based on the functionality required:

REST API Installed Files

tempfilepath defines a temporary path to be used as the temporary filesystem for EPM-UL binaries. The default is set as /tmp. At install time, if pbinstall is invoked, using -t <tempdir> option, tempfilepath is set to <tempdir>. lockfilepath defines a lock file path for EPM-UL binaries as needed. The default is /opt/pbul/locks.

When REST API is installed, the following files are copied to the host:

• The binary pbrestcall is copied to the Administration Program Location (/usr/sbin, by default ).
• The binary pbconfigd is copied to WWW server CGI directory specified during the installation.
• The sample code files are copied to the REST API sample code directory specified during the installation:
  • examples/lighttpd/: Example configuration files for lighttpd. The contents of these are referenced below in the example configuration of web server
  • examples/java/: Java sources and Eclipse project for Java API examples
  • examples/java/PBULAPI/build.xml: Ant build script to build the Java .jar
  • examples/java/PBULAPI/doc: Javadoc documentation
  • examples/jsoncalls.html: Example of static HTML file, containing JavaScript implementation of JSON API. The file contains JavaScript sections that implement the MD5 HMAC required to make the REST call.
  • examples/java/PBULAPI/test: JUnit test suite to test all areas of the JSON REST API using Java
  • examples/java/PBULAPI/src/*: The Java example source to call the REST API
  • examples/scripts/: Example bash scripts that implement JSON API calls

For more information on pbrestcall and pbconfigd, see pbrestcall and pbconfigd.

pblighttpd Service

pblighttpd is the HTTP server daemon which launches the REST service. It is configured to run as a service in the background on hosts where an Endpoint Privilege Management for Unix and Linux server component is installed. After a successful installation, the pblighttpd service is configured to startup and shutdown systemd/xinetd/init on Linux, init on HP-UX, inittab for AIX, and SMF for Solaris 10+.

Stop pblighttpd

When pblighttpd service receives a stop request, its main process will ensure that all its child processes have terminated before it exits. This feature, combined with a lock file mechanism, helps prevent a new set of processes from starting before the old set has cleaned up and exited.

Start pblighttpd

The pblighttpd service is comprised of a set of processes which is monitored by a parent process. A lock file mechanism is used to ensure that only one set exists at a time.

To avoid running out of resources during heavy load while support authentication events to a program (eventdestinations authevt=|program), pblighttpd-svc must be started with unlimited NOFILES and NPROC, at least. For example, on Linux with systemd:

# cat /etc/systemd/system/pblighttpd.service
[Unit]
Description=BeyondTrust Privilege Management - REST Server
After=network.target
[Service]
Type=forking
Environment=LD_LIBRARY_PATH=/opt/pbul/rest/lib:/opt/pbul/lib:/usr/lib/oracle/19.5/client64/lib
ExecStart=@/opt/pbul/rest/sbin/pblighttpd-svc pblighttpd-svc -d -i xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ExecReload=/bin/kill -HUP $MAINPID
TasksAccounting=false
LimitNPROC=infinity
LimitNOFILE=infinity
LimitCORE=infinity
[Install]
WantedBy=multi-user.target

For legacy sysV, simply add ulimit -u unlimited and ulimit -n unlimited to the start routine of /etc/rc.d/init.d/pblighttpd.

Restart pblighttpd when pb.settings is changed

The pblighttpd service must be restarted when the following keywords are changed in pb.settings:

• svccacherefresh
• dbsyncrefresh
• pblicenserefresh
• autofwdtime
• iologactioninterval
• sharedlibssldependencies
• sharedlibcurldependencies
• schedulingservice
• restservice
• pbrestlog
• messageroutersocketpath
• messagerouterqueuesize

pblighttpd_svc.sh

pblighttpd_svc.sh is a wrapper script that can start, stop, and restart pblighttpd on any of the supported platforms. It is installed in the same location as the other EPM-UL administration programs.

Syntax

<prefix>pblighttpd_svc.sh<suffix> <action>

where <action> is one of the following:

• stop: Stop the pblighttpd service
• start: Start the pblighttpd service
• restart: Stop and then start the pblighttpd service

When used to stop the pblighttpd service, the script ensures that all the processes associated with pblighttpd have terminated before exiting and returning to the command prompt.

On systems where processes take a long time to exit, the script may appear hung when it is just waiting for a child process. Use ps or a similar tool to list running processes and check for pblighttpd.

When being requested to start the pblighttpd service, the script errors out if it detects that a pblighttpd service is already running.

The script uses the pbdbutil (pbadmin) option to check if pblighttpd and pbconfigd processes are accepting requests before attempting to stop or restart.

<prefix>pbdbutil<suffix> --info --restsvr

If not accepting requests, the script displays “The process does not seem to accept requests, attempting to <stop/restart> anyway” to inform you of current status but proceeds with stopping or restarting the service anyway.

Endpoint Privilege Management for Unix and Linux REST API Programs

pbconfigd

• Version 8.5.0 and earlier: pbconfigd setting not available
• Version 9.0.0 and later: pbconfigd setting available

The pbconfigd binary is utilized by the pblighttpd process to provide REST services. Much of the functionality that is provided by newer versions of Endpoint Privilege Management for Unix and Linux uses facilities that the REST services provide. These include secure communication between services across the enterprise, a reliable replicated database layer, scheduled tasks that provide automated maintenance and housekeeping for background processes, the REST API layer used by the BeyondInsight for Unix & Linux GUI management tool, and can be used by customers to integrate Endpoint Privilege Management for Unix and Linux with their own in-house processes and systems.

pbconfigd is launched by the pblighttpd server and communicates in JSON over the FastCGI protocol. The service is started automatically by the operating system and services requests when various other facilities of Endpoint Privilege Management for Unix and Linux require it. Primary servers tend to instantiate more pbconfigd processes so that they can more readily serve secondary servers and clients with services such as Registration Name Service, Role Based Policy configuration, File Integrity Monitoring, and Licensing framework. Client hosts do not generally run pbconfigd processes, but can momentarily launch the service to allow client configuration or to retrieve valuable data for the BeyondInsight for Unix & Linux management GUI.

As more Endpoint Privilege Management for Unix and Linux facilities become more reliant upon the REST service for reliable and successful functioning, it is vital to make sure that the service is working correctly. We recommend the REST log file be closely monitored and the troubleshooting guide used whenever issues are noted.

Generally pbconfigd is launched automatically by the pblighttpd service and should not be launched manually.

pbconfigd has a --call option. This action requires a JSON string parameter to process and processes as if the call was made over REST. This allows specific calls that are required to action licensing and message router queuing calls to be made.

Usage

pbconfigd [options]
    -v, --version
    --help

Arguments

For more information, see pblighttpd Service.

pbrestcall

• Version 8.0 and earlier: pbrestcall setting not available
• Version 8.1.0 and later: pbrestcall setting available

The pbrestcall utility provides a method of making REST API calls from the command line. It calculates the MD5 HMAC of the header to provide authentication, and encodes command line parameters on the URL.

pbrestcall -l -a appid -k f339c33b-64d7-44f4-b113-34e344cff670 https://myhost:24351/REST/settings

This retrieves and display all of the /etc/pb.settings from the Policy Server host using the REST API, and the -l parameter lists them in a formatted JSON format.

Usage

pbrestcall [options] [param=value param=value…]
    -a <appId> [<acl> ...]
    -k <appKey>
    -d
    -X
    -l
    -v
    -t
    -p

The URL with HMAC and timestamp can be printed using the -p parameter. MD5 HMAC along with timestamp (see the setting pbresttimeskew) authenticates the session.

pbrestcall -p -l -a appid -k f339c33b-64d7-44f4-b113-34e344cff670 https://myhost:24351/REST/settings

Response https://myhost:24351/REST/settings?appid=appid&timestamp=1620676163&hmac=9623fe94d48e50d2d600efd518613392

Arguments

Configuration of pbconfigd FastCGI Module

The pbconfigd specific parameters below may need to be added to /etc/pb.settings manually.

restkeyencryption

• Version 8.0 and earlier: restkeyencryption setting not available
• Version 8.1.0 and later: restkeyencryption setting available

This is similar to other encryption keywords but only takes one value at a time.

restkeyencryption <algorithm-1>:<keyfile=/fullpath/data-file-1>
[:<startdate=yyyy/mm/dd>:<enddate=yyyy/mm/dd>]

restkeyencryption aes-256:keyfile=/etc/pb.key

Default

restkeyencryption aes-256

Used on

• All hosts where pbconfigd is installed

For more information, see networkencryption.

pbrestlog

• Version 8.0 and earlier: pbrestlog setting not available
• Version 8.1.0 and later: pbrestlog setting available

This option configures where the pbconfigd binary should log debug and error messages.

pbrestlog /var/log/pbrest.log

Default

Depending on the operating system standards, this can be any of the following:

• /var/log/pbrest.log
• /var/adm/pbrest.log
• /usr/adm/pbrest.log

Used on

All hosts where pbconfigd is installed

pbrestkeyfile

• Version 8.0 and earlier: pbrestkeyfile setting not available
• Version 8.1.0 and later: pbrestkeyfile setting available

This option allows the specification of where the pbconfigd keys are kept. This keystore is encrypted using the restkeyencryption option above. It may be written as an absolute path, or a path relative to the databasedir setting.

pbrestkeyfile /mypath/pbrstkeys.db

Default

pbrestkeyfile /opt/pbul/dbs/pbrstkeys.db

Used on

All hosts where pbconfigd is installed

REST ACL’s

To allow different applications to have different access over the REST API, ACLs have been implemented and can be created against given application ID’s. These take the form of regular expressions that match specific REST API URLs. Each application ID can have up to 8 regular expressions assigned to it.

Examples

Configuration of pbconfigd Keystore

To enable the authentication of REST API sessions pre-shared keys are created with application identifiers. These are used to identify the application and to create a MD5 HMAC (along with a timestamp) to authenticate the session.

pbdbutil --rest -g appid

This creates an application ID of appid and displays the application key, which needs to be noted, as it cannot be retrieved and added to the web application.

Specify a REST URL Path and Parameters

RESTful interfaces use the URL path to specify data and attributes, not actions. Actions are specified using the HTTP request methods GET, PUT, POST, and DELETE. Data is grouped together in the URL path, so for example all Endpoint Privilege Management for Unix and Linux settings are specified in the path /REST/settings (or /REST/setting when accessing a single setting). HTTP GET requests always pass parameters (URL encoded) as URL parameters on the URI. PUT, POST, and DELETE can use either the URI or the HTTP body to pass more complicated data.

GET https://<host>:<port>/REST/iolog?file=%2f/tmp%2fiolog%2broot%2elog

PUT https://<host>:<port>/REST/setting/submitmaster
{ "setting": {"values":["pbuild","pbuild2","pbuild3"]}}