User Guide

Full documentation for installation, configuration, reporting, and alerts.

This is the latest version of the CRL Monitor User Guide, rendered directly from the official markdown source.

CrlMonitor User Guide

Quick Start

  1. Extract the release ZIP to C:\CrlMonitor\
  2. Run CrlMonitor.exe once to accept the EULA (or use --accept-eula for automated deployments)
  3. Edit config.json:
  4. Add your CRL URIs to the uris section
  5. Set html_report_path and csv_output_path to desired locations
  6. Run: CrlMonitor.exe config.json
  7. Verify the generated HTML/CSV reports at the configured paths

You now have a working CRL monitoring tool.

Note for automated deployments: Use CrlMonitor.exe --accept-eula config.json to bypass interactive EULA acceptance.

By running CrlMonitor with the --accept-eula flag, you indicate your acceptance of the End User License Agreement found in EULA.txt. If you do not agree to these terms, do not use this flag.

The EULA text is available in EULA.txt (included in the release ZIP) and at https://redkestrel.co.uk/products/crlmonitor/EULA

Next Steps (Optional)

1. Introduction

CrlMonitor checks Certificate Revocation Lists (CRLs), validates signatures, monitors expiry windows, and produces HTML/CSV reports and optional email alerts. It is designed to run unattended and is typically scheduled via Windows Task Scheduler.

2. Installation

Extract the release ZIP to a folder such as C:\CrlMonitor\. Ensure the account used to run the scheduled task (often LocalSystem) has read/write access to the folder and to any report/output locations.

3. Configuration File

The application reads a JSON configuration file defining CRLs, email settings, report preferences, logging, and license behaviour. The main sections include:

Environment Variables (Windows only): Path strings support environment variable expansion using %VARIABLE% syntax (e.g., %ProgramData%/RedKestrel/CrlMonitor/report.csv). Common variables include %ProgramData%, %TEMP%, %USERPROFILE%, and %APPDATA%.

Configuration Fields

Top-Level Settings

Logging Section

"logging": {
  "min_level": "Information",
  "log_file_path": "CrlMonitor.log",
  "rolling_interval": "Day",
  "retained_file_count_limit": 7
}

SMTP Section

"smtp": {
  "host": "smtp.example.com",
  "port": 587,
  "username": "[email protected]",
  "password": "",
  "from": "CRL Monitor <[email protected]>",
  "enable_starttls": true
}

Reports Section

"reports": {
  "enabled": false,
  "report_frequency_hours": 24,
  "recipients": ["[email protected]"],
  "subject": "CRL Health Report",
  "include_summary": true,
  "include_full_csv": true
}

Alerts Section

"alerts": {
  "enabled": false,
  "recipients": ["[email protected]"],
  "statuses": ["ERROR", "EXPIRED", "EXPIRING"],
  "cooldown_hours": 24,
  "subject_prefix": "[CRL Alert]",
  "include_details": true
}

URIs Section

"uris": [
  {
    "uri": "http://crl.example.com/example.crl",
    "signature_validation_mode": "ca-cert",
    "ca_certificate_path": "certs/ca.crt",
    "expiry_threshold": 0.8,
    "max_crl_size_bytes": 5242880,
    "ldap": {
      "username": "CN=Reader,DC=example,DC=com",
      "password": "secret"
    }
  }
]

4. Running CrlMonitor Manually

Run from PowerShell or CMD:

CrlMonitor.exe config.json

Or using full path:

CrlMonitor.exe C:\CrlMonitor\config.json

Configuration File Location: Keep config.json with CrlMonitor.exe (e.g., C:\CrlMonitor\config.json). If no argument supplied, app looks in exe directory. Output files (logs, reports, state) default to %ProgramData%/RedKestrel/CrlMonitor/ following Windows conventions for application data.

Exit Codes

5. Running via Scheduled Task (Recommended)

Most deployments run CrlMonitor automatically.

Creating the Scheduled Task

  1. Open Task Scheduler.
  2. Choose Create Task….
  3. Set Run as to LocalSystem or a suitable service account.
  4. Add an Action calling: C:\CrlMonitor\CrlMonitor.exe C:\CrlMonitor\config.json

  5. Add a Trigger:

  6. Daily (every 24 hours), or

  7. Every 4 hours for faster alerting

Notes

6. Reports

CrlMonitor generates two optional report types.

HTML Report

A detailed dashboard including summary counts and a full table of CRLs with status, issuer, timestamps, signature verification, size, download time, revocation count, and previous check time.

Configured by:

CSV Report

A machine-readable CSV listing all CRL rows with columns: URI, Status, Fetch Time, Error, Issuer, This Update, Next Update, Signature Valid, Download Time, Size Bytes, Revocations, Previous Fetch.

Configured by:

7. Alerts

Alerts are sent when a CRL enters a monitored state such as ERROR, EXPIRED, or EXPIRING.

Key fields:

Cooldown prevents repeated notifications if the CRL remains in the same state. State is tracked in the file specified by state_file_path.

8. Logging

Logging uses Serilog with rolling daily files. Main settings:

Log File Location

Log files include timestamps, log level, message, and exception details.

9. Licensing

CrlMonitor supports both trial and standard licenses.

License File Location

Store the license.lic file in a location accessible to the user or service account:

The application searches for license.lic in: 1. Application directory 2. User's home directory 3. Common application data folder

Trial Period

Trial licenses show remaining days in console output and logs. After 30 days from first use, the application will stop running until a standard license is installed.

10. Troubleshooting

Config file not found

Check the full path in the Task Scheduler Action. Ensure you're passing the config file path as the first argument.

No HTML or CSV output

Confirm reporting is enabled in the config and that the scheduled-task user has write permissions to the output directories. Check logs for errors.

SMTP not working

LDAP CRLs failing

CRL signature invalid

EULA not accepted

Run the application manually once to accept the EULA. The acceptance is stored in %ProgramData%\RedKestrel\CrlMonitor and persists for scheduled runs.

Reading the EULA: The EULA text is available in EULA.txt (included in the release ZIP) and online at https://redkestrel.co.uk/products/crlmonitor/EULA

For automated deployments (IaC/Ansible/SCCM): Use the --accept-eula flag to bypass interactive acceptance:

CrlMonitor.exe --accept-eula config.json

By running CrlMonitor with the --accept-eula flag, you indicate your acceptance of the End User License Agreement found in EULA.txt. If you do not agree to these terms, do not use this flag.

This is particularly useful for Infrastructure as Code deployments and automated configuration management.

License validation failing

Proxy authentication failing

11. Example Configuration

{
  "logging": {
    "min_level": "Information",
    "log_file_path": "CrlMonitor.log",
    "rolling_interval": "Day",
    "retained_file_count_limit": 7
  },
  "console_reports": true,
  "console_verbose": false,
  "csv_reports": true,
  "csv_output_path": "%ProgramData%/RedKestrel/CrlMonitor/crl-report.csv",
  "csv_append_timestamp": false,
  "html_report_enabled": true,
  "html_report_path": "%ProgramData%/RedKestrel/CrlMonitor/crl-report.html",
  "html_report_url": "https://monitoring.example.com/crl-report.html",
  "fetch_timeout_seconds": 30,
  "max_parallel_fetches": 6,
  "max_crl_size_bytes": 10485760,
  "use_system_proxy": true,
  "state_file_path": "%ProgramData%/RedKestrel/CrlMonitor/state.json",
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "[email protected]",
    "password": "",
    "from": "CRL Monitor <[email protected]>",
    "enable_starttls": true
  },
  "reports": {
    "enabled": true,
    "report_frequency_hours": 24,
    "recipients": ["[email protected]"],
    "subject": "Daily CRL Health Report",
    "include_summary": true,
    "include_full_csv": true
  },
  "alerts": {
    "enabled": true,
    "recipients": ["[email protected]"],
    "statuses": ["ERROR", "EXPIRED"],
    "cooldown_hours": 24,
    "subject_prefix": "[CRL Alert]",
    "include_details": true
  },
  "uris": [
    {
      "uri": "http://crl3.digicert.com/DigiCertGlobalRootCA.crl",
      "signature_validation_mode": "ca-cert",
      "ca_certificate_path": "examples/CA-certs/DigiCertGlobalRootCA.crt",
      "expiry_threshold": 0.8
    },
    {
      "uri": "http://crl.globalsign.com/gsrsaovsslca2018.crl",
      "signature_validation_mode": "ca-cert",
      "ca_certificate_path": "examples/CA-certs/GlobalSignRSAOVSSLCA2018.pem",
      "expiry_threshold": 0.8
    }
  ]
}

Support

For support, feature requests, or licensing enquiries: * Email: [email protected] * Sales: [email protected]