"""Minimal VyOS HTTP API client (Stream 2026.03 / rolling: service https api rest). Protocol (docs: automation/vyos-api.html): POST {base}/configure form fields: data=, key= POST {base}/retrieve {"op":"returnValues","path":[tokens]} -> {"returnValues":[...]} POST {base}/show {"op":"show","path":[...]} POST {base}/config-file {"op":"save"} GET {base}/info version/health, no auth Multipart/form-data encoding, exactly what curl -F sends. """ from __future__ import annotations import hashlib import json import logging import socket import ssl import time from typing import Any import requests from requests.adapters import HTTPAdapter from urllib3.connection import HTTPSConnection from urllib3.connectionpool import HTTPSConnectionPool log = logging.getLogger("leaf.vyos") class VyosApiError(RuntimeError): def __init__(self, msg: str, status: int | None = None, body: Any = None): super().__init__(msg) self.status = status self.body = body def normalize_pin(pin: str) -> str: """Accept openssl-style 'AA:BB:..' or plain hex; return lowercase hex digest.""" p = pin.strip().lower().removeprefix("sha256:").replace(":", "") if len(p) != 64 or any(c not in "0123456789abcdef" for c in p): raise ValueError("tls_cert_pin must be a sha256 certificate fingerprint (hex)") return p class PinMismatchError(VyosApiError): pass class _PinnedHTTPSConnection(HTTPSConnection): """TLS to an IP-hosted self-signed endpoint, anchored on a pinned cert. Hostname verification is impossible for this router's cert (CN=localhost, no IP SAN), so trust comes from comparing the peer's SHA-256 fingerprint against the configured pin. CERT_NONE is safe *because* the pin is the trust anchor: a mismatch aborts the connection before any request. """ leaf_pin: str | None = None def connect(self): ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) ctx.check_hostname = False ctx.verify_mode = ssl.CERT_NONE sock = socket.create_connection((self.host, self.port), self.timeout, self.source_address) self.sock = ctx.wrap_socket(sock, server_hostname=self.host) der = self.sock.getpeercert(binary_form=True) if der is None: raise PinMismatchError("TLS handshake returned no peer certificate") digest = hashlib.sha256(der).hexdigest() if digest != self.leaf_pin: self.sock.close() raise PinMismatchError( f"TLS cert fingerprint mismatch for {self.host}; peer is " f"{digest}, pinned is {self.leaf_pin} (possible MiTM?)") # Pin matched: this connection IS authenticated to the pinned anchor. self.is_verified = True return None class VyosClient: def __init__(self, url: str, key: str, ca_bundle: str | None = None, tls_verify: bool = True, timeout: float = 10.0, retries: int = 3, cert_pin: str | None = None): self.url = url.rstrip("/") self.key = key self.timeout = timeout self.retries = retries self.sess = requests.Session() # Do not bypass the pinned adapter through an environment HTTP proxy. self.sess.trust_env = False if cert_pin: pin = normalize_pin(cert_pin) class PinAdapter(HTTPAdapter): def init_poolmanager(self, *args, **kwargs): super().init_poolmanager(*args, **kwargs) conn_cls = type( "PinnedConn", (_PinnedHTTPSConnection,), {"leaf_pin": pin}) self.poolmanager.pool_classes_by_scheme = dict(self.poolmanager.pool_classes_by_scheme) self.poolmanager.pool_classes_by_scheme["https"] = type( "PinnedPool", (HTTPSConnectionPool,), {"ConnectionCls": conn_cls}) return self.poolmanager self.sess.mount("https://", PinAdapter()) elif ca_bundle: self.sess.verify = ca_bundle else: self.sess.verify = bool(tls_verify) if self.sess.verify is False: requests.packages.urllib3.disable_warnings() # explicit opt-in only # ------------------------------------------------------------------ core def _post(self, endpoint: str, payload: dict, auth: bool = True) -> dict: # multipart/form-data exactly like `curl -F "data=..." -F "key=..."`: # part tuples (None, value) -> no filename -> plain form field fields = {"data": (None, json.dumps(payload))} if auth: fields["key"] = (None, self.key) resp = self.sess.post(f"{self.url}{endpoint}", files=fields, timeout=self.timeout) try: body = resp.json() except ValueError: body = resp.text if resp.status_code >= 400: raise VyosApiError(f"{endpoint} -> HTTP {resp.status_code}: {body!r}", status=resp.status_code, body=body) # VyOS returns success:false + error for semantic failures (often 200/400) if isinstance(body, dict) and body.get("success") is False: raise VyosApiError(f"{endpoint} rejected: {body.get('error')!r}", status=resp.status_code, body=body) if not isinstance(body, dict) or body.get("success") is not True: raise VyosApiError(f"{endpoint}: missing success acknowledgement") return body # ------------------------------------------------------------- public API def info(self) -> dict: resp = self.sess.get(f"{self.url}/info", timeout=self.timeout) if resp.status_code >= 400: raise VyosApiError(f"/info -> HTTP {resp.status_code}", status=resp.status_code) body = resp.json() if isinstance(body, dict) and isinstance(body.get("data"), dict): return body["data"] return body def configure(self, ops: list[dict] | dict) -> dict: """One commit: a single op dict or a list of ops (atomic multi-op).""" payload = ops if isinstance(ops, list) else ops return self._post("/configure", payload) def retrieve(self, op: str, path: list[str]) -> dict: return self._post("/retrieve", {"op": op, "path": path}) def group_members(self, group: str) -> list[str]: body = self.retrieve("returnValues", ["firewall", "group", "address-group", group, "address"]) # live 2026.03 returns {"success":true,"data":[...]}; older builds used # {"returnValues":[...]}. Accept both, never silently hide members. vals = body.get("data") if vals is None: if "returnValues" not in body and "data" not in body: raise VyosApiError("group member response contains no values field") vals = body.get("returnValues") or [] if not isinstance(vals, list): vals = [vals] if vals else [] return [str(v) for v in vals] @staticmethod def member_op(op, group, ip): import ipaddress ipaddress.IPv4Address(ip) # This prototype manages IPv4 address groups only. return {"op": op, "path": ["firewall", "group", "address-group", group, "address", ip]} def set_group_member(self, group: str, ip: str) -> dict: return self.configure(self.member_op("set", group, ip)) def del_group_member(self, group: str, ip: str) -> dict: return self.configure(self.member_op("delete", group, ip)) def verify_enforcement(self, group, require_src=False): fw = self.retrieve("showConfig", ["firewall"]).get("data", {}) if not isinstance(fw, dict): raise VyosApiError("cannot inspect firewall enforcement hooks") directions = set() def walk(obj): if not isinstance(obj, dict): return if obj.get("action") == "drop": for side in ("source", "destination"): if obj.get(side, {}).get("group", {}).get("address-group") == group: directions.add(side) for value in obj.values(): if isinstance(value, dict): walk(value) ipv4 = fw.get("ipv4", {}) walk(ipv4.get("forward", {})) attached = set() def attachments(obj): if not isinstance(obj, dict): return hook = obj.get("firewall", {}) if isinstance(hook, dict) and isinstance(hook.get("name"), str): attached.add(hook["name"]) for value in obj.values(): if isinstance(value, dict): attachments(value) attachments(fw.get("zone", {})) for name in attached: walk(ipv4.get("name", {}).get(name, {})) required = {"destination", "source"} if require_src else {"destination"} if not required <= directions: raise VyosApiError("missing drop hooks for " + ", ".join(sorted(required - directions))) def show(self, command: list[str]) -> str: body = self._post("/show", {"op": "show", "path": command}) out = body.get("output") if out is None: out = body.get("data", "") return str(out) def save_config(self) -> dict: return self._post("/config-file", {"op": "save"}) # ----------------------------------------------------- retrying operations def op_with_retry(self, fn, *args, **kwargs) -> Any: last: Exception | None = None for attempt in range(1, self.retries + 1): try: return fn(*args, **kwargs) except (requests.RequestException, VyosApiError) as exc: last = exc wait = min(2 ** attempt, 30) log.warning("vyos op failed (attempt %d/%d): %s — retry in %ss", attempt, self.retries, exc, wait) time.sleep(wait) raise VyosApiError(f"vyos op failed after {self.retries} attempts: {last}")