Adding upstream version 1:1.1.2.upstream/1%1.1.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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:
+
+![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..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.
+
+![check host perf data](res/check-host-perf-data.png)
+
+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.
+
+![new host template](res/new-host-template.png)
+
+This host template also requires three data fields which are shown below.
+
+![host template fields](res/host-template-fields.png)
+
+A service template is also needed. We chose the name `x509-host-check` and
+`icingacli-x509` as check command.
+
+![new service template](res/new-service-template.png)
+
+The service template now requires all data fields which correspond to the
+check command's parameters.
+
+![service template fields](res/service-template-fields.png)
+
+#### Import Source Setup
+
+Create a new import source of type `Hosts (X509)`.  
+![hosts import source](res/hosts-import-source.png)
+
+Configure a property modifier for column `host_ports` of type `Split` and use
+the comma `,` as delimiter.  
+![ports property modifier](res/ports-property-modifier.png)
+
+The preview should now produce a similar result to this:  
+![hosts import result](res/hosts-import-result.png)
+
+#### 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)
+
+![sync rule properties](res/sync-rule-properties.png)
+
+#### 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.
+
+![host check single service](res/host-check-single-service.png)
+
+Once you've triggered the import and synchronisation as well as deployed
+the resulting changes you should see this in Icinga Web 2:
+
+![single service result](res/single-service-result.png)
+
+##### 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:
+
+![host check multiple services](res/host-check-multiple-services.png)
+
+After deploying the resulting changes you should see this in Icinga Web 2:
+
+![multiple services result](res/multiple-services-result.png)
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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new 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
new file mode 100644
index 0000000..a4c81b6
--- /dev/null
+++ b/doc/res/x509-usage.png