runspec-linux 0.4.3__tar.gz → 0.6.0__tar.gz

{runspec_linux-0.4.3 → runspec_linux-0.6.0}/CHANGELOG.md

@@ -1,5 +1,55 @@
 # runspec-linux Changelog
 
+## [0.6.0] — 2026-06-22
+
+Add a **`which`** runnable — locate a command on the PATH and return its full
+path, like the `which` command (`autonomy = "autonomous"`, `output = "json"`). A
+thin wrapper over the new `runspec_linux_core.which` helper (requires
+`runspec-linux-core >= 0.3.3`). Handy for finding an interpreter/binary path
+(e.g. `which python3`) to feed another runnable such as `create-venv`, without
+hunting through `/usr/bin` in the path browser.
+
+- Positional `name` accepts one command or several space-separated
+  (`which "python3 pip3 git"`).
+- `--all`/`-a` returns every match on the PATH, not just the first.
+- `--path` overrides the search PATH (defaults to the host's `$PATH`).
+- Prints `{path, all_found, results: [{name, found, path, paths}]}` and, mirroring
+  the `which` command, exits non-zero when any name was not found.
+
+## [0.5.0] — 2026-06-22
+
+Add 8 cross-platform **web / TLS / API** runnables — thin wrappers over the new
+`runspec-webops-core` (a new dependency). All are read-only network probes
+(`autonomy = "autonomous"`, `output = "json"`) and use only the Python stdlib,
+so the same runnables ship in `runspec-windows` too. They are a Python port of
+the `runspec-webops` Node package (plus four extras), so a fleet that can't run
+Node still gets them.
+
+- **`cert-check`** — inspect a host's TLS certificate (days-to-expiry, issuer,
+  SANs, fingerprint, trust). Exits `1` when expiring/expired, `2` when
+  unreachable. Args: `--port`/`-p` (443), `--warn-days`/`-w` (30),
+  `--timeout`/`-t` (10).
+- **`cert-chain`** — print the full certificate chain (leaf → intermediates →
+  root), flagging the self-signed root.
+- **`tls-info`** — report the negotiated TLS protocol, cipher, and trust result.
+- **`http-check`** — probe an HTTP(S) URL (status, response time, redirect
+  target); `--expect-status`/`-e` exits non-zero on a mismatch; `--insecure`/`-k`
+  skips TLS verification.
+- **`http-headers`** — fetch response headers and flag missing security headers
+  (HSTS, CSP, X-Frame-Options, …); `--method`/`-m` (HEAD/GET).
+- **`redirect-trace`** — follow the redirect chain hop by hop with loop
+  detection; `--max-hops`/`-n` (10).
+- **`dns-lookup`** — resolve a hostname (A/AAAA + canonical name) or
+  reverse-resolve an IP; `--reverse`/`-r` also PTRs each resolved address.
+- **`api-spec`** — read an OpenAPI/Swagger spec (`source` = an http(s) URL or a
+  local file) and condense its shape to bounded JSON, so an agent can write or
+  update the runnables that call an internal API (and re-check when it drifts).
+  Default is an overview (info, servers, every operation), narrowable with
+  `--tag` / `--match`; `--operation`/`-o` (or `--path` + `--method`/`-X`) drills
+  into one operation's params, request body and responses with `$ref`s resolved.
+  OpenAPI 3.x and Swagger 2.0; JSON needs no extra, YAML needs
+  `runspec-webops-core[yaml]`.
+
 ## [0.4.3] — 2026-06-21
 
 - **`install-into-venv --venv` and `configure-pip --venv` are now marked

{runspec_linux-0.4.3 → runspec_linux-0.6.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: runspec-linux
-Version: 0.4.3
+Version: 0.6.0
 Summary: Linux system admin runnables for runspec
 Requires-Python: >=3.10
-Requires-Dist: runspec-linux-core>=0.3.2
+Requires-Dist: runspec-linux-core>=0.3.3
+Requires-Dist: runspec-webops-core>=0.1.0
 Requires-Dist: runspec>=0.27.0
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'

{runspec_linux-0.4.3 → runspec_linux-0.6.0}/pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux"
-version = "0.4.3"
+version = "0.6.0"
 requires-python = ">=3.10"
 description = "Linux system admin runnables for runspec"
 dependencies = [
     "runspec>=0.27.0",
-    "runspec-linux-core>=0.3.2",
+    "runspec-linux-core>=0.3.3",
+    "runspec-webops-core>=0.1.0",
 ]
 
 [project.scripts]
@@ -44,6 +45,16 @@ create-venv       = "runspec_linux.venvs:main_create_venv"
 install-into-venv = "runspec_linux.venvs:main_install_into_venv"
 configure-pip     = "runspec_linux.venvs:main_configure_pip"
 nc-command        = "runspec_linux.nc_command:main"
+which             = "runspec_linux.commands:main_which"
+# Web / TLS probes (runspec-webops-core; cross-platform)
+cert-check        = "runspec_linux.webops:main_cert_check"
+cert-chain        = "runspec_linux.webops:main_cert_chain"
+tls-info          = "runspec_linux.webops:main_tls_info"
+http-check        = "runspec_linux.webops:main_http_check"
+http-headers      = "runspec_linux.webops:main_http_headers"
+redirect-trace    = "runspec_linux.webops:main_redirect_trace"
+dns-lookup        = "runspec_linux.webops:main_dns_lookup"
+api-spec          = "runspec_linux.webops:main_api_spec"
 
 [project.optional-dependencies]
 dev = [

{runspec_linux-0.4.3 → runspec_linux-0.6.0}/runspec_linux/__init__.py

@@ -39,6 +39,7 @@ from runspec_linux_core import (
     system_info,
     tail_log,
     upgrade_packages,
+    which,
     who,
 )
 
@@ -74,5 +75,6 @@ __all__ = [
     "system_info",
     "tail_log",
     "upgrade_packages",
+    "which",
     "who",
 ]

runspec_linux-0.6.0/runspec_linux/commands.py

@@ -0,0 +1,23 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_linux_core import which
+from runspec_linux_core.errors import LinuxCoreError
+
+
+def main_which() -> None:
+    spec = rs.parse("which")
+    try:
+        result = which(
+            spec.name.value,
+            all_matches=spec.all.value,
+            path=spec.path.value or None,
+        )
+    except (ValueError, LinuxCoreError) as e:
+        print(json.dumps({"error": str(e)}))
+        sys.exit(1)
+    print(json.dumps(result))
+    # Mirror the `which` command: non-zero exit when any name was not found.
+    if not result["all_found"]:
+        sys.exit(1)

{runspec_linux-0.4.3 → runspec_linux-0.6.0}/runspec_linux/runspec.toml

@@ -439,6 +439,36 @@ type        = "float"
 description = "Per-chunk socket read timeout in seconds"
 default     = 0.1
 
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+[which]
+serve       = ["local"]
+description = "Locate a command on the PATH and return its full path (like the `which` command) — handy for finding interpreter/binary paths to feed other runnables"
+autonomy    = "autonomous"
+output      = "json"
+
+examples = [
+  {cmd = "which python3",              description = "Resolve a command to its full path"},
+  {cmd = "which \"python3 pip3 git\"", description = "Resolve several commands at once (space-separated)"},
+  {cmd = "which python3 --all",        description = "Show every match on the PATH, not just the first"},
+]
+
+[which.args.name]
+type        = "str"
+position    = 1
+description = "Command name(s) to locate on the PATH (space-separated for several)"
+
+[which.args.all]
+type        = "flag"
+short       = "-a"
+description = "Return every match found on the PATH, not just the first"
+default     = false
+
+[which.args.path]
+type        = "str"
+description = "Override the search PATH to use (defaults to the host's $PATH)"
+required    = false
+
 # ── Python venvs ──────────────────────────────────────────────────────────────
 
 # These deliberately declare NO `run_as` key. The service account that owns a
@@ -627,3 +657,242 @@ type        = "choice"
 options     = ["sudo", "su"]
 default     = "sudo"
 description = "How to escalate to run-as: sudo (passwordless, -n) or su"
+
+# ── Web / TLS probes (runspec-webops-core; cross-platform, read-only) ──────────
+
+[cert-check]
+serve       = ["local"]
+description = "Inspect a host's TLS certificate — days-to-expiry, issuer, SANs, fingerprint, trust"
+autonomy    = "autonomous"
+output      = "json"
+
+[cert-check.args.host]
+type        = "str"
+position    = 1
+description = "Hostname to connect to"
+
+[cert-check.args.port]
+type        = "int"
+short       = "-p"
+description = "TLS port"
+default     = 443
+
+[cert-check.args.warn-days]
+type        = "int"
+short       = "-w"
+description = "Report 'expiring' when fewer than N days remain"
+default     = 30
+
+[cert-check.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Connection timeout in seconds"
+default     = 10
+
+[cert-chain]
+serve       = ["local"]
+description = "Show the full TLS certificate chain (leaf -> intermediates -> root)"
+autonomy    = "autonomous"
+output      = "json"
+
+[cert-chain.args.host]
+type        = "str"
+position    = 1
+description = "Hostname to connect to"
+
+[cert-chain.args.port]
+type        = "int"
+short       = "-p"
+description = "TLS port"
+default     = 443
+
+[cert-chain.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Connection timeout in seconds"
+default     = 10
+
+[tls-info]
+serve       = ["local"]
+description = "Report the negotiated TLS protocol, cipher, and trust result for a host"
+autonomy    = "autonomous"
+output      = "json"
+
+[tls-info.args.host]
+type        = "str"
+position    = 1
+description = "Hostname to connect to"
+
+[tls-info.args.port]
+type        = "int"
+short       = "-p"
+description = "TLS port"
+default     = 443
+
+[tls-info.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Connection timeout in seconds"
+default     = 10
+
+[http-check]
+serve       = ["local"]
+description = "Probe an HTTP(S) URL — status code, response time, redirect target"
+autonomy    = "autonomous"
+output      = "json"
+
+[http-check.args.url]
+type        = "str"
+position    = 1
+description = "URL to request"
+
+[http-check.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Request timeout in seconds"
+default     = 10
+
+[http-check.args.expect-status]
+type        = "int"
+short       = "-e"
+description = "Exit non-zero unless the response status matches this code"
+required    = false
+
+[http-check.args.insecure]
+type        = "flag"
+short       = "-k"
+description = "Skip TLS certificate verification"
+default     = false
+
+[http-headers]
+serve       = ["local"]
+description = "Fetch an endpoint's response headers and flag missing security headers"
+autonomy    = "autonomous"
+output      = "json"
+
+[http-headers.args.url]
+type        = "str"
+position    = 1
+description = "URL to request"
+
+[http-headers.args.method]
+type        = "choice"
+options     = ["HEAD", "GET"]
+short       = "-m"
+description = "HTTP method to use for the header probe"
+default     = "HEAD"
+
+[http-headers.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Request timeout in seconds"
+default     = 10
+
+[http-headers.args.insecure]
+type        = "flag"
+short       = "-k"
+description = "Skip TLS certificate verification"
+default     = false
+
+[redirect-trace]
+serve       = ["local"]
+description = "Follow an HTTP redirect chain and list each hop with status and Location"
+autonomy    = "autonomous"
+output      = "json"
+
+[redirect-trace.args.url]
+type        = "str"
+position    = 1
+description = "URL to start from"
+
+[redirect-trace.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Per-request timeout in seconds"
+default     = 10
+
+[redirect-trace.args.max-hops]
+type        = "int"
+short       = "-n"
+description = "Maximum number of redirects to follow"
+default     = 10
+
+[redirect-trace.args.insecure]
+type        = "flag"
+short       = "-k"
+description = "Skip TLS certificate verification"
+default     = false
+
+[dns-lookup]
+serve       = ["local"]
+description = "Resolve a hostname (A/AAAA + canonical name), or reverse-resolve an IP"
+autonomy    = "autonomous"
+output      = "json"
+
+[dns-lookup.args.host]
+type        = "str"
+position    = 1
+description = "Hostname to resolve, or an IP address to reverse-resolve"
+
+[dns-lookup.args.reverse]
+type        = "flag"
+short       = "-r"
+description = "Also reverse-resolve (PTR) each resolved address"
+default     = false
+
+[api-spec]
+serve       = ["local"]
+description = "Summarise an OpenAPI/Swagger spec (URL or file) — operations, params, schemas — to help write/update runnables for an API"
+autonomy    = "autonomous"
+output      = "json"
+
+examples = [
+  {cmd = "api-spec https://api.internal/openapi.json",                       description = "Overview: info, servers, and every operation"},
+  {cmd = "api-spec https://api.internal/openapi.json --tag orders",          description = "Only operations tagged 'orders'"},
+  {cmd = "api-spec ./openapi.json --operation createOrder",                  description = "Full detail for one operation (params, body, responses)"},
+  {cmd = "api-spec ./openapi.json --path /orders --method post",            description = "Drill into an operation by path + method"},
+]
+
+[api-spec.args.source]
+type        = "str"
+position    = 1
+description = "OpenAPI/Swagger spec — an http(s) URL or a local file path (JSON always; YAML needs the pyyaml extra)"
+
+[api-spec.args.operation]
+type        = "str"
+short       = "-o"
+description = "operationId to describe in full (params, request body, responses)"
+required    = false
+
+[api-spec.args.path]
+type        = "str"
+description = "API path to describe in full (pair with --method); alternative to --operation"
+required    = false
+
+[api-spec.args.method]
+type        = "str"
+short       = "-X"
+description = "HTTP method for --path (e.g. get, post)"
+required    = false
+
+[api-spec.args.tag]
+type        = "str"
+description = "Overview only: limit to operations carrying this tag"
+required    = false
+
+[api-spec.args.match]
+type        = "str"
+description = "Overview only: limit to operations whose path contains this substring"
+required    = false
+
+[api-spec.args.timeout]
+type        = "int"
+short       = "-t"
+description = "Fetch timeout in seconds (URL sources)"
+default     = 15
+
+[api-spec.args.insecure]
+type        = "flag"
+short       = "-k"
+description = "Skip TLS certificate verification when fetching the spec"
+default     = false

runspec_linux-0.6.0/runspec_linux/webops.py

@@ -0,0 +1,148 @@
+"""Web/TLS runnables — thin cross-platform wrappers over runspec-webops-core.
+
+These probe remote HTTP(S)/TLS endpoints and resolve DNS using only the Python
+stdlib (via ``runspec-webops-core``), so they behave identically on Linux and
+Windows. All are read-only network probes (``autonomy = "autonomous"``).
+
+Exit codes follow the web-monitor convention so a caller can branch on them:
+``0`` success, ``1`` a reportable problem (expiring/expired cert, unexpected
+status), ``2`` the endpoint was unreachable.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import runspec as rs
+from runspec_webops_core import (
+    ConnectError,
+    ResolveError,
+    SpecError,
+    chain_report,
+    connect_peer,
+    describe_operation,
+    fetch_headers,
+    leaf_report,
+    load_document,
+    probe,
+    resolve,
+    summarize_spec,
+    trace_redirects,
+)
+
+
+def _emit(obj: object) -> None:
+    print(json.dumps(obj))
+
+
+def main_cert_check() -> None:
+    spec = rs.parse("cert-check")
+    host, port = spec.host.value, spec.port.value
+    try:
+        peer = connect_peer(host, port, spec.timeout.value)
+        report = leaf_report(peer, spec.warn_days.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "host": host, "port": port})
+        sys.exit(2)
+    _emit({"host": host, "port": port, **report})
+    if report["status"] != "ok":
+        sys.exit(1)
+
+
+def main_cert_chain() -> None:
+    spec = rs.parse("cert-chain")
+    host, port = spec.host.value, spec.port.value
+    try:
+        peer = connect_peer(host, port, spec.timeout.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "host": host, "port": port})
+        sys.exit(2)
+    _emit({"host": host, "port": port, "chain": chain_report(peer)})
+
+
+def main_tls_info() -> None:
+    spec = rs.parse("tls-info")
+    host, port = spec.host.value, spec.port.value
+    try:
+        peer = connect_peer(host, port, spec.timeout.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "host": host, "port": port})
+        sys.exit(2)
+    _emit(
+        {
+            "host": host,
+            "port": port,
+            "protocol": peer.protocol,
+            "cipher": peer.cipher_name,
+            "cipher_version": peer.cipher_version,
+            "authorized": peer.authorized,
+            "authorization_error": peer.authorization_error,
+        }
+    )
+
+
+def main_http_check() -> None:
+    spec = rs.parse("http-check")
+    url = spec.url.value
+    expect = spec.expect_status.value
+    try:
+        result = probe(url, spec.timeout.value, insecure=spec.insecure.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "url": url})
+        sys.exit(2)
+    _emit(result)
+    if expect is not None and result["status"] != expect:
+        sys.exit(1)
+
+
+def main_http_headers() -> None:
+    spec = rs.parse("http-headers")
+    url = spec.url.value
+    try:
+        result = fetch_headers(url, spec.timeout.value, method=spec.method.value, insecure=spec.insecure.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "url": url})
+        sys.exit(2)
+    _emit(result)
+
+
+def main_redirect_trace() -> None:
+    spec = rs.parse("redirect-trace")
+    url = spec.url.value
+    try:
+        result = trace_redirects(url, spec.timeout.value, max_hops=spec.max_hops.value, insecure=spec.insecure.value)
+    except ConnectError as e:
+        _emit({"error": str(e), "url": url})
+        sys.exit(2)
+    _emit(result)
+
+
+def main_dns_lookup() -> None:
+    spec = rs.parse("dns-lookup")
+    host = spec.host.value
+    try:
+        _emit(resolve(host, want_reverse=spec.reverse.value))
+    except ResolveError as e:
+        _emit({"error": str(e), "host": host})
+        sys.exit(1)
+
+
+def main_api_spec() -> None:
+    spec = rs.parse("api-spec")
+    source = spec.source.value
+    try:
+        doc = load_document(source, spec.timeout.value, insecure=spec.insecure.value)
+        if spec.operation.value or spec.path.value:
+            result: object = describe_operation(
+                doc,
+                operation_id=spec.operation.value or None,
+                path=spec.path.value or None,
+                method=spec.method.value or None,
+            )
+        else:
+            result = summarize_spec(doc, tag=spec.tag.value or None, path_filter=spec.match.value or None)
+    except SpecError as e:
+        _emit({"error": str(e), "source": source})
+        sys.exit(2)
+    _emit(result)

runspec_linux-0.6.0/tests/test_webops.py

@@ -0,0 +1,107 @@
+"""The webops runnables parse from runspec.toml and the wrappers emit JSON + exit codes."""
+
+import json
+from pathlib import Path
+
+import pytest
+import runspec as rs
+
+from runspec_linux import webops
+
+TOML = Path(__file__).resolve().parent.parent / "runspec_linux" / "runspec.toml"
+
+# Each new runnable plus a minimal valid argv (its required positional).
+WEBOPS_RUNNABLES = {
+    "cert-check": ["example.com"],
+    "cert-chain": ["example.com"],
+    "tls-info": ["example.com"],
+    "http-check": ["https://example.com"],
+    "http-headers": ["https://example.com"],
+    "redirect-trace": ["https://example.com"],
+    "dns-lookup": ["example.com"],
+    "api-spec": ["/tmp/spec.json"],
+}
+
+
+@pytest.mark.parametrize("name", list(WEBOPS_RUNNABLES))
+def test_runnable_is_defined(name: str) -> None:
+    spec = rs.parse(name, WEBOPS_RUNNABLES[name], config_path=TOML)
+    assert spec.runspec_runnable == name
+
+
+def test_cert_check_defaults_and_positional() -> None:
+    spec = rs.parse("cert-check", ["example.com"], config_path=TOML)
+    assert spec.host.value == "example.com"
+    assert spec.port.value == 443
+    assert spec.warn_days.value == 30
+    assert spec.timeout.value == 10
+
+
+def test_http_check_flags() -> None:
+    spec = rs.parse("http-check", ["https://x.test", "--expect-status", "200", "--insecure"], config_path=TOML)
+    assert spec.url.value == "https://x.test"
+    assert spec.expect_status.value == 200
+    assert spec.insecure.value is True
+
+
+def _fixed_parse(name: str, argv: list[str]):
+    """A real parse bound to a runnable + argv, for patching ``webops.rs.parse``."""
+    real = rs.parse
+    return lambda *_a, **_k: real(name, argv, config_path=TOML)
+
+
+def test_main_cert_check_problem_exits_1(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(webops.rs, "parse", _fixed_parse("cert-check", ["expired.test"]))
+    monkeypatch.setattr(webops, "connect_peer", lambda *a, **k: object())
+    monkeypatch.setattr(webops, "leaf_report", lambda *a, **k: {"status": "expired", "days_remaining": -3})
+    with pytest.raises(SystemExit) as exc:
+        webops.main_cert_check()
+    assert exc.value.code == 1
+    out = json.loads(capsys.readouterr().out)
+    assert out["host"] == "expired.test"
+    assert out["status"] == "expired"
+
+
+def test_main_cert_check_unreachable_exits_2(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(webops.rs, "parse", _fixed_parse("cert-check", ["down.test"]))
+
+    def boom(*_a, **_k):
+        raise webops.ConnectError("refused")
+
+    monkeypatch.setattr(webops, "connect_peer", boom)
+    with pytest.raises(SystemExit) as exc:
+        webops.main_cert_check()
+    assert exc.value.code == 2
+    out = json.loads(capsys.readouterr().out)
+    assert "error" in out
+
+
+def test_main_api_spec_overview(monkeypatch, capsys, tmp_path) -> None:
+    spec_file = tmp_path / "openapi.json"
+    spec_file.write_text(json.dumps({"openapi": "3.0.0", "info": {"title": "T", "version": "1"}, "paths": {"/x": {"get": {"operationId": "getX", "responses": {"200": {"description": "ok"}}}}}}))
+    monkeypatch.setattr(webops.rs, "parse", _fixed_parse("api-spec", [str(spec_file)]))
+    webops.main_api_spec()
+    out = json.loads(capsys.readouterr().out)
+    assert out["title"] == "T"
+    assert out["operations"][0]["operation_id"] == "getX"
+
+
+def test_main_api_spec_bad_source_exits_2(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(webops.rs, "parse", _fixed_parse("api-spec", ["/no/such/spec.json"]))
+    with pytest.raises(SystemExit) as exc:
+        webops.main_api_spec()
+    assert exc.value.code == 2
+    assert "error" in json.loads(capsys.readouterr().out)
+
+
+def test_main_dns_lookup_resolve_error_exits_1(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(webops.rs, "parse", _fixed_parse("dns-lookup", ["bad.invalid"]))
+
+    def boom(*_a, **_k):
+        raise webops.ResolveError("nxdomain")
+
+    monkeypatch.setattr(webops, "resolve", boom)
+    with pytest.raises(SystemExit) as exc:
+        webops.main_dns_lookup()
+    assert exc.value.code == 1
+    assert "error" in json.loads(capsys.readouterr().out)