From 067008c5f094ba9606daacbe540f6b929dc124ea Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 14 Apr 2024 15:31:28 +0200 Subject: Adding upstream version 1:1.3.2. Signed-off-by: Daniel Baumann --- doc/01-About.md | 22 ++++ doc/02-Installation.md | 73 +++++++++++ doc/02-Installation.md.d/From-Source.md | 16 +++ doc/03-Configuration.md | 77 +++++++++++ doc/04-Scanning.md | 85 +++++++++++++ doc/10-Monitoring.md | 212 +++++++++++++++++++++++++++++++ doc/11-Housekeeping.md | 38 ++++++ doc/80-Upgrading.md | 91 +++++++++++++ doc/res/check-host-perf-data.png | Bin 0 -> 7466 bytes doc/res/host-check-multiple-services.png | Bin 0 -> 49022 bytes doc/res/host-check-single-service.png | Bin 0 -> 32771 bytes doc/res/host-template-fields.png | Bin 0 -> 15012 bytes doc/res/hosts-import-result.png | Bin 0 -> 7182 bytes doc/res/hosts-import-source.png | Bin 0 -> 8344 bytes doc/res/multiple-services-result.png | Bin 0 -> 13992 bytes doc/res/new-host-template.png | Bin 0 -> 11630 bytes doc/res/new-service-template.png | Bin 0 -> 14294 bytes doc/res/ports-property-modifier.png | Bin 0 -> 12071 bytes doc/res/service-template-fields.png | Bin 0 -> 27772 bytes doc/res/single-service-result.png | Bin 0 -> 82322 bytes doc/res/sync-rule-properties.png | Bin 0 -> 19091 bytes doc/res/weekly-schedules.png | Bin 0 -> 140091 bytes doc/res/x509-certificates.png | Bin 0 -> 475307 bytes doc/res/x509-dashboard.png | Bin 0 -> 208525 bytes doc/res/x509-usage.png | Bin 0 -> 286297 bytes 25 files changed, 614 insertions(+) create mode 100644 doc/01-About.md create mode 100644 doc/02-Installation.md create mode 100644 doc/02-Installation.md.d/From-Source.md create mode 100644 doc/03-Configuration.md create mode 100644 doc/04-Scanning.md create mode 100644 doc/10-Monitoring.md create mode 100644 doc/11-Housekeeping.md create mode 100644 doc/80-Upgrading.md create mode 100644 doc/res/check-host-perf-data.png create mode 100644 doc/res/host-check-multiple-services.png create mode 100644 doc/res/host-check-single-service.png create mode 100644 doc/res/host-template-fields.png create mode 100644 doc/res/hosts-import-result.png create mode 100644 doc/res/hosts-import-source.png create mode 100644 doc/res/multiple-services-result.png create mode 100644 doc/res/new-host-template.png create mode 100644 doc/res/new-service-template.png create mode 100644 doc/res/ports-property-modifier.png create mode 100644 doc/res/service-template-fields.png create mode 100644 doc/res/single-service-result.png create mode 100644 doc/res/sync-rule-properties.png create mode 100644 doc/res/weekly-schedules.png create mode 100644 doc/res/x509-certificates.png create mode 100644 doc/res/x509-dashboard.png create mode 100644 doc/res/x509-usage.png (limited to 'doc') diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 0000000..38fa06a --- /dev/null +++ b/doc/01-About.md @@ -0,0 +1,22 @@ +# Icinga Certificate Monitoring + +The certificate monitoring module for Icinga keeps track of certificates as they are deployed in a network environment. +It does this by scanning networks for TLS services and collects whatever certificates it finds along the way. +The certificates are verified using its own trust store. + +The module’s web frontend can be used to view scan results, allowing you to drill down into detailed information +about any discovered certificate of your landscape: + +![X.509 Usage](res/x509-usage.png "X.509 Usage") + +![X.509 Certificates](res/x509-certificates.png "X.509 Certificates") + +At a glance you see which CAs have issued your certificates and key counters of your environment: + +![X.509 Dashboard](res/x509-dashboard.png "X.509 Dashboard") + +## Documentation + +* [Installation](02-Installation.md) +* [Configuration](03-Configuration.md) +* [Monitoring](10-Monitoring.md) diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..af2eaf3 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,73 @@ + +# Installing Icinga Certificate Monitoring + +The recommended way to install Icinga Certificate Monitoring +and its dependencies is to use prebuilt packages for +all supported platforms from our official release repository. +Please note that [Icinga Web](https://icinga.com/docs/icinga-web) is required +and if it is not already set up, it is best to do this first. + +The following steps will guide you through installing and setting up Icinga Certificate Monitoring. + + + +## Installing the Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icinga-x509` package +or install [from source](02-Installation.md.d/From-Source.md). + + +## Setting up the Database + +### Setting up a MySQL or MariaDB Database + +The module needs a MySQL/MariaDB database with the schema that's provided in the `/usr/share/icingaweb2/modules/x509/schema/mysql.schema.sql` file. + + +**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path. + + + +You can use the following sample command for creating the MySQL/MariaDB database. Please change the password: + +``` +CREATE DATABASE x509; +GRANT CREATE, SELECT, INSERT, UPDATE, DELETE, DROP, ALTER, CREATE VIEW, INDEX, EXECUTE ON x509.* TO x509@localhost IDENTIFIED BY 'secret'; +``` + +After, you can import the schema using the following command: + +``` +mysql -p -u root x509 < /usr/share/icingaweb2/modules/x509/schema/mysql.schema.sql +``` + +### Setting up a PostgreSQL Database + +The module needs a PostgreSQL database with the schema that's provided in the `/usr/share/icingaweb2/modules/x509/schema/pgsql.schema.sql` file. + + +**Note:** If you haven't installed this module from packages, then please adapt the schema path to the correct installation path. + + + +You can use the following sample command for creating the PostgreSQL database. Please change the password: + +```sql +CREATE USER x509 WITH PASSWORD 'secret'; +CREATE DATABASE x509 + WITH OWNER x509 + ENCODING 'UTF8' + LC_COLLATE = 'en_US.UTF-8' + LC_CTYPE = 'en_US.UTF-8'; +``` + +After, you can import the schema using the following command: + +``` +psql -U x509 x509 -a -f /usr/share/icingaweb2/modules/x509/schema/pgsql.schema.sql +``` + +This concludes the installation. You should now be able to import CA certificates and set up scan jobs. +Please read the [Configuration](03-Configuration.md) section for details. + diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 0000000..31f3d2b --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,16 @@ +# Installing Icinga Certificate Monitoring from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `x509` as the module name. The following requirements must also be met. + +## Requirements + +* PHP (≥7.2) +* MySQL or PostgreSQL PDO PHP libraries +* The following PHP modules must be installed: `gmp`, `pcntl`, `openssl` +* [Icinga Web](https://github.com/Icinga/icingaweb2) (≥2.9) +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.13.0) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.12.0) + + diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..4ecde77 --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,77 @@ +# Configuration + +## Importing CA certificates + +The module tries to verify certificates using its own trust store. By default, this trust store is empty, and it +is up to the Icinga Web 2 admin to import CA certificates into it. + +Using the `icingacli x509 import` command CA certificates can be imported. The certificate chain file that is specified +with the `--file` option should contain a PEM-encoded list of X.509 certificates which should be added to the trust +store: + +``` +icingacli x509 import --file /etc/ssl/certs/ca-certificates.crt +``` + +## Configure Jobs + +Scan jobs have a name which uniquely identifies them, e.g. `lan`. These names are used by the CLI command to start +scanning for specific jobs. + +Each scan job can have one or more IP address ranges and one or more port ranges. The module scans each port in +a job's port ranges for all the individual IP addresses in the IP ranges. IP address ranges have to be specified using +the CIDR format. Multiple IP address ranges can be separated with commas, e.g.: + +`192.0.2.0/24,10.0.10.0/24` + +Port ranges are separated with dashes (`-`). If you only want to scan a single port you don't need to specify the second +port: + +`443,5665-5669` + +Additionally, each job may also exclude specific **hosts** and **IP** addresses from scan. These hosts won't be scanned +when you run the [scan](04-Scanning.md#scan-command) or [jobs](04-Scanning.md#scheduling-jobs) command. Excluding an entire network and specifying IP addresses in CIDR +format will not work. You must specify concrete **IP**s and **host CN**s separated with commas, e.g: + +`192.0.2.2,192.0.2.5,icinga.com` + +### Job Schedules + +Schedules are [`cron`](https://crontab.guru) and rule based configs used to run jobs periodically at the given interval. +Every job is allowed to have multiple schedules that can be run independently of each other. Each job schedule provides +different options that you can use to control the scheduling behavior of the [jobs command](04-Scanning.md#scheduling-jobs). + +#### Examples + +A schedule that runs weekly on **Friday** and scans all targets that have not yet been scanned, or +whose last scan is older than `1 week`. + +![Weekly Schedules](res/weekly-schedules.png "Weekly Schedules") + +## Server Name Indication + +In case you are serving multiple virtual hosts under a single IP you can configure those in +`Configuration -> Modules -> x509 -> SNI`. + +Each entry defines an IP with multiple hostnames associated with it. These are then utilized when jobs run. + +Modules may also provide sources for SNI. At this time the module monitoring is the only one with known support. + +## Icinga Certificate Monitoring Daemon + +The default `systemd` service of this module, shipped with package installations, uses the [jobs command](04-Scanning.md#scheduling-jobs) +and runs all your configured jobs and schedules. + + + +> **Note** +> +> If you haven't installed this module from packages, you have to configure this as a `systemd` service yourself by just +> copying the example service definition from `/usr/share/icingaweb2/modules/x509/config/systemd/icinga-x509.service` +> to `/etc/systemd/system/icinga-x509.service`. + + +You can run the following command to enable and start the daemon. +``` +systemctl enable --now icinga-x509.service +``` diff --git a/doc/04-Scanning.md b/doc/04-Scanning.md new file mode 100644 index 0000000..608d18a --- /dev/null +++ b/doc/04-Scanning.md @@ -0,0 +1,85 @@ +# Scanning + +The Icinga Certificate Monitoring provides CLI commands to scan **hosts** and **IPs** in various ways. +These commands are listed below and can be used individually. It is necessary for all commands to know which IP address +ranges and ports to scan. These can be configured as described [here](03-Configuration.md#configure-jobs). + +## Scan Command + +The scan command, scans targets to find their X.509 certificates and track changes to them. +A **target** is an **IP-port** combination that is generated from the job configuration, taking into account configured +[**SNI**](03-Configuration.md#server-name-indication) maps, so that targets with multiple certificates are also properly +scanned. + +By default, successive calls to the scan command perform partial scans, checking both targets not yet scanned and +targets whose scan is older than 24 hours, to ensure that all targets are rescanned over time and new certificates +are collected. This behavior can be customized through the command [options](#usage-1). + +> **Note** +> +> When rescanning due targets, they will be rescanned regardless of whether the target previously provided a certificate +> or not, to collect new certificates, track changed certificates, and remove decommissioned certificates. + +### Usage + +This scan command can be used like any other Icinga Web cli operations like this: `icingacli x509 scan [OPTIONS]` + +**Options:** + +``` +--job= Scan targets that belong to the specified job. (Required) +--since-last-scan=