DOCSEARCHbyAlgolia
Submit Docs

PingCastle Documentation

repository·master·Indexed 25 days ago

https://github.com/netwrix/pingcastle

A security assessment tool for evaluating Active Directory and Entra ID security risks. Features include health checks, Entra ID scoring, domain mapping, and workstation scanning. Includes documentation for the PingCastleAutoUpdater tool for managing updates, configuration migrations from XML to JSON, and build instructions for C# using Visual Studio.

Tokens
1.5K
Snippets
4
Records
11
Agent score
34%

What's inside PingCastle

  2. Automate updates with Windows Task Scheduler

    master

    To automate updates, create a Basic Task in Windows Task Scheduler:

    1. Trigger: Set your preferred frequency (e.g., weekly).
    2. Action: Start PingCastleAutoUpdater.exe.
    3. Start in: Ensure the action runs within the PingCastle directory.
    4. Arguments (Optional): Add flags like --wait-for-days 7 to ensure stability.

  3. Install PingCastle Auto Updater

    master

    To install the updater, place PingCastleAutoUpdater.exe in the same directory as your pingcastle.exe. The tool is self-contained and includes the .NET 8.0 runtime, so no additional software installation is required. It is compatible with Windows x64 only.

    Place `PingCastleAutoUpdater.exe` in the same directory as `pingcastle.exe`.

  4. Use PingCastle interactive mode

    master

    PingCastle provides an interactive menu for performing various Active Directory and Entra ID security assessments. When running the application, you can select from the following core functionalities:

    • 1-healthcheck: Score the risk of a domain.
    • 2-entraid: Score the risk of Entra ID.
    • 3-conso: Aggregate multiple reports into a single one.
    • 4-carto: Build a map of all interconnected domains.
    • 5-scanner: Perform specific security checks on workstations.
    • 6-export: Export users or computers.
    • 7-advanced: Open the advanced menu.
    • 0-Exit: Exit the application.

    You can also use command line switches such as --help for additional options.

  5. Migrate PingCastle 3.4 to 3.5 configurations

    master

    When running the auto-updater for the first time with both XML (PingCastle.exe.config) and JSON (appsettings.console.json) configurations, the tool performs an initial state migration:

    1. Converts XML settings to JSON format.
    2. Merges XML settings into the existing JSON (XML values take precedence).
    3. Archives the legacy XML file as PingCastle.exe.config.bak.
    4. Proceeds with the update.

  6. Preview updates with --dry-run

    master

    Use the --dry-run flag to simulate an update without modifying any files. This allows you to verify which files would be replaced and check if configuration migrations (XML to JSON) would succeed. A detailed conversion report is generated for review, but no changes are applied to the system.

    PingCastleAutoUpdater.exe --dry-run

  8. Troubleshoot PingCastle Auto Updater issues

    master

    No current version detected

    If you see No current version detected - download will proceed, it means pingcastle.exe was not found in the same directory. The tool will proceed with a fresh download.

    Initial State Migration Failed

    If XML to JSON migration fails, the tool restores the original JSON configuration from a temporary backup and saves an error report. Steps to resolve:

    1. Check the error report.
    2. Run with --dry-run to preview the migration.

    Configuration Merge Failed

    If merging fails during the update, your previous configuration is preserved as a .bak file. You may need to manually review and merge settings.

    Network Issues

    If GitHub is unreachable, check your connectivity or use the --api-url <url> switch to point to an internal API.

  9. Reference: PingCastleAutoUpdater CLI switches

    master

    The following command-line arguments are available for PingCastleAutoUpdater.exe:

    • --help: Display the help message with all available options.
    • --dry-run: Preview all changes that would be made without modifying any files.
    • --use-preview: Include preview/prerelease versions when checking for updates (default is stable only).
    • --force-download: Download and install the latest release even if the current version is already up to date.
    • --wait-for-days <n>: Only use releases that have been published for at least n days to ensure stability.
    • --api-url <url>: Use a custom API URL (must be HTTP or HTTPS) instead of GitHub. This is useful for systems that cannot connect to GitHub and need to use PingCastle Pro or Enterprise internal updates.
    # Examples
PingCastleAutoUpdater.exe --help
PingCastleAutoUpdater.exe --use-preview
PingCastleAutoUpdater.exe --force-download
PingCastleAutoUpdater.exe --wait-for-days 30
PingCastleAutoUpdater.exe --api-url https://pingcastle.your.server/api/release

  10. Review Migration and Conversion reports

    master

    The tool generates audit reports in the PingCastle directory to track configuration changes:

    • InitialStateMigration_*.txt: Details of the pre-update XML-to-JSON migration (sections converted, settings merged, and precedence rules applied).
    • ConversionReport_*.txt: Details of post-update XML to JSON configuration conversion and merging during the update process.

  11. Understand PingCastle licensing options

    master

    PingCastle is available under two distinct licensing models:

    Open Source Edition

    Licensed under the Non-Profit Open Software License ("Non-Profit OSL") 3.0.

    • Permitted Use: Organizations (including for-profit companies) may use PingCastle internally without a purchased license. This includes usage by internal IT staff or contracted IT service providers.
    • Restrictions: You cannot monetize PingCastle or offer it as a paid service to others.

    Commercial License

    • Required Use: Necessary for anyone intending to incorporate PingCastle into commercial services or products, or for those planning to generate revenue by providing PingCastle-based services to other organizations.