PingCastle

About this document

This document provides a step-by-step procedure for configuring PingCastle in SAFE.

Introduction

The integration between SAFE and PingCastle enables SAFE to ingest Active Directory security assessment results generated by PingCastle scans. SAFE imports domain risk findings and associated assessment data to provide centralized visibility and risk analysis within the SAFE platform.

Since PingCastle is executed within the customer’s on-premises Active Directory environment, SAFE provides an on-premises connector that runs on the customer’s local network. The connector securely receives scan reports locally and forwards the processed result to SAFE, ensuring that sensitive Active Directory data, credentials, and internal systems remain protected.

Integration Flow

The integration follows a store-and-sync model, designed to keep scan execution fully within the customer’s environment while enabling secure ingestion into SAFE.

1. PingCastle Scan Execution

   The customer executes PingCastle scans within their environment using their preferred scheduling mechanism (for example, a Windows Scheduled Task).

2. Local Report Submission

   The generated PingCastle reports are submitted to a lightweight local service hosted inside the SAFE connector, which mimics the PingCastle Enterprise server endpoint.

3. Local Buffering of Reports

   The connector securely stores (buffers) the received reports as unprocessed assessment data within the customer’s environment until synchronization occurs.

4. Connector Polling for Sync Commands

   The SAFE connector (running as a Docker container) continuously polls the SAFE platform every 10 minutes to check whether a Sync operation has been triggered. For this reason, the connector container must remain running at all times to ensure reliable communication and timely data synchronization.

5. Synchronization with SAFE

   When a scheduled or manual Sync operation is initiated from SAFE, the platform retrieves all unprocessed reports from the connector.

6. Processing and Risk Analysis

   SAFE processes the reports, ingests the findings, and updates risk insights and analytics within the platform.

Prerequisites

Functional Prerequisites

• Install Docker CE Engine

  • Docker Desktop for Mac v3.5.1

  • CentOS

  • Ubuntu

• Host machine with Docker installed, to set up an on-premise Docker-based component for communicating with SAFE

• Network access from the host machine to the following:

  • SAFE Instance (Refer to SAFE’s Outgoing IP Addresses  )

  • PingCastle Instance

  • A 32-character-long Encryption Key (Refer to the FAQs section for more details)

Host Prerequisites

• Docker Engine on the server where the PingCastle connector needs to be deployed.

• For on-premise deployment with PingCastle integration, we recommend the following Docker configurations :

  • CPU: Minimum 2 vCPUs

  • Memory: 8 GB RAM

  • Storage: 100 GB available disk space

PingCastle Prerequisites

• The PingCastle must be installed on your device - https://www.pingcastle.com/download/

Configure PingCastle with SAFE

Follow the steps below to configure the PingCastle integration in SAFE

SAFE Setup

1. Log in to SAFE and navigate to SAFE Integrations.

2. Click the + button available at the top-right.

3. Search and click the PingCastle card.
   

4. Click Generate Integration ID to view the required commands, as shown below.
   

5. The generated commands need to be configured on the on-premises connector, as covered in the next section.

On-Premise connector setup

1. Run the Docker Pull Command on the terminal.
   

   docker pull safesecurity/pingcastle-connector:1.0.1

2. Run the Docker Start Command and replace '<MOUNT_PATH_IN_HOST_MACHINE>' with the actual value.
   

   docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config --name safe-pingcastle-connector safesecurity/pingcastle-connector:1.0.1 && docker exec -it safe-pingcastle-connector bash initialise.s

3. Fill in the required details as per the prompt shown on the terminal:

   Note

   The PingCastle API key is used to prevent unauthorized report submissions to the server. It is generated and managed by the customer, similar to the encryption key.

   

   Note

   For the first time setup, provide values for all prompts. In the subsequent runs, only the encryption key is mandatory. The encryption key provided in subsequent runs should be the same as the one provided during the first-time setup. To change other configuration values in the subsequent runs, provide a new value for the same.

4. Once all required details are provided, logs similar to the following will be displayed:
   

[Optional] Proxy Setup

Follow the steps below to set up the proxy:

1. On the prompt “Do you want to configure a proxy? (Yes/No)” -  If Yes, fill in all required fields below.

   1. Enter proxy IP (Optional if configured previously): <IP>

   2. Enter proxy port (Optional if configured previously): <PORT>

   3. Enter proxy username (Optional if configured previously): <PROXY_USERNAME> If configured on Proxy

   4. Enter proxy password (Optional if configured previously): <PROXY_PASSWORD> If configured on Proxy

   5. Enter comma-separated list of no proxy IP/DNS (leave empty if none): <IP>
      

2. Leave all fields empty if the proxy was already configured, and you want to keep it the same.

PingCastle Setup

Schedule a cron job to deposit reports  into our server using the  following command:

PingCastle.exe --healthcheck --server example.local --api-endpoint http://api.example.com:<PORT> --api-key <your-api-key> --level <level>

Details:

Security Considerations

Reports are encrypted at rest using the same 32-character encryption key that is used to secure other stored credentials. HTTPS transport is not currently supported.

A successful setup will result in the following output appearing in the PingCastle cron terminal.

Upon successful setup, Docker logs comparable to the following should be visible.

Set Auto Sync Frequency

1. Navigate to the Ping Castle Card on the integrations page.

2. Enter the auto-sync frequency, then click Save.
   

3. Once the configuration is saved, click the Sync Now button to trigger the on-demand sync outside of the scheduled auto sync.

4. If the setup is done correctly, Docker logs should appear during sync.
   

View Results

After a successful sync, the PingCastle assets are automatically imported into SAFE.

• On the PingCastle integration page, review the Assets and Findings

• Alternatively, you can navigate to Technology > Assets and filter the assets list to Onboarding Source equal to security.safe.pingcastle.

• When you click a finding, you can see its score and the CAM Control Mapping related to it.
  

Severity mapping

PingCastle generates findings with scores ranging from 0 to 100 and provides a legend describing how these scores represent risk levels within Active Directory assessments. Based on the PingCastle scoring legend, SAFE maps PingCastle scores to SAFE severity levels to ensure consistent risk representation within the SAFE platform.

PingCastle Score Interpretation

FAQs

How to generate a Encryption Key?

• SAFE’s on-premises connector for PingCastle uses offline encryption to protect PingCastle and SAFE API credentials on the machine.

• The encryption key required for this has to be exactly 32 characters and must be entered every time the container has to be started/updated/re-started.

• 32 bytes encryption key can be generated using any online tool, e.g., RANDOM.ORG - String Generator.

• It is highly recommended to store the Encryption key in any PIM/PAM tool or any other credentials manager.

What to do if the Encryption Key is lost?

In the case when the Encryption Key is lost:

1. Remove the previously mounted config path directory on the host machine.

2. Reconfigure the on-premise connector.

How do I upgrade the connector when a newer version is available from SAFE?

Follow the steps below to upgrade the connector to a newer version:

1. Stop the currently running on-premise Connector using the following command:

   docker rm -f safe-pingcastle-connector

2. Copy the Docker pull command (which would have been updated with a newer version) and, after pulling the latest image for the PingCastle, go ahead with the starting command (i.e., the second command on the Hooks Page)

3. Keep the config path as configured earlier; no need to change it.

4. Enter the Encryption Key when prompted.

5. The user is not required to fill in any other details again (if they are already configured).

How to use private SSL certificates with the on-prem connector? (with Deep Packet Inspection-ing Firewalls)

• To be able to use private certificates, customers will have to ensure that the certificates are available in a directory on the server/machine where the On-prem connector is being configured. Let’s say <CERTIFICATES_DIRECTORY>

• You will also need the path to the certificate used to access the SAFE server from inside the container. So, if the certificate is ca-certificates.crt, then the path of the certificate file will be /etc/ssl/certs/ca-certificates.crt, for e.g. <CA_CERTIFICATE_FILE_PATH>

• To make the connector work using these certificates, modify the second command from Integrations page.

Original Command

docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config --name safe-pingcastle-connector safesecurity/pingcastle-connector:1.0.1 && docker exec -it safe-pingcastle-connector bash initialise.sh

Updated Command

docker run -d -v <MOUNT_PATH_IN_HOST_MACHINE>:/app/config -v <CERTIFICATES_DIRECTORY>:/usr/local/share/ca-certificates -e NODE_EXTRA_CA_CERTS=<CA_CERTIFICATE_FILE_PATH> --name safe-pingcastle-connector safesecurity/pingcastle-connector:1.0.1 && docker exec -it safe-pingcastle-connector bash initialise.sh