237 lines
10 KiB
Python
237 lines
10 KiB
Python
"""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}")
|