Check Point Harmony Security Custom Response Integration

Check Point Harmony Security Custom Response Integration

This article shows how to leverage the Lumu Defender API and Check Point Harmony Security API to mitigate security risks.


Requirements

  • Harmony Email Security subscription.
    • A Harmony subscription with Office 365 mail or Gmail SaaS applications configured
  • Lumu Defender API key
    • To retrieve an API token, please refer to the Defender API document.
  • A Docker-enabled host
  • This host will be used to deploy the integration component.
    • It must have Internet visibility over the Lumu Defender API endpoints and the Harmony Email Security API endpoints.
  • Component and Script package

Contacted hosts

Ensure your integration host can communicate with the following hosts. These are required for the operation of this integration.
  1. Harmony Authentication and Email Security URLs.
  2. defender.lumu.io
  3. docker.io

Integration’s overview

The Lumu Custom integration with Harmony Email & Collaboration uses the Harmony Email Security API to manage Anti-phishing exceptions. These exceptions allow Harmony to prevent, detect, and remediate emails with Lumu detection-related hashes and URLs. Any mail matching these exceptions will be treated according to the protection mode defined in the policy rules.

Preliminary Setup - Check Point Harmony Security

To set up the integration, you must prepare your Harmony Email & Collaboration deployment to communicate with the Lumu integration by creating a new account API key associated with the Email & Collaboration service.

Next, we will guide you through the process to fulfill this requirement.

Create an account API key

1. Open your Web browser and access the Check Point Infinity Portal. Log in into the portal if you are not already logged in.
2. On the top navigation bar, click the Gear icon on the right side of the screen. Then, click on API Keys.
3. On the API Keys window, click on New at the top of the page. Then click New account API key.
4. Fill the required information within the CREATE A NEW ACCOUNT API KEY modal as follows:
a. Under Service (1), search for and select the Email & Collaboration option. You can type in the field to narrow down the options shown.
b. Set an Expiration (2) date and time by clicking on the calendar and the scroll buttons. Choose an expiration date based on your internal security policy guidelines.
c. Under Description (3), type a distinctive description to identify the API key
d. When done, click on the blue Create (4) button.
e. A new window will appear, containing the Client ID (5), Secret Key (6), and Authentication URL (7). Make sure you store this information safely. Once you do, click Close (8).
Warning
This will be the only time you will be able to record it. If you lose this info, you will need to do the entire process from the beginning.

Preliminary setup - Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:
  • Lumu Defender API key
  • Company UUID
Log in to your Lumu portal and run the following procedures to collect these data.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, please refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.


Preliminary Setup - Docker-enabled host

Follow the steps below if your integration host does not have Docker installed. You must follow the Docker installation documentation that corresponds to your OS. Ensure you follow the Post-installation steps for Linux before deploying the integration.
NotesFor Windows users, follow the Install Docker Desktop for Windows documentation to install the Docker Engine.

Deploy the integration

The following sections will guide through the deployment process. 

Set up the Management Script

Lumu prepared a short snippet to manage the integration. Create a file named manage.sh in your integration host. Copy and paste the following code.
Code snipett
#!/usr/bin/env bash

RED='\033[0;31m'
GREEN='\033[0;32m'
CYAN='\033[0;36m'
YELLOW='\033[1;33m'
BOLD='\033[1m'
RESET='\033[0m'

info() { echo -e "${CYAN}[INFO]${RESET} $*"; }
success() { echo -e "${GREEN}[OK]${RESET} $*"; }
warn() { echo -e "${YELLOW}[WARN]${RESET} $*"; }
error() { echo -e "${RED}[ERROR]${RESET} $*" >&2; }
prompt() { echo -e "${BOLD}${YELLOW}$*${RESET}"; }

IMG=lumutools/harmony-email-threat-feeder:latest
INTEGRATION_NAME=harmony-email-threat-feeder
INTEGRATION_NAME_IOC=harmony-email-threat-feeder-ioc
INTEGRATION_DIR=${HOME}/HarmonyEmailResponse
VOLUME_DATA=${INTEGRATION_DIR}/data:/app/data
VOLUME_CONFIG=${INTEGRATION_DIR}/data/.config.toml:/app/.config.toml:ro
VOLUME_IOC=${INTEGRATION_DIR}/data/ioc.db:/app/data/ioc.db:ro

mkdir -p "${INTEGRATION_DIR}/data"
chmod -R o+w "${INTEGRATION_DIR}/data" > /dev/null 2>&1

run_config() {
info "Running configuration script ..."
if docker run --rm -it -v "${INTEGRATION_DIR}/data:/app/data" "${IMG}" bash run_config; then
success "Configuration completed."
else
error "Configuration script failed."; return 1
fi
}

start_integration() {
info "Setting up IOC integration '${INTEGRATION_NAME_IOC}' ..."
if [[ ! -f "${INTEGRATION_DIR}/data/.config.toml" ]]; then
error "Please configure the integration first."; return 1
fi
if ! docker container inspect "${INTEGRATION_NAME_IOC}" &>/dev/null; then
info "Integration '${INTEGRATION_NAME_IOC}' does not exist. Creating it ..."
if ! docker create \
-v "${VOLUME_DATA}" \
-v "${VOLUME_CONFIG}" \
--restart unless-stopped \
--log-driver json-file \
--log-opt max-size=30m \
--log-opt max-file=3 \
--name "${INTEGRATION_NAME_IOC}" \
"${IMG}" bash run_ioc; then
error "Failed to create IOC integration."
return 1
fi
else
warn "Integration '${INTEGRATION_NAME_IOC}' already exists. Skipping its creation."
fi
if docker start "${INTEGRATION_NAME_IOC}"; then
success "IOC integration started."; sleep 5
else
error "Failed to start IOC integration."; return 1
fi

info "Setting up main integration '${INTEGRATION_NAME}' ..."
if ! docker container inspect "${INTEGRATION_NAME}" &>/dev/null; then
info "Integration '${INTEGRATION_NAME}' does not exist. Creating ..."
if ! docker create \
-v "${VOLUME_DATA}" \
-v "${VOLUME_CONFIG}" \
-v "${VOLUME_IOC}" \
--restart unless-stopped \
--log-driver json-file \
--log-opt max-size=30m \
--log-opt max-file=3 \
--name "${INTEGRATION_NAME}" \
"${IMG}" bash run_component; then
error "Failed to create main integration."; return 1
fi
else
warn "Integration '${INTEGRATION_NAME}' already exists. Skipping create."
fi
if docker start "${INTEGRATION_NAME}"; then
success "Main integration started."
else
error "Failed to start main integration."; return 1
fi
}

check_status() {
info "Checking status of integrations ..."
if [[ ! -f "${INTEGRATION_DIR}/data/.status.ndjson" ]]; then
error "Status check failed. Verify if your integration has been deployed."; return 1
fi
if docker run --rm -it -v "${VOLUME_DATA}":ro "${IMG}" bash run_status; then
success "Status check completed."
else
error "Status check failed."; return 1
fi
}

show_logs() {
echo ""
prompt "Select which logs to view:"
echo -e " ${CYAN}1${RESET}) IOC integration (${INTEGRATION_NAME_IOC})"
echo -e " ${CYAN}2${RESET}) Main integration (${INTEGRATION_NAME})"
echo ""
read -rp "$(prompt 'Enter option [1/2]: ')" choice
case "${choice}" in
1)
info "Showing logs for '${INTEGRATION_NAME_IOC}' ..."
docker logs --tail 100 -f "${INTEGRATION_NAME_IOC}"
;;
2)
info "Showing logs for '${INTEGRATION_NAME}' ..."
docker logs --tail 100 -f "${INTEGRATION_NAME}"
;;
*)
error "Invalid option '${choice}'."
return 1
;;
esac
}

usage() {
echo ""
prompt " HARMONY EMAIL SECURITY RESPONSE INTEGRATION MANAGEMENT"
echo -e " ${BOLD}Usage:${RESET} $0 "
echo ""
echo -e " ${CYAN}config${RESET} Run configuration"
echo -e " ${CYAN}start${RESET} Start integration"
echo -e " ${CYAN}status${RESET} Check integration status"
echo -e " ${CYAN}logs${RESET} Show integration logs"
echo ""
}

case "${1}" in
config) run_config ;;
start) start_integration ;;
status) check_status ;;
logs) show_logs ;;
*) usage
[[ -n "${1}" ]] && error "Unknown command '${1}'."
exit 1 ;;
esac



Using the Management Script

With the management script, you can:
  1. Configure the integration.
  2. Start the integration.
  3. Check the status of the integration.
  4. Check the audit logs of the integration.
You can check these options by running the following command:
bash manage.sh

The following sections outline how to use each option.

Set up the configuration parameters

Before activating the integration, execute the following command:
bash manage.sh config

A setup wizard will guide you. Type in the parameters you collected during the preliminary setup. The wizard verifies if the provided parameter values will allow the integration to work properly.
Alert You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment and runtime of the integration.
NotesWe strongly recommend correcting any credential errors before attempting to start the integration using the start command.

Run the Integration

You are ready to run the integration. You can start it by running this command:
bash manage.sh start

Notes If you have run this process before, you may receive warning messages about the existence of components. To ensure you have the latest version of the integration, we recommend removing the existing integration containers before entering the start command.

Check the integration status

You can check the integration status after it has been activated. Run the following command to check its current status.
bash manage.sh status

If the script reports errors during the integration operation, head to the Show logs section to check how to collect additional details.

Show logs

Notes We kindly request you to, when issuing a support case, attach the integration logs collected using the steps described in this section.
The logs option allows you to view the integration's logs. You can select to check either the IOC component’s logs or the integration’s logs.

1. IOC integration: This component keeps an up-to-date record of IOCs from Lumu detections. Here, you can check Lumu API-related errors.
2. The main integration: This component manages the IOCs’ lifecycle in the third-party platform based on the data curated by the first component. Here, you can check any third-party API error raised during the IOC management tasks.

Expected results

All the uploaded IOCs can be found in the Anti-Phishing Block-List module under the Harmony Email & Collaboration configuration. You can get here by clicking on Security Settings on the left-hand menu and clicking on the Exceptions header. The list is under the Anti-Phishing option.

Ensure you select the Block-List option next to the Anti-Phishing Exceptions title. You will see the list of the exception managed by the integration.

After the IOCs are uploaded to your Harmony Email & Collaboration subscription, further events will be detected and marked as Phishing attempts in the Check Point portal, under the Events header in the left-handleft hand menu. The uploaded IOCs will enhance the current visibility of your Harmony Email & Collaboration subscription. All detections must be addressed according to your policies.

Troubleshooting

You can use the management snippet for general troubleshooting. Here, you will find additional commands to run additional diagnostics if they are needed.
  • Stopping the integration
    Run the following command if you need to stop the integration.
    docker stop harmony-email-threat-feeder
    docker stop harmony-email-threat-feeder-ioc
  • Starting the integration
    Run the following command to start the integration.
    docker start harmony-email-threat-feeder-ioc
    docker start harmony-email-threat-feeder-ioc

Known issues

In this section, we collect all the potential issues you will find after you run the troubleshooting commands from the above section.

Docker permission execution

If you get an error similar to the following when you start the integration.

Follow the steps outlined in the Linux post-installation steps for Docker Engine - Manage Docker as a non-root user documentation and start over the integration.

Network Connection Problems

Logs indicating a connection problem will often contain keywords such as timeout or connection error. These terms are suggestive of an underlying network issue. Check the internet status and the network visibility from the integration host to the APIs listed in the Contacted Hosts section, and try again.