https-wrench.schema.json

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "$ref": "#/definitions/HttpsWrenchConfiguration",
  "definitions": {
    "HttpsWrenchConfiguration": {
      "type": "object",
      "additionalProperties": false,
      "description": "Top-level configuration for https-wrench requests.",
      "properties": {
        "debug": {
          "type": "boolean",
          "description": "Enables global debug mode to print additional diagnostic information."
        },
        "verbose": {
          "type": "boolean",
          "description": "Enables verbose output, showing more details during execution."
        },
        "caBundle": {
          "type": "string",
          "description": "PEM-encoded CA certificate bundle used to verify server certificates. When omitted, the system trust store is used."
        },
        "concurrency": {
          "type": "integer",
          "default": 10,
          "description": "Maximum number of concurrent HTTP requests (1 for sequential; defaults to 10 if omitted or <= 0)."
        },
        "observability": {
          "$ref": "#/definitions/Observability"
        },
        "baseRequest": {
          "$ref": "#/definitions/RequestDefaults",
          "description": "YAML-only shared request template. Define an anchor (e.g. baseRequest: &base) and merge into requests with <<: *base. Ignored by https-wrench at runtime."
        },
        "requests": {
          "type": "array",
          "description": "List of HTTPS requests to execute.",
          "items": {
            "$ref": "#/definitions/Request"
          }
        }
      },
      "required": [
        "requests",
        "verbose"
      ],
      "title": "HttpsWrenchConfiguration"
    },
    "RequestDefaults": {
      "type": "object",
      "additionalProperties": false,
      "description": "Shared request fields with no required keys. Used by baseRequest anchors and merged into requests[] entries.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Descriptive name for this request, used in output. Required on each requests[] entry."
        },
        "transportOverrideUrl": {
          "type": "string",
          "format": "uri",
          "qt-uri-protocols": [
            "https"
          ],
          "pattern": "^https://",
          "description": "TLS/TCP dial address (https://host or https://ip:port). The logical hostname remains hosts[].name for Host header and SNI."
        },
        "clientTimeout": {
          "type": "integer",
          "minimum": 0,
          "description": "HTTP client timeout in seconds."
        },
        "requestDebug": {
          "type": "boolean",
          "description": "If true, dumps the raw outgoing HTTP request for debugging."
        },
        "responseDebug": {
          "type": "boolean",
          "description": "If true, dumps the raw HTTP response, including TLS connection details, for debugging."
        },
        "responseBodyMatchRegexp": {
          "type": "string",
          "description": "Regular expression that the response body must match."
        },
        "responseBodyFailRegexp": {
          "type": "string",
          "description": "Regular expression that causes the probe to fail if it matches the response body."
        },
        "responseHeaderMatchRegexp": {
          "type": "object",
          "description": "Map of response header names to regular expressions that must match.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "responseHeaderFailRegexp": {
          "type": "object",
          "description": "Map of response header names to regular expressions that fail the probe if matched.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "validStatusCodes": {
          "type": "array",
          "description": "List of HTTP status codes considered successful. When omitted or empty, defaults to 200..399.",
          "items": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          }
        },
        "printResponseBody": {
          "type": "boolean",
          "description": "If true, prints the HTTP response body."
        },
        "printResponseHeaders": {
          "type": "boolean",
          "description": "If true, prints HTTP response headers."
        },
        "printResponseCertificates": {
          "type": "boolean",
          "description": "If true, prints TLS certificates from the peer chain."
        },
        "responseCertificatesFilter": {
          "type": "array",
          "description": "Filter to display only specific certificates from the peer chain and/or only subset of fields for each certificate. Each item in the array is a map of certificate index (0-indexed, where 0 is the leaf certificate) to a list of certificate fields to render (e.g. Subject, DNSNames, Issuer, NotBefore, NotAfter, Expiration). If the list of fields is empty, all fields for that certificate are printed.",
          "items": {
            "type": "object",
            "description": "Map of certificate chain index to the list of certificate fields to print.",
            "patternProperties": {
              "^[0-9]+$": {
                "type": "array",
                "description": "Certificate fields to print for the given chain index.",
                "items": {
                  "type": "string",
                  "description": "Certificate field name to include in output.",
                  "enum": [
                    "Subject",
                    "DNSNames",
                    "Issuer",
                    "NotBefore",
                    "NotAfter",
                    "Expiration",
                    "IsCA",
                    "AuthorityKeyId",
                    "SubjectKeyId",
                    "PublicKeyAlgorithm",
                    "SignatureAlgorithm",
                    "SerialNumber",
                    "Fingerprint SHA-256"
                  ]
                }
              }
            },
            "additionalProperties": false
          }
        },
        "enableProxyProtocolV2": {
          "type": "boolean",
          "description": "If true, sends an HAProxy PROXY protocol v2 header on connect. Requires transportOverrideUrl."
        },
        "insecure": {
          "type": "boolean",
          "description": "If true, skips TLS server certificate verification (InsecureSkipVerify)."
        },
        "followRedirects": {
          "type": "boolean",
          "description": "If true, follows HTTP redirects. Defaults to false."
        },
        "responseHeadersFilter": {
          "type": "array",
          "description": "Response header names to include when printResponseHeaders is enabled.",
          "items": {
            "type": "string",
            "pattern": "^[A-Z]",
            "description": "HTTP response header name. Must start with an uppercase letter."
          }
        },
        "requestBody": {
          "type": "string",
          "description": "HTTP request body payload."
        },
        "requestMethod": {
          "type": "string",
          "pattern": "^(POST|GET|HEAD|PUT|DELETE|PATCH|HEAD|OPTIONS|TRACE)$",
          "description": "HTTP method for the request. Defaults to GET when omitted."
        },
        "requestHeaders": {
          "type": "array",
          "description": "Custom HTTP request headers to send.",
          "items": {
            "$ref": "#/definitions/RequestHeader"
          }
        },
        "userAgent": {
          "type": "string",
          "description": "Custom User-Agent string for the request."
        },
        "hosts": {
          "type": "array",
          "description": "Target hostnames and paths to request. Required on each requests[] entry.",
          "items": {
            "$ref": "#/definitions/Host"
          }
        }
      },
      "dependencies": {
        "enableProxyProtocolV2": [
          "transportOverrideUrl"
        ],
        "responseCertificatesFilter": [
          "printResponseCertificates"
        ]
      },
      "title": "RequestDefaults"
    },
    "Request": {
      "description": "A single HTTPS probe definition. Each entry must include name and hosts.",
      "allOf": [
        {
          "$ref": "#/definitions/RequestDefaults"
        },
        {
          "required": [
            "name",
            "hosts"
          ]
        }
      ],
      "title": "Request"
    },
    "Host": {
      "type": "object",
      "additionalProperties": false,
      "description": "A logical hostname and the URI paths to request on it.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Hostname used for the request URL, Host header, and TLS ServerName indication."
        },
        "uriList": {
          "type": "array",
          "description": "URI paths to request on this host. Each path must start with /. When omitted, tool defaults apply.",
          "items": {
            "type": "string",
            "pattern": "^/",
            "description": "Request path starting with /."
          }
        }
      },
      "required": [
        "name"
      ],
      "title": "Host"
    },
    "RequestHeader": {
      "type": "object",
      "additionalProperties": false,
      "description": "A single HTTP request header key-value pair.",
      "properties": {
        "key": {
          "type": "string",
          "description": "HTTP header name."
        },
        "value": {
          "type": "string",
          "description": "HTTP header value."
        }
      },
      "required": [
        "key",
        "value"
      ],
      "title": "RequestHeader"
    },
    "Observability": {
      "type": "object",
      "additionalProperties": false,
      "description": "Configuration for continuous observability mode, interval execution, and metrics export.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enables continuous observability mode."
        },
        "interval": {
          "type": "string",
          "default": "30s",
          "description": "Interval between probe execution cycles (e.g. '15s', '30s', '1m')."
        },
        "timeout": {
          "type": "string",
          "default": "25s",
          "description": "Maximum execution duration for a single probe cycle (e.g. '10s', '25s')."
        },
        "pull": {
          "$ref": "#/definitions/ObservabilityPull"
        },
        "push": {
          "$ref": "#/definitions/ObservabilityPush"
        },
        "metrics": {
          "$ref": "#/definitions/ObservabilityMetrics"
        },
        "logging": {
          "$ref": "#/definitions/ObservabilityLogging"
        }
      }
    },
    "ObservabilityPull": {
      "type": "object",
      "additionalProperties": false,
      "description": "Prometheus pull HTTP scrape server settings.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Whether the Prometheus metrics HTTP scrape server is enabled."
        },
        "address": {
          "type": "string",
          "default": ":9090",
          "description": "Network address to bind the HTTP scrape server to (e.g. ':9090', '0.0.0.0:9090')."
        },
        "path": {
          "type": "string",
          "default": "/metrics",
          "description": "URL path for Prometheus metrics exposition."
        },
        "reloadToken": {
          "type": "string",
          "description": "Optional secret token required to authorize POST /-/reload requests from non-loopback addresses."
        },
        "reloadSecret": {
          "type": "string",
          "description": "Alias for reloadToken."
        }
      }
    },
    "ObservabilityPush": {
      "type": "object",
      "additionalProperties": false,
      "description": "Push configuration for Prometheus remote_write and OpenTelemetry OTLP destinations.",
      "properties": {
        "prometheus": {
          "$ref": "#/definitions/ObservabilityPushPrometheus"
        },
        "otlp": {
          "$ref": "#/definitions/ObservabilityPushOTLP"
        }
      }
    },
    "ObservabilityPushPrometheus": {
      "type": "object",
      "additionalProperties": false,
      "description": "Prometheus remote_write push configuration.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enables pushing metrics to a Prometheus remote_write endpoint."
        },
        "remoteWriteUrl": {
          "type": "string",
          "format": "uri",
          "description": "Target Prometheus remote_write endpoint URL."
        },
        "timeout": {
          "type": "string",
          "default": "10s",
          "description": "HTTP request timeout for remote_write push."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Custom HTTP headers to send with the remote_write request."
        },
        "basicAuthUser": {
          "type": "string",
          "description": "Username for HTTP Basic Authentication."
        },
        "basicAuthPassword": {
          "type": "string",
          "description": "Password for HTTP Basic Authentication."
        },
        "bearerToken": {
          "type": "string",
          "description": "Bearer token for HTTP Authorization header."
        }
      }
    },
    "ObservabilityPushOTLP": {
      "type": "object",
      "additionalProperties": false,
      "description": "OpenTelemetry OTLP push configuration.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enables pushing metrics to an OpenTelemetry OTLP endpoint."
        },
        "endpoint": {
          "type": "string",
          "description": "Target OpenTelemetry collector endpoint (e.g. 'https://otel:4318/v1/metrics')."
        },
        "protocol": {
          "type": "string",
          "enum": [
            "http/protobuf"
          ],
          "default": "http/protobuf",
          "description": "OTLP transport protocol."
        },
        "timeout": {
          "type": "string",
          "default": "10s",
          "description": "HTTP request timeout for OTLP push."
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Custom HTTP headers to send with OTLP requests."
        }
      }
    },
    "ObservabilityMetrics": {
      "type": "object",
      "additionalProperties": false,
      "description": "Filtering and customization options for generated metrics.",
      "properties": {
        "includeTls": {
          "type": "boolean",
          "default": true,
          "description": "Whether to generate TLS connection and certificate lifecycle metrics."
        },
        "includeCertChain": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include intermediate/root certificates in certificate metrics (defaults to leaf only)."
        },
        "stripQuery": {
          "type": "boolean",
          "default": true,
          "description": "Whether to strip query strings from URL path labels to prevent cardinality explosion."
        },
        "customLabels": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Static custom labels to append to all exported metrics."
        }
      }
    },
    "ObservabilityLogging": {
      "type": "object",
      "additionalProperties": false,
      "description": "Structured logging configuration for observability mode.",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "debug",
            "info",
            "warn",
            "warning",
            "error"
          ],
          "default": "info",
          "description": "Minimum log severity level to output."
        },
        "format": {
          "type": "string",
          "enum": [
            "text",
            "json"
          ],
          "default": "text",
          "description": "Format for structured log output."
        }
      }
    }
  }
}