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."
        },
        "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."
        },
        "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)."
        },
        "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"
    }
  }
}