diff options
Diffstat (limited to 'doc')
21 files changed, 410 insertions, 0 deletions
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: + + + + + +At a glance you see which CAs have issued your certificates and key counters of your environment: + + + +## 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..ab06e5d --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,43 @@ +# <a id="Installation"></a>Installation + +## Requirements + +* PHP (>= 7.0) +* Icinga Web 2 (>= 2.9) +* Icinga Web 2 libraries: + * [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.8.1) + * [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10) +* php-gmp +* OpenSSL +* MySQL or MariaDB + +## Database Setup + +The module needs a MySQL/MariaDB database with the schema that's provided in the `etc/schema/mysql.schema.sql` file. + +You may use the following example command for creating the MySQL/MariaDB database. Please change the password: + +``` +CREATE DATABASE x509; +GRANT SELECT, INSERT, UPDATE, DELETE, DROP, 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 < etc/schema/mysql.schema.sql +``` + +## Installation + +1. Install it [like any other module](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation). +Use `x509` as name. + +2. Once you've set up the database, create a new Icinga Web 2 resource for it using the +`Configuration -> Application -> Resources` menu. + +3. The next step involves telling the module which database resource to use. This can be done in +`Configuration -> Modules -> x509 -> Backend`. + +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/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..a70bf0b --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,104 @@ +# <a id="Configuration"></a>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 +``` + +## Scan Jobs + +The module needs to know which IP address ranges and ports to scan. These can be configured in +`Configuration -> Modules -> x509 -> 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` + +Scan jobs can be executed using the `icingacli x509 scan` CLI command. The `--job` option is used to specify the scan +job which should be run: + +``` +icingacli x509 scan --job lan +``` + +## Scheduling Jobs + +Each job may specify a `cron` compatible `schedule` to run periodically at the given interval. The `cron` format is as +follows: + +``` +* * * * * +- - - - - +| | | | | +| | | | | +| | | | +----- day of week (0 - 6) (Sunday to Saturday) +| | | +---------- month (1 - 12) +| | +--------------- day of month (1 - 31) +| +-------------------- hour (0 - 23) ++------------------------- minute (0 - 59) +``` + +Example definitions: + +Description | Definition +------------------------------------------------------------| ---------- +Run once a year at midnight of 1 January | 0 0 1 1 * +Run once a month at midnight of the first day of the month | 0 0 1 * * +Run once a week at midnight on Sunday morning | 0 0 * * 0 +Run once a day at midnight | 0 0 * * * +Run once an hour at the beginning of the hour | 0 * * * * + +Jobs are executed on CLI with the `jobs` command: + +``` +icingacli x509 jobs run +``` + +This command runs all jobs which are currently due and schedules the next execution of all jobs. + +You may configure this command as `systemd` service. Just copy the example service definition from +`config/systemd/icinga-x509.service` to `/etc/systemd/system/icinga-x509.service` and enable it afterwards: + +``` +systemctl enable icinga-x509.service +``` + +As an alternative if you want scan jobs to be run periodically, you can use the `cron(8)` daemon to run them on a +schedule: + +``` +vi /etc/crontab +[...] + +# Runs job 'lan' daily at 2:30 AM +30 2 * * * www-data icingacli x509 scan --job lan +``` + +## 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. diff --git a/doc/10-Monitoring.md b/doc/10-Monitoring.md new file mode 100644 index 0000000..7ef3abd --- /dev/null +++ b/doc/10-Monitoring.md @@ -0,0 +1,212 @@ +# <a id="Monitoring"></a>Monitoring + +## Host Check Command + +The module provides a CLI command to check a host's certificate. It does so by +fetching all the necessary information from this module's own database. + +### Usage + +General: `icingacli x509 check host [options]` + +Options: + +``` +--ip A hosts IP address +--host A hosts name +--port The port to check in particular +--warning Less remaining time results in state WARNING [25%] +--critical Less remaining time results in state CRITICAL [10%] +--allow-self-signed Ignore if a certificate or its issuer has been self-signed +``` + +### Threshold Definition + +Thresholds can either be defined relative (in percent) or absolute (time interval). +Time intervals consist of a digit and an accompanying unit (e.g. "3M" are three +months). Supported units are: + + Identifier | Description +------------|------------ +y, Y | Year +M | Month +d, D | Day +h, H | Hour +m | Minute +s, S | Second + +**Example:** + +``` +$ icingacli x509 check host --host example.org --warning 1y +WARNING - *.example.org expires in 219 days|'*.example.org'=18985010s;25574400;10281600;0;102470399 +``` + +### Performance Data + +The command outputs a performance data value for each certificate that is +served by the host. The value measured is the amount of seconds remaining +until the certificate expires. + + + +The value of `max` is the total amount of seconds the certificate is valid. +`warning` and `critical` are the seconds remaining after which the respective +state is reported. + +## Icinga 2 Integration + +First off, this chapter relies on the fact that you're using the Director +already and that you're familiar with some of the terms and functionalities +used there. + +If you don't want to use the Director, know that Icinga 2 already provides +an appropriate template for the host check command in its template library: +https://icinga.com/docs/icinga2/latest/doc/10-icinga-template-library/#x509 + +### Director Import Sources + +The module provides two different import sources: + +#### Hosts (X509) + +Focuses on the hosts the module found when scanning the networks. Use this +for the most straightforward way of integrating the results into your +environment. It's also the utilized source in the example further below. + +Columns provided by this source: + +Name | Description +----------------|-------------------------------------------------------------- +host_name_or_ip | Default key column. This is primarily `host_name`, though if this is not unique it falls back to `host_ip` for individual results +host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6 +host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process +host_ports | Separated by comma. All ports where certificates were found +host_address | Set to `host_ip` if it is IPv4 else `null` +host_address6 | Set to `host_ip` if it is IPv6 else `null` + +#### Services (X509) + +While the hosts import source does not provide any details about the found +certificates this one does. This also means that this source may generate +multiple results for a single host since it focuses on the found certificates. + +Use this source if you want to import service objects directly and relate them +to already existing hosts by their utilized certificates. The Director's many +utilities provided in this regard will again come in handy here. + +Columns provided by this source: + +Name | Description +----------------------|-------------------------------------------------------- +host_name_ip_and_port | Default key column. This is a combination of `host_name`, `host_ip` and `host_port` in the format `name/ip:port` +host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6 +host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process +host_port | A host's port where a certificate has been found +host_address | Set to `host_ip` if it is IPv4 else `null` +host_address6 | Set to `host_ip` if it is IPv6 else `null` +cert_subject | A certificate's common name +cert_issuer | The issuer's common name +cert_self_signed | Whether the certificate is self-signed (`yes` or `no`) +cert_trusted | Whether the certificate is trusted (`yes` or `no`) +cert_valid_from | The certificate's start time of validity (UNIX timestamp) +cert_valid_to | The certificate's end time of validity (UNIX timestamp) +cert_fingerprint | The certificate's fingerprint (hex-encoded) +cert_dn | The certificate's distinguished name +cert_subject_alt_name | The certificate's alternative subject names (Comma separated pairs of `type:name`) + +### Service Checks With the Hosts Import Source + +This example covers the setup of service checks by using a particular host +template and suggests then two options utilizing service apply rules. + +#### Preparations + +Assuming the check command definition `icingacli-x509` has already been imported +you need to define a few data fields now: + +Field name | Data type +---------------------------------|---------- +certified_ports | Array +icingacli_x509_ip | String +icingacli_x509_host | String +icingacli_x509_port | String +icingacli_x509_warning | String +icingacli_x509_critical | String +icingacli_x509_allow_self_signed | Boolean + +Then please create a new host template with a name of your choosing. We've chosen +`x509-host`. We're also importing our base template `base-host` here which defines +all the default properties of our hosts. + + + +This host template also requires three data fields which are shown below. + + + +A service template is also needed. We chose the name `x509-host-check` and +`icingacli-x509` as check command. + + + +The service template now requires all data fields which correspond to the +check command's parameters. + + + +#### Import Source Setup + +Create a new import source of type `Hosts (X509)`. + + +Configure a property modifier for column `host_ports` of type `Split` and use +the comma `,` as delimiter. + + +The preview should now produce a similar result to this: + + +#### Sync Rule Setup + +Create a new sync rule for objects of type `Host`. Depending on your environment +you may choose either `Merge` or `Replace` as update policy. Choose `Merge` to +continue with this example. + +Which properties this rule defines is also very dependent on what you want to +achieve. We now assume that you already have host objects whose object names +match exactly those the import source provides. (Hence you should choose +`Merge` as update policy) + + + +#### Service Check Setup + +There are two choices now. The first checks a host's certificates as a single +service. The second creates for each individual certificate (port) a service. + +##### Single Service + +This is done by defining a new service as part of the host template created +earlier. There add a service and choose the service template also created +previously. + + + +Once you've triggered the import and synchronisation as well as deployed +the resulting changes you should see this in Icinga Web 2: + + + +##### Multiple Services + +This utilizes a service apply rule. Trigger the import and synchronisation +first, otherwise you can't choose a custom variable for the *apply for* rule. + +Once the synchronisation is finished, set up the service apply rule like this: + + + +After deploying the resulting changes you should see this in Icinga Web 2: + + diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md new file mode 100644 index 0000000..85c5fa8 --- /dev/null +++ b/doc/80-Upgrading.md @@ -0,0 +1,29 @@ +# Upgrading Icinga Certificate Monitoring + +Upgrading Icinga Certificate Monitoring is straightforward. +Usually the only manual steps involved are schema updates for the database. + +## Upgrading to version 1.1.0 + +Icinga Certificate Monitoring version 1.1.0 fixes issues that affect the database schema. +To have these issues really fixed in your environment, the schema must be upgraded. +Please find the upgrade script in **etc/schema/mysql-upgrade**. + +You may use the following command to apply the database schema upgrade file: + +``` +# mysql -u root -p x509 < etc/schema/mysql-upgrade/v1.1.0.sql +``` + +## Upgrading to version 1.0.0 + +Icinga Certificate Monitoring version 1.0.0 requires a schema update for the database. +The schema has been adjusted so that it is no longer necessary to adjust server settings +if you're using a version of MySQL < 5.7 or MariaDB < 10.2. +Please find the upgrade script in **etc/schema/mysql-upgrade**. + +You may use the following command to apply the database schema upgrade file: + +``` +# mysql -u root -p x509 < etc/schema/mysql-upgrade/v1.0.0.sql +``` diff --git a/doc/res/check-host-perf-data.png b/doc/res/check-host-perf-data.png Binary files differnew file mode 100644 index 0000000..958a226 --- /dev/null +++ b/doc/res/check-host-perf-data.png diff --git a/doc/res/host-check-multiple-services.png b/doc/res/host-check-multiple-services.png Binary files differnew file mode 100644 index 0000000..a153e2e --- /dev/null +++ b/doc/res/host-check-multiple-services.png diff --git a/doc/res/host-check-single-service.png b/doc/res/host-check-single-service.png Binary files differnew file mode 100644 index 0000000..1f4bdec --- /dev/null +++ b/doc/res/host-check-single-service.png diff --git a/doc/res/host-template-fields.png b/doc/res/host-template-fields.png Binary files differnew file mode 100644 index 0000000..a6aa438 --- /dev/null +++ b/doc/res/host-template-fields.png diff --git a/doc/res/hosts-import-result.png b/doc/res/hosts-import-result.png Binary files differnew file mode 100644 index 0000000..c19b1f2 --- /dev/null +++ b/doc/res/hosts-import-result.png diff --git a/doc/res/hosts-import-source.png b/doc/res/hosts-import-source.png Binary files differnew file mode 100644 index 0000000..fe525c7 --- /dev/null +++ b/doc/res/hosts-import-source.png diff --git a/doc/res/multiple-services-result.png b/doc/res/multiple-services-result.png Binary files differnew file mode 100644 index 0000000..8bec4b9 --- /dev/null +++ b/doc/res/multiple-services-result.png diff --git a/doc/res/new-host-template.png b/doc/res/new-host-template.png Binary files differnew file mode 100644 index 0000000..2ff9074 --- /dev/null +++ b/doc/res/new-host-template.png diff --git a/doc/res/new-service-template.png b/doc/res/new-service-template.png Binary files differnew file mode 100644 index 0000000..fec3d22 --- /dev/null +++ b/doc/res/new-service-template.png diff --git a/doc/res/ports-property-modifier.png b/doc/res/ports-property-modifier.png Binary files differnew file mode 100644 index 0000000..7bb3ecc --- /dev/null +++ b/doc/res/ports-property-modifier.png diff --git a/doc/res/service-template-fields.png b/doc/res/service-template-fields.png Binary files differnew file mode 100644 index 0000000..17c1cbd --- /dev/null +++ b/doc/res/service-template-fields.png diff --git a/doc/res/single-service-result.png b/doc/res/single-service-result.png Binary files differnew file mode 100644 index 0000000..418f495 --- /dev/null +++ b/doc/res/single-service-result.png diff --git a/doc/res/sync-rule-properties.png b/doc/res/sync-rule-properties.png Binary files differnew file mode 100644 index 0000000..1b54553 --- /dev/null +++ b/doc/res/sync-rule-properties.png diff --git a/doc/res/x509-certificates.png b/doc/res/x509-certificates.png Binary files differnew file mode 100644 index 0000000..c89e6fb --- /dev/null +++ b/doc/res/x509-certificates.png diff --git a/doc/res/x509-dashboard.png b/doc/res/x509-dashboard.png Binary files differnew file mode 100644 index 0000000..c4a2f5c --- /dev/null +++ b/doc/res/x509-dashboard.png diff --git a/doc/res/x509-usage.png b/doc/res/x509-usage.png Binary files differnew file mode 100644 index 0000000..a4c81b6 --- /dev/null +++ b/doc/res/x509-usage.png |
