PingCastle Notify

PingCastle Notify is a tool that will monitor your PingCastle reports ! You will be notified every time a change between a scan and a previous scan is made.

How it works ? PingCastle-Notify is a PS1 script that will run a PingCastle scan, compare the difference between a previous scan, highlight the diff and send the result into a Slack / Teams channel or a log file !

The slack/teams/log message will notify you regarding the different states: correction, recession etc

⚠️ If you don't want to use Slack or Teams set SLACK_ENABLED=0 and TEAMS_ENABLED=0 in the .env file. Skip the step "Create a BOT" and check the log file inside the Reports folder.

---

▶️ First scan

Slack	Teams

▶️ No new vulnerability but some rules have been updated

▶️ New vulnerabilty

Slack	Teams

▶️ Some vulnerability have been removed

Slack	Teams

▶️ No new vulnerability

No result in slack since reports are the same

---

🔰 Adding the result of the current scan

Set the variable $print_current_result to 1 in the script, the rules flagged on the current scan will be added as a thread into Slack or after the rule diff on Teams.

Slack	Teams

How to install ?

Structure of the project

SECU-TOOL-SCAN/
    - PingCastle-Notify.ps1
    - .env                  <-- Configuration file
    - modules/
        - Slack.psm1
        - Teams.psm1
    - PingCastle/
        - Reports/
            - domain.local.xml
            - domain.local.html
            - scan.logs <-- contains the logs of the scan (diff scan)
        - Pingcastle.exe
        - ...

PingCastle & PingCastle-Notify.ps1

1. Download PingCastle
2. Unzip the archive
3. Create a "Reports" folder inside the PingCastle folder
4. Download the PingCastle-Notify repository
5. Copy .env.example to .env and configure your settings

Configuration

Create a .env file in the root directory with your configuration:

# Copy the example file
cp .env.example .env

Then edit the .env file with your settings:

# Slack Configuration
SLACK_CHANNEL=#pingcastle-scan
SLACK_TOKEN=xoxb-your-slack-bot-token-here
SLACK_ENABLED=1

# Teams Configuration  
TEAMS_ENABLED=0
TEAMS_URI=https://your-org.webhook.office.com/webhookb2/your-webhook-url-here

# Report Configuration
PRINT_CURRENT_RESULT=1

# Domain Configuration
DOMAIN=your-domain.local

Configuration Options:

• SLACK_ENABLED: Set to 1 to enable Slack notifications, 0 to disable
• SLACK_CHANNEL: The Slack channel to send notifications to (include the #)
• SLACK_TOKEN: Your Slack bot token (starts with xoxb-)
• TEAMS_ENABLED: Set to 1 to enable Teams notifications, 0 to disable
• TEAMS_URI: Your Teams webhook URL
• PRINT_CURRENT_RESULT: Set to 1 to include current scan results in notifications
• DOMAIN: Your domain name (optional, will use $env:USERDNSDOMAIN if not set)

Create a BOT

▶️ Slack BOT

1. In Slack create an application https://api.slack.com/apps
2. Add the following rights
   • Click on "Add features and functionality" -> Bots (configure the name)
   • Click on "Add features and functionality" -> Permissions (add the following permissions)
   • Generate a "Bot User OAuth Token" on the Permissions tab

3. Get your token and add it to the .env file as SLACK_TOKEN
4. Create a slack channel and add your bot user to the channel
5. You can test your bot using https://api.slack.com/methods/chat.postMessage/test
6. Add the channel to the .env file as SLACK_CHANNEL
7. Set SLACK_ENABLED=1 in your .env file
8. Run the script to test using this command: powershell.exe -exec bypass C:\YOUR_PATH\SECU-TOOL-SCAN\PingCastle-Notify.ps1

▶️ Teams BOT

1. Create a channel pingcastle-scan
2. Click on the "..." dots and select "Connectors"
3. Search for Webhook
4. Add the webhook
5. Re-click on the connectors button and on the webhook click "configure"
6. Add a title and a logo and click Create, copy the webhook URL
7. Update the .env file:
   • Set TEAMS_ENABLED=1
   • Set TEAMS_URI to your webhook URL

Deploy a Scheduled Task

On your Windows Server go to

1. Create a service account that will run the PS1 script every night (no need to set the service account as domain admin)
2. Give privileges to the service account on the folder "Reports"

3. Run taskschd.msc to open the Scheduler Task
4. Create a Task and use the service account you just created
5. In Actions tab set "Start a program" -> "Script": C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -> "Arguments" -> -exec bypass -f C:\PINGCASTLE\Pingcastle-Notify.ps1
6. Give the permission "Log on as Batch Job" to service account https://danblee.com/log-on-as-batch-job-rights-for-task-scheduler/
7. Run the scheduled task to test the result
8. Enjoy :)

Adding a New Connector

The PingCastle-Notify system is designed to be easily extensible. You can add new notification connectors (Discord, Email, SMS, etc.) by creating a new module file.

Step 1: Create the Module File

Create a new PowerShell module file in the modules folder:

modules/YourConnector.psm1

Step 2: Test Your Connector

1. Place your module file in the modules folder
2. Add configuration to .env
3. Run the script - your connector will be automatically discovered and loaded
4. Check the console output for "Loading module: YourConnector"

Notes

• No changes needed to the main script when adding new connectors
• The system automatically discovers all .psm1 files in the modules folder
• Function names must follow the pattern: FunctionName-YourConnectorName
• Your connector will only be used if enabled in the .env file
• Both hashtable and string body types are supported

Acknowledgement

• Vincent Le Toux - https://twitter.com/mysmartlogon
• Romain Tiennot - https://github.com/aikiox
• Lilian Arago - https://github.com/NahisWayard
• Romain Bourgue - https://github.com/raomin

License

MIT License