This commit is contained in:
2026-11-15 17:41:40 +01:00
parent e31f6f0ca1
commit 7864d2ed18
13 changed files with 1530 additions and 0 deletions

View File

@@ -0,0 +1,236 @@
"""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=<json>, key=<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}")