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 ?

Quick Setup with Initial Deployment Script

The easiest way to get started is using the automated initial deployment script:

# Download or clone the repository
git clone https://github.com/mpgn/PingCastle-Notify.git
cd PingCastle-Notify

# Run the initial deployment script
.\initial-deploy.ps1

After running the script, you'll need to:

1. Edit the .env file to add your specific tokens/webhooks
2. Configure your chosen notification platform (see sections below)
3. Run .\PingCastle-Notify.ps1 to start monitoring

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

The .env file contains all configuration options. If you used the initial deployment script, this file is already created with your selected connectors enabled.

# Domain Configuration
DOMAIN=your-domain.local

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

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

# Teams Workflow Configuration
TEAMS_WORKFLOW_ENABLED=0
TEAMS_WORKFLOW_URL=https://prod-xx.westus.logic.azure.com:443/workflows/xxx

# Discord Configuration
DISCORD_ENABLED=0
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url

# Report Configuration
PRINT_CURRENT_RESULT=1
ANSSI_LVL=1

Configuration Options:

• DOMAIN: Your Active Directory domain (auto-configured by initial deploy script)
• 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 webhook notifications
• TEAMS_WORKFLOW_ENABLED: Set to 1 to enable Teams Power Automate workflow
• DISCORD_ENABLED: Set to 1 to enable Discord notifications
• PRINT_CURRENT_RESULT: Set to 1 to include current scan results in notifications
• ANSSI_LVL: Set to 1 to enable ANSSI compliance level reporting

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

▶️ Teams WorkFlow (prefered for Teams)

1. Start a new workflow: In Microsoft Teams, navigate to your desired channel, click the three dots (...), and select Workflows. Then, click Create a workflow.
2. Set the trigger: Search for and select the trigger "When a Teams webhook request is received." This action provides a unique URL that will listen for incoming POST requests.
3. Add a new action: Click on New step.
4. Configure the action: Search for and select the action "Post message in a chat or channel."
   • For Post as, choose Flow bot to ensure the message comes from the workflow itself.
   • Select the Team and Channel where the message should be posted.
5. Define the message content: In the Message field, click on the Expression tab. Enter the following expression: triggerBody()?['pingcastle'] This expression tells the workflow to look for a key named pingcastle within the JSON payload of the incoming webhook request and use its value as the message content.
6. Save and get the URL: Save the workflow. Once saved, expand the trigger step "When a Teams webhook request is received." The unique HTTP POST URL will be displayed there. You can now use this URL to send a message to the Teams channel. Any POST request to this URL with a JSON body containing a key named pingcastle will have the corresponding value posted as a message.
7. Update the .env file

Usage

Basic Usage

Run the script to perform a PingCastle scan and send notifications:

.\PingCastle-Notify.ps1

Advanced Usage

No-Scan Mode

Skip the PingCastle scan and only process existing reports:

.\PingCastle-Notify.ps1 -noscan

This mode is useful for generating the diff without running PingCastle.exe in case you already send all the report into a custom share.

Note: The -noscan mode requires existing PingCastle reports to be present in the expected location.

Verbose Output

Enable detailed information output for debugging:

.\PingCastle-Notify.ps1 -InformationAction Continue

Or combine with noscan mode:

.\PingCastle-Notify.ps1 -noscan -InformationAction Continue

Deploy a Scheduled Task

▶️ Make sure the scan is automatic and run every day

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