Text updates: ssl/ssl-certfile-monitoring

integrations/ssl/ssl-certfile-monitoring/CHANGELOG.md

@@ -7,7 +7,14 @@ to [Semantic Versioning][semver].
 
 ## Unreleased
 
-- N/A
+- Combine the file path and subscriptions installation sections in integration yaml
+- Add default subscription value in integration yaml
+- Revise text labels and prompts in configuration modal
+- Update summary for success screen in integration yaml file
+- Restore comments with instructions in README
+- Reformat metrics table in README
+- Add and revise setup steps and options in README
+- Update reference documentation list
 
 ## [ 20220421.0.0 ] - 2022-04-21
 

integrations/ssl/ssl-certfile-monitoring/README.md

@@ -1,56 +1,87 @@
 ## Overview
 
-Collect metrics on and monitor local SSL certificate files.
+<!-- Sensu Integration description; supports markdown -->
 
-This integration includes the following resources:
+The SSL Certificate File Monitoring (Local) integration monitors and collects metrics for local SSL certificate files.
+
+<!-- Provide a high level overview of the integration contents (e.g. checks, filters, mutators, handlers, assets, etc) -->
+
+This integration includes the following Sensu resources:
 
 * `ssl-certfile-monitoring` [check]
-* `sensu/cert-checks` [asset]
+* `sensu/cert-checks:0.1.0` [asset]
 
 ## Dashboards
 
-There are no compatible dashboards for this integration.
+<!-- List of compatible dashboards w/ screenshots (supports png, jpeg, and gif images; relative paths only; e.g. `![](img/dashboard-1.png)` )-->
+
+<!-- This integration is compatible with the [{{dashboard_name}}][{{dashboard_link}}] (included w/ [Sensu Plus][sensu-plus]). -->
+
+<!-- ![](img/dashboard.png) -->
+
+The SSL Certificate File Monitoring (Local) integration does not have compatible dashboards.
 
 ## Setup
 
-1. Add the `ssl` subscription to agents that should run this check.
+<!-- Sensu Integration setup instructions, including Sensu agent configuration and external component configuration -->
+<!-- EXAMPLE: what configuration (if any) is required in a third-party service to enable monitoring? -->
+
+1. Get the path to your SSL certificate file. You will need the path to install this integration.
+
+1. Decide which Sensu agents should execute the `ssl-certfile-monitoring` check. You will need the agent [subscription] names when you install this integration.
+
+   <details><summary><strong>Optional: Use the default `ssl` subscription</strong></summary>
+
+   This integration includes a built-in `ssl` subscription as the default. To use the default subscription, add the `ssl` subscription to the agents that should execute the `ssl-certfile-monitoring` check.
+
+   </details>
+   <br>
+
+1. If you want to use Sensu [pipelines] to process SSL Certificate File Monitoring (Local) integration data, you will need the pipeline names when you install this integration.
 
 ## Plugins
 
+<!-- Links to any Sensu Integration dependencies (i.e. Sensu Plugins) -->
+
+The SSL Certificate File Monitoring (Local) integration uses the following Sensu [plugins]:
+
 - [sensu/cert-checks][cert-checks-bonsai] ([GitHub][cert-checks-github])
 
-## Metrics & Events
+## Alerts
 
-This integration collects the following [metrics]:
+<!-- List of all alerts generated by this integration. -->
 
-| **Metric name** | **Description** | **Tags** |
-|-----------------|-----------------|----------|
-| `cert_days_left` | Number of days until certificate expiry. Expired certificates produce a negative number. | `servername`, `subject` |
-| `cert_seconds_left` | Number of seconds until certificate expiry. Expired certificates produce a negative number. | `servername`, `subject` |
-| `cert_issued_days` | Number of days the certificate has been issued. | `servername`, `subject` |
-| `cert_issued_seconds` | Number of seconds the certificate has been issued. | `servername`, `subject` |
+The SSL Certificate File Monitoring (Local) integration uses the `output_metric_thresholds` check attribute (available as of Sensu Go 6.7.0) to trigger the following alerts based on the `cert_days_left` and `cert_issued_days` [integration metrics]:
 
-## Alerts
+**SSL certificate expiry**
 
-This integration uses `output_metric_threshold`s (new in Sensu Go version 6.7.0) to trigger the following alerts:
+- Generates a WARNING event if the `cert_days_left` is lower than a user-configurable minimum value (default 15).
+- Generates a CRITICAL event if the `cert_days_left` is lower than a user-configurable minimum value (default 7).
 
-* SSL Certificate Expiry events
+**SSL certificate issued days**
 
-  Will generate alerts and/or incidents using the configured pipelines when a SSL Certificate is nearing expiry.
+Generates a CRITICAL event if the `cert_issued_days` is greater than a user-configurable maximum value (default 398). Many clients do not accept certificates that are issued for more than [398 days].
 
-  * **Default Behaviour**: will issue a `WARNING` status event if `cert_days_left` is 15 days or less, and a `CRITICAL` status event if `cert_days_left` is 7 days or less.
+## Metrics
 
-* SSL Configuration configuration events
+<!-- List of all metrics or events collected by this integration. -->
 
-  Will generate alerts and/or incidents using the configured pipelines when a SSL Certificate has been issued for too many days (which may lead it to not be accepted by many clients).
+The SSL Certificate File Monitoring (Local) integration collects the following [metrics]:
 
-  * **Default Behaviour**: will issue a `CRITICAL` status event if `cert_issued_days` is greater than 398 days (read [this article](https://thehackernews.com/2020/09/ssl-tls-certificate-validity-398.html)).
+Metric name | Description | Tags
+----------- | ----------- | ----
+`cert_days_left` | Number of days until certificate expiry. Expired certificates produce a negative number. | `servername`, `subject`
+`cert_issued_days` | Number of days for which the certificate is issued. | `servername`, `subject`
+`cert_issued_seconds` | Number of seconds for which the certificate is issued. | `servername`, `subject`
+`cert_seconds_left` | Number of seconds until certificate expiry. Expired certificates produce a negative number. | `servername`, `subject`
 
 ## Reference Documentation
 
-* [Maximum Lifespan of SSL/TLS Certificates is 398 Days Starting Today](https://thehackernews.com/2020/09/ssl-tls-certificate-validity-398.html)
-* [Round-robin check scheduling reference documentation](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/#round-robin-checks)
-* [Proxy entity reference documentation](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-entities/entities/#create-and-manage-proxy-entities)
+<!-- Please provide links to any relevant reference documentation to help users learn more and/or troubleshoot this integration; specifically including any third-party software documentation. -->
+
+* [Metric threshold evaluation] (Sensu documentation)
+* [398-Day Browser Limit for SSL/TLS Certificates Begins September 1, 2020][398 days] (SSL.com article)
+
 
 <!-- Links -->
 [check]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/
@@ -62,11 +93,13 @@ This integration uses `output_metric_threshold`s (new in Sensu Go version 6.7.0)
 [plugins]: https://docs.sensu.io/sensu-go/latest/plugins/
 [metrics]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/metrics/
 [handler]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/handlers/
-[pipeline]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/
+[pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/
 [secret]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets/
 [secrets]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets/
 [tokens]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/tokens/
 [sensu-plus]: https://sensu.io/features/analytics
-[metric-threshold-rule]: #
 [cert-checks-bonsai]: https://bonsai.sensu.io/assets/sensu/cert-checks
 [cert-checks-github]: https://github.com/sensu/cert-checks
+[integraton metrics]: #metrics
+[398 days]: https://www.ssl.com/blogs/398-day-browser-limit-for-ssl-tls-certificates-begins-september-1-2020/
+[Metric threshold evaluation]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/metrics/#metric-threshold-evaluation

integrations/ssl/ssl-certfile-monitoring/sensu-integration.yaml

@@ -7,8 +7,8 @@ metadata:
 spec:
   class: supported
   provider: monitoring
-  display_name: SSL Certificate File Monitoring (Local)
-  short_description: Monitor Local SSL Certificate File Validity
+  display_name: SSL Certificate Monitoring (Local)
+  short_description: Monitor and collect metrics for local SSL certificate files
   supported_platforms:
     - linux
     - darwin
@@ -24,102 +24,99 @@ spec:
     - "@thoward"
   prompts:
     - type: section
-      title: SSL Certificate Check
+      title: SSL Certificate Path and Sensu Subscriptions
     - type: markdown
       body: |
-        Configure your SSL Certificate Check with the following parameters:
-
-        * File path
+        Provide the path for your SSL certificate file and the subscriptions for Sensu agents that should execute the `ssl-certfile-monitoring` check
     - type: question
       name: path
       required: true
       input:
         type: string
-        title: SSL Certificate File Path
+        title: Path for SSL certificate
         description: >-
-          Provide the SSL certificate file path (e.g. /var/lib/path/to/my/certificate)
+          Enter the path for the SSL certificate file (e.g. /var/lib/path/to/my/certificate)
+    - type: question
+      name: subscriptions
+      input:
+        type: array
+        items:
+          type: string
+          title: Subscriptions
+          ref: core/v2/entity/subscriptions
+        default:
+          - ssl
     - type: section
       title: Check Thresholds
     - type: markdown
       body: |
-        Configure Sensu check warning and critical thresholds for:
+        Provide these configuration parameters for Sensu check thresholds:
 
-          * Days Left Minimum Thresholds (warning and critical)
-          * Days Since Issued Maximum Threshold
+          * WARNING threshold for number of days left before SSL certificate expiry
+          * CRITICAL threshold for number of days left before SSL certificate expiry
+          * CRITICAL threshold for number of days for which the SSL certificate is issued (many clients do not accept certificates that are issued for more than [398 days])
 
+          [398 days]: https://www.ssl.com/blogs/398-day-browser-limit-for-ssl-tls-certificates-begins-september-1-2020/
     - type: question
-      name: ssl_cert_check_days_left_critical_threshold
-      required: false
+      name: ssl_cert_check_days_left_warning_threshold
       input:
-        default: 7
+        default: 15
         type: integer
-        title: Days Left Critical Threshold
+        title: Days left (WARNING threshold)
         description: >-
-          The minimum number of days left on the certificate before triggering a critical alert (default 7 days).
+          Specify the number of days remaining before SSL certificate expiry that will trigger a WARNING alert (default is 15)
     - type: question
-      name: ssl_cert_check_days_left_warning_threshold
+      name: ssl_cert_check_days_left_critical_threshold
+      required: false
       input:
-        default: 15
+        default: 7
         type: integer
-        title: Days Left Warning Threshold
+        title: Days left (CRITICAL threshold)
         description: >-
-          The minimum number of days left on the certificate before triggering a warning alert (default 15 days).
+          Specify the number of days remaining before SSL certificate expiry that will trigger a CRITICAL alert (default is 7)
     - type: question
       name: ssl_cert_check_days_issued_critical_threshold
       input:
         default: 398
         type: integer
-        title: Days Issued Critical Threshold
+        title: Days issued (CRITICAL threshold)
         description: >-
           The maximum number of days since the certificate was issued before triggering a critical alert (default 398 days).
-    - type: section
-      title: Configure Sensu Subscriptions
-    - type: markdown
-      body: |
-        Configure which Sensu Agent subscriptions this check should be run on.
-    - type: question
-      name: subscriptions
-      input:
-        type: array
-        items:
-          type: string
-          title: Sensu Subscriptions
-          ref: core/v2/entity/subscriptions
     - type: section
       title: Pipeline Configuration
     - type: markdown
       body: |
-        Configure one or more [pipelines] for processing SSL Cert monitoring events.
+        Name the [pipelines] you want to use to process SSL Certificate File Monitoring (Local) integration data.
 
-        [pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/
+        [pipelines]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/pipelines/
     - type: question
       name: alert_pipeline
       required: false
       input:
         type: string
-        title: Alert Pipeline
+        title: Alert pipeline name
         description: >-
-          How do you want to be alerted for failures detected by this pipeline (e.g. Slack or Microsoft Teams)?
+          Which pipeline do you want to use for alerts due to failures this integration detects?
         ref: core/v2/pipeline/metadata/name
         refFilter: .labels.provider == "alerts"
     - type: question
       name: incident_pipeline
       required: false
       input:
         type: string
-        title: Incident Management Pipeline
+        title: Incident management pipeline name
         description: >-
-          How do you want to process incidents for failures detected by this pipeline (e.g. Atlassian JIRA/ServiceDesk, or Pagerduty)?
+          Which pipeline do you want to use to process incidents due to failures this integration detects?
         ref: core/v2/pipeline/metadata/name
         refFilter: .labels.provider == "incidents"
     - type: question
       name: metrics_pipeline
       required: false
       input:
         type: string
-        title: Metrics Pipeline
+        title: Metrics pipeline name
         description: >-
-          How do you want to process metrics collected by this integration?
+          Which pipeline do you want to use to process the metrics this integration collects?
         ref: core/v2/pipeline/metadata/name
         refFilter: .labels.provider == "metrics"
   resource_patches:
@@ -135,7 +132,7 @@ spec:
             --cert file://[[path]]
         - path: /spec/subscriptions
           op: replace
-          value: subscriptions
+          value: "[[subscriptions]]"
         - path: /spec/output_metric_tags/-
           op: add
           value:
@@ -173,4 +170,6 @@ spec:
       title: Success
     - type: markdown
       body: |
-        You have successfully enabled SSL Certificate monitoring.
+        You enabled the SSL Certificate File Monitoring (Local) integration for the certificate at [[path]].
+
+        The `ssl-certfile-monitoring` check will run for all Sensu agents with these subscriptions: [[subscriptions]].