shmgw - SHM gateway

Standalone API translation gateway for Forcepoint SHM sandbox API calls to external providers. Currently it supports making requests to Check Point Software's Threat Prevention API.

Prerequisites

A server with networking configured such that:

1. the Forcepoint NGFW can reach the server for sandboxing requests and
2. the shmgw container can reach the Check Point gateway running the Threat Prevention API

The service runs in two docker containers. shgmw-nginx runs the web server, that handles incoming requests and forwards them to the shmgw-api container that does the actual API translation.

The service has been tested on Ubuntu 24.04 with Docker Engine (also known as Docker CE) version 28.0.1. Please follow these installation instructions if you need to install docker on your server. In addition the Docker Compose plugin is required for successful setup of the shmgw-* containers. Consult the Docker Compose plugin install instructions for setting up the plugin on your server.

Usage

The API gateway is provided in a git repository that contains all the necessary parts to take it into use.

Running the API gateway

Clone the shmgw repository and enter the directory:

cd shmgw

Before starting, fetch the CA certificate used by Check Point security gateway to the server, and copy it to the shgmw directory. The certificate must be in PEM format and named certificate.pem. The host entry in config file must also be changed to the correct hostname or IP-address of the Check Point security gateway providing the Threat Prevention API.

Finally to build and start the API gateway use

docker compose up -d

This will start the containers on port 5000 and use certificate.pem from current directory for verifying connections to the Threat Prevention API.

The port, certificate, and number of workers can be configured by editing the .env file in the shmgw directory. All variables are commented out by default. Uncomment and modify as needed:

# .env file
SHM_PORT=12000
GW_CERT=/path/to/ca-certificate.pem
WORKERS=4

Available environment variables:

• SHM_PORT: The listening port for the SHM API (default: 5000)
• GW_CERT: Path to CA certificate file for Threat Prevention API (default: ./certificate.pem)
• WORKERS: Number of gunicorn workers (default: CPU count * 2)

Alternatively, you can override settings by setting environment variables inline:

SHM_PORT=12000 GW_CERT=/path/to/ca-certificate.pem docker compose up -d

To stop the containers use:

docker compose down

In case you want to rebuild the API container image eg. to update some of the python dependencies execute the following commands to stop, clean old image and start container again:

docker compose down
docker rmi shmgw-api:latest
docker compose up -d

To view logs from the containers you can use the following commands:

docker compose logs

To filter logs based on container you can use:

docker compose logs api
docker compose logs nginx

Threat Prevention API configuration

The Threat Prevention API properties are configured in the config file. The options are documented below. The host option is mandatory for the API gateway to work properly.

[ThreatPrevention]
# The hostname or IP address at which the Threat Prevention API is running.
# Port can be added at end of hostname.
#host = myhost.com
#host = myhost.com:5000
#host = 1.2.3.4:4000

# Whether certificate of gateway is verified or not. If yes a CA cert file is
# required.
# Default value is yes
#verify_cert = yes

# Controls whether json messages sent and received are shown. Default is no.
#dump_messages = yes

# If wait_all_results is enabled the API will return 204/pending until all scans
# (sandbox and AV) have a result. Default is no.
#wait_all_results = no

# scan_duration controls the time in seconds the NGFW waits before starting to
# poll for results.
# This should be set according to the scan duration on CheckPoint gateway.
# Default is 240 seconds.
#scan_duration = 240

# Sets the timeout for connections to the Checkpoint Gateway
# Default is 5 seconds. The upload timeout is set to 4 times
# the provided timeout value.
#timeout = 5

If an option in the file is changed, API gateway container needs to be restarted using docker compose restart.

Forcepoint NGFW configuration

In Forcepoint Security Management Center (SMC) the sandboxing is configured in Engine Properties, Add-Ons, Sandbox. There the Sandbox Type should be selected as "Local Sandbox - Adwanced Malware Detection & Protection". Then a new sandbox service should be created similarly to the below picture:

It is important that the Data Centers is selected as "Local Sandbox - Adwanced Malware Detection & Protection". The "Host Name" field can be left empty. "Server URL" should be the IP-address or hostname of the server that runs the API gateway. The scheme of URL should always be http:// and the URL should contain the correct port for contacting the API gateway (see SHM_PORT in "Running the container").

If you want to download reports for the sandboxing scans, the "Portal URL" should be configured. The scheme host and port parts should be identical to the "Server URL". The path should be /report/[file_id].

A dummy value needs to be inserted in the "API KEY" part. A "TLS Profile" needs to be selected even though it will not be used.

It should now be possible to upload files inspected by the Forcepoint NGFW for sandboxing on the Check Point gateway, through the API gateway. This is done by enabling File Filtering in the access rules and enabling sandboxing in the File Filtering policy.