feat(json-values): add bearer token auth, custom headers, and per-key thresholds

* --token adds HTTP bearer authentication
* --header (curl-style "Name: Value", repeatable) sends arbitrary custom headers
* --warning-key/--warning and --critical-key/--critical alert on a numeric value at a specific JSON key with Nagios range syntax; the overall state is the worst of the JSON state and the two key-level thresholds
* all --*-key parameters now support dot-notation for nested keys (e.g. --state-key=meta.state, --critical-key=detailedInfo.count1)
* empty --state-key is treated as an explicit opt-out so threshold-only monitoring of schema-free JSON responses no longer collapses to UNKNOWN
* add unit tests covering flat/nested fixtures, state coercion edge cases, and the threshold semantics, with a fixture copied verbatim from the issue body

Closes #1005

Author: markuslf

CHANGELOG.md

@@ -36,6 +36,7 @@ Monitoring Plugins:
 * infomaniak-swiss-backup-devices: add `--ignore-customer`, `--ignore-name`, `--ignore-tag`, `--ignore-user` parameters to skip devices by regex
 * infomaniak-swiss-backup-products: add `--ignore-customer`, `--ignore-tag` parameters to skip products by regex
 * ipmi-sel: add `--ignore` parameter to filter out SEL entries by regex, e.g. auto-generated "Log area reset/cleared" entries after `ipmitool sel clear` ([#982](https://github.com/Linuxfabrik/monitoring-plugins/issues/982))
+* json-values: add `--token` and `--header` parameters for HTTP bearer-token and custom header authentication when fetching JSON from protected endpoints, add `--warning-key` / `--warning` and `--critical-key` / `--critical` to alert on a numeric value at a specific JSON key (with Nagios range syntax), and support dot-notation for nested keys in all `--*-key` parameters (e.g. `--state-key=meta.state`) ([#1005](https://github.com/Linuxfabrik/monitoring-plugins/issues/1005))
 * librenms-alerts: add device-type `management`
 * librenms-health: add device-type `management`
 * nextcloud-enterprise: provides information about an installed Nextcloud Enterprise subscription

check-plugins/json-values/README.md

@@ -11,6 +11,9 @@ Parses a JSON object from a local file, HTTP/HTTPS URL, or SMB share and extract
 * Extracts the output message from the key specified by `--message-key` (default: `message`)
 * Extracts the perfdata string from the key specified by `--perfdata-key` (default: `perfdata`)
 * Extracts the return state from the key specified by `--state-key` (default: `state`)
+* All `--*-key` parameters support dot-notation for nested keys (e.g. `--state-key=meta.state`)
+* HTTP endpoints can be authenticated with a bearer token (`--token`) and/or custom request headers (`--header`, curl-style `"Name: Value"`, can be specified multiple times)
+* In addition to the state extracted from the JSON itself, the value at a specific JSON key can be alerted on via `--warning-key`/`--warning` and `--critical-key`/`--critical` (Nagios range syntax); the value at the referenced key must be numeric, otherwise the check returns UNKNOWN. The overall check state is the worst of the JSON state and the two key-level thresholds.
 
 
 ## Fact Sheet
@@ -29,41 +32,90 @@ Parses a JSON object from a local file, HTTP/HTTPS URL, or SMB share and extract
 ## Help
 
 ```text
-usage: json-values [-h] [-V] [--always-ok] [--filename FILENAME] [--insecure]
-                   [--message-key MESSAGE_KEY] [--no-proxy]
-                   [--password PASSWORD] [--perfdata-key PERFDATA_KEY]
-                   [--state-key STATE_KEY] [--timeout TIMEOUT] [-u URL]
-                   [--username USERNAME]
-
-Parses a JSON array from a file, URL, or SMB share and extracts message,
-state, and perfdata values from specific keys. Useful for integrating custom
-applications or APIs that provide monitoring data in JSON format. Alerts based
-on the state value extracted from the JSON data.
+usage: json-values [-h] [-V] [--always-ok] [-c CRIT]
+                   [--critical-key CRITICAL_KEY] [--filename FILENAME]
+                   [--header HEADER] [--insecure] [--message-key MESSAGE_KEY]
+                   [--no-proxy] [--password PASSWORD]
+                   [--perfdata-key PERFDATA_KEY] [--state-key STATE_KEY]
+                   [--timeout TIMEOUT] [--token TOKEN] [-u URL]
+                   [--username USERNAME] [-w WARN] [--warning-key WARNING_KEY]
+
+Parses a JSON object from a file, URL, or SMB share and extracts message,
+state, and perfdata values from configurable keys. Useful for integrating
+custom applications or APIs that expose monitoring data as JSON. Supports HTTP
+bearer-token and arbitrary header authentication, dot-notation for nested JSON
+keys, and per-key Nagios-range thresholds in addition to the state value
+extracted from the JSON itself.
 
 options:
   -h, --help            show this help message and exit
   -V, --version         show program's version number and exit
   --always-ok           Always returns OK.
+  -c, --critical CRIT   Nagios range expression evaluated for the CRIT state
+                        against the value of the JSON key referenced by
+                        --critical-key. Example: `--critical-key=days
+                        --critical=1`. Example: `--critical-
+                        key=detailedInfo.count1 --critical=@90:100`. Default:
+                        None
+  --critical-key CRITICAL_KEY
+                        Name of the JSON key whose value should be evaluated
+                        against --critical for the CRIT state. Supports dot-
+                        notation for nested keys (e.g. `detailedInfo.count1`).
+                        The value at the resolved key must be numeric in the
+                        JSON, otherwise the check returns UNKNOWN. Example:
+                        `--critical-key=days`. Example: `--critical-
+                        key=detailedInfo.count1`. Default: None
   --filename FILENAME   Path to a local JSON file. Mutually exclusive with -u
                         / --url.
+  --header HEADER       Custom HTTP request header to send when fetching the
+                        URL. curl-style format `"Name: Value"`. Can be
+                        specified multiple times. Example: `--header="X-API-
+                        Key: linuxfabrik"`. Example: `--header="Accept:
+                        application/json"`. Default: None
   --insecure            This option explicitly allows insecure SSL
                         connections.
   --message-key MESSAGE_KEY
-                        Name of the JSON array key containing the output
-                        message. Default: message
+                        Name of the JSON key containing the output message.
+                        Supports dot-notation for nested keys (e.g.
+                        `meta.message`). Example: `--message-
+                        key=meta.message`. Default: message
   --no-proxy            Do not use a proxy.
   --password PASSWORD   Password for SMB authentication.
   --perfdata-key PERFDATA_KEY
-                        Name of the JSON array key containing the perfdata.
-                        Default: perfdata
+                        Name of the JSON key containing the perfdata. Supports
+                        dot-notation for nested keys (e.g. `meta.perfdata`).
+                        Example: `--perfdata-key=meta.perfdata`. Default:
+                        perfdata
   --state-key STATE_KEY
-                        Name of the JSON array key containing the state.
-                        Default: state
+                        Name of the JSON key containing the state. Supports
+                        dot-notation for nested keys (e.g. `meta.state`).
+                        Example: `--state-key=meta.state`. Default: state
   --timeout TIMEOUT     Network timeout in seconds. Default: 3 (seconds)
+  --token TOKEN         HTTP bearer token. Adds an `Authorization: Bearer
+                        <token>` header to the URL request. Can be combined
+                        with --header to send additional custom headers (e.g.
+                        `--token=linuxfabrik --header="Accept:
+                        application/json"`); a manual
+                        `--header="Authorization: ..."` is overridden by
+                        --token if both are specified. Default: None
   -u, --url URL         URL of the JSON file, starting with "http://",
                         "https://", or "smb://". Mutually exclusive with
                         --filename.
   --username USERNAME   Username for SMB authentication.
+  -w, --warning WARN    Nagios range expression evaluated for the WARN state
+                        against the value of the JSON key referenced by
+                        --warning-key. Example: `--warning-key=days
+                        --warning=7`. Example: `--warning-
+                        key=detailedInfo.count1 --warning=@80:90`. Default:
+                        None
+  --warning-key WARNING_KEY
+                        Name of the JSON key whose value should be evaluated
+                        against --warning for the WARN state. Supports dot-
+                        notation for nested keys (e.g. `detailedInfo.count1`).
+                        The value at the resolved key must be numeric in the
+                        JSON, otherwise the check returns UNKNOWN. Example:
+                        `--warning-key=days`. Example: `--warning-
+                        key=detailedInfo.count1`. Default: None
 ```
 
 
@@ -90,11 +142,33 @@ Output:
 This is a test message|'cpu-usage'=5.6%;80;90;0;100
 ```
 
+Fetching from a protected HTTP endpoint with a bearer token and an additional `Accept` header, and reading a nested state key:
+
+```bash
+./json-values \
+    --url=https://api.example.com/monitoring \
+    --token=linuxfabrik \
+    --header='Accept: application/json' \
+    --state-key=meta.state \
+    --message-key=meta.message \
+    --perfdata-key=meta.perfdata
+```
+
+Alerting on a numeric value inside a nested JSON key with Nagios range expressions (`@80:90` means alert when inside the range, inclusive):
+
+```bash
+./json-values \
+    --filename=/tmp/example.json \
+    --warning-key=detailedInfo.count1 --warning=@80:90 \
+    --critical-key=detailedInfo.count1 --critical=@90:100
+```
+
 
 ## States
 
-* Returns the state value from the JSON object (0=OK, 1=WARN, 2=CRIT, 3=UNKNOWN).
-* UNKNOWN if `--filename` and `--url` are used together, if the URL protocol is unsupported, if JSON parsing fails, or if the state key is missing.
+* Returns the worst of three states: the state extracted from the JSON object (0=OK, 1=WARN, 2=CRIT, 3=UNKNOWN), the state computed from `--warning-key` / `--warning`, and the state computed from `--critical-key` / `--critical`.
+* UNKNOWN if `--filename` and `--url` are used together, if the URL protocol is unsupported, if JSON parsing fails, if the state key is missing or does not resolve to an integer in the range `0..3`, or if a threshold key cannot be resolved or is not numeric.
+* `--warning` / `--warning-key` and `--critical` / `--critical-key` must be specified together (range without a key has nothing to compare, key without a range would silently never alert).
 * `--always-ok` suppresses all alerts and always returns OK.