Files
napalm-opnsense/tests/unit/test_config_revisions.py
T
Christian Manivong a65a3ed6e3
driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 15s
driver / types (pull_request) Successful in 1m0s
driver / test (3.12) (pull_request) Successful in 1m11s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 35s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 1m1s
CI / driver (pull_request) Successful in 2m44s
driver / publish (pull_request) Skipped
refactor(config): take the revision contract from napalm-device-types
napalm-device-types 4.38.0 declares ConfigRevisionsMixin: the listing,
the reading, ConfigRevisionDict and the exceptions, and the revert as a
template. The driver keeps the device communication: the three backup
API calls, the revert step, and config_revision_content(), which leaves
out the <revision> block every save writes into config.xml and the
indentation between elements.

The template reads the newest revision after the revert and checks that
it holds the revision's configuration. OPNsense answers "reverted" even
when restoreBackup() could not load the file and kept the previous one;
that now raises ConfigRevertFailed instead of passing. A refusal of the
firewall raises ConfigRevertFailed too. An id the history does not list
still never reaches a request path.

Refs NetOrk/netork#2511
2026-11-13 22:33:58 +01:00

416 lines
16 KiB
Python

"""The firewall's own configuration history: list it, read a revision, revert to one.
NetOrk/netork#2511: OPNsense has no API that takes an uploaded config.xml, so an
application restores a configuration by finding the revision in the firewall's own
history whose content it wants and reverting to that one.
``core_backup_backups_this.json`` has the shape ``/api/core/backup/backups/this`` answers
with on 24.7 up to 26.7 and ``master`` (``OPNsense\\Core\\Api\\BackupController``):
newest first, ``time`` the revision's unix time with two decimals, ``time_iso`` the same
in the firewall's own zone (here +01:00), ``id`` the file name in ``/conf/backup``. The
values are made up; the oldest is a revision without description and user, as the
first configuration of a new install is.
"""
from __future__ import annotations
import copy
import json
from pathlib import Path
from unittest.mock import MagicMock, patch
from xml.etree.ElementTree import ParseError
import pytest
import requests
from napalm_device_types import ConfigRevertFailed, ConfigRevisionsMixin, UnknownConfigRevision
from napalm_opnsense.opnsense import OPNsenseDriver
FIXTURES = Path(__file__).parent / "fixtures"
HISTORY = json.loads((FIXTURES / "core_backup_backups_this.json").read_text())
CONFIG_XML = (FIXTURES / "config_xml_sample.xml").read_text()
HISTORY_PATH = "/api/core/backup/backups/this"
NEWEST = "config-1794603885.1239.xml"
OLDEST = "config-1793516400.0012.xml"
WITH_SUFFIX = "config-1794475810.0548_123456789.xml"
#: The id of the revision a revert saves, as the fake firewall names it.
REVERTED = "config-1794700000.0001.xml"
def _stamped(config: str, user: str, time: str) -> str:
"""*config* with the <revision> block every save writes into config.xml."""
block = (
f" <revision>\n <username>{user}</username>\n <time>{time}</time>\n"
" <description>/api/core/backup/revert_backup made changes</description>\n"
" </revision>\n"
)
return config.replace("</opnsense>", block + "</opnsense>")
#: The oldest revision is the sample; every later one names the host otherwise.
FILES = {
OLDEST: _stamped(CONFIG_XML, "root@192.0.2.20", "1793516400.00"),
WITH_SUFFIX: _stamped(CONFIG_XML, "apiuser@192.0.2.10", "1794475810.05"),
"config-1794603482.8721.xml": _stamped(
CONFIG_XML.replace("<hostname>OPNsense</hostname>", "<hostname>gw</hostname>"),
"root@192.0.2.20",
"1794603482.87",
),
NEWEST: _stamped(
CONFIG_XML.replace("<hostname>OPNsense</hostname>", "<hostname>gw1</hostname>"),
"apiuser@192.0.2.10",
"1794603885.12",
),
}
class Firewall:
"""Answers as the firewall's backup API would; every request is recorded.
A revert it takes saves the revision as a new newest one, restamped; one it does
not take (``takes=False``) still answers "reverted", as OPNsense does when it falls
back to the previous file.
"""
def __init__(self, history=HISTORY, files=None, revert_answer=None, takes=True):
self.history = copy.deepcopy(history)
self.files = dict(FILES if files is None else files)
self.revert_answer = revert_answer or {"status": "reverted"}
self.takes = takes
self.requests: list[tuple[str, str]] = []
def get(self, url, timeout=None):
path = url.removeprefix("https://fw")
self.requests.append(("GET", path))
response = MagicMock()
response.raise_for_status.return_value = None
if path == HISTORY_PATH:
if isinstance(self.history, Exception):
response.raise_for_status.side_effect = self.history
response.json.return_value = self.history
return response
prefix = "/api/core/backup/download/this/"
if path.startswith(prefix):
# BackupController::downloadAction sends nothing for a name it has no file for.
response.text = self.files.get(path.removeprefix(prefix), "")
response.json.side_effect = json.JSONDecodeError("Expecting value", "<", 0)
return response
raise AssertionError(f"unexpected GET {path}")
def post(self, url, json=None, timeout=None):
path = url.removeprefix("https://fw")
self.requests.append(("POST", path))
response = MagicMock()
response.raise_for_status.return_value = None
if isinstance(self.revert_answer, Exception):
response.raise_for_status.side_effect = self.revert_answer
elif self.revert_answer.get("status") == "reverted" and self.takes:
self._save(path.rsplit("/", 1)[1])
response.json.return_value = self.revert_answer
return response
def _save(self, revision_id):
body = self.files[revision_id].split(" <revision>")[0] + "</opnsense>\n"
self.files[REVERTED] = _stamped(body, "apiuser@192.0.2.10", "1794700000.00")
item = {"time": "1794700000.00", "description": "", "username": "", "id": REVERTED}
self.history["items"].insert(0, item)
@property
def posts(self) -> list[str]:
return [path for method, path in self.requests if method == "POST"]
@pytest.fixture
def driver():
with patch("napalm_opnsense.opnsense.requests.Session"):
drv = OPNsenseDriver(
hostname="fw", username="k", password="s", optional_args={"verify": False}
)
drv.session = MagicMock()
yield drv
def _on(driver, firewall: Firewall) -> Firewall:
driver.session.get.side_effect = firewall.get
driver.session.post.side_effect = firewall.post
return firewall
class TestGetConfigRevisions:
def test_every_revision_newest_first(self, driver):
_on(driver, Firewall())
revisions = driver.get_config_revisions()
assert [r["id"] for r in revisions] == [
NEWEST,
"config-1794603482.8721.xml",
WITH_SUFFIX,
OLDEST,
]
def test_a_revision_as_the_firewall_describes_it(self, driver):
_on(driver, Firewall())
assert driver.get_config_revisions()[0] == {
"id": NEWEST,
"time": "2026-11-13T21:04:45+00:00",
"description": "/api/firewall/filter/apply made changes",
"user": "apiuser@192.0.2.10",
"size": 58213,
}
def test_the_time_is_utc_whatever_zone_the_firewall_runs_in(self, driver):
# time_iso is in the firewall's zone (+01:00 here); time is unix seconds.
_on(driver, Firewall())
times = [r["time"] for r in driver.get_config_revisions()]
assert times == [
"2026-11-13T21:04:45+00:00",
"2026-11-13T20:58:02+00:00",
"2026-11-12T09:30:10+00:00",
"2026-11-01T07:00:00+00:00",
]
def test_no_description_and_no_user_are_none(self, driver):
_on(driver, Firewall())
oldest = driver.get_config_revisions()[-1]
assert (oldest["description"], oldest["user"]) == (None, None)
def test_newest_first_even_when_the_answer_is_not_sorted(self, driver):
items = list(reversed(HISTORY["items"]))
_on(driver, Firewall(history={"items": items}))
assert driver.get_config_revisions()[0]["id"] == NEWEST
def test_without_a_time_the_file_name_tells_it(self, driver):
item = {"id": OLDEST, "description": "", "username": "", "filesize": 1}
_on(driver, Firewall(history={"items": [item]}))
assert driver.get_config_revisions()[0]["time"] == "2026-11-01T07:00:00+00:00"
def test_a_time_and_size_of_another_shape_are_none(self, driver):
item = {"id": "config-1.xml", "time": "soon", "filesize": "big", "description": 7}
_on(driver, Firewall(history={"items": [item, "noise"]}))
assert driver.get_config_revisions() == [
{
"id": "config-1.xml",
"time": "1970-01-01T00:00:01+00:00",
"description": None,
"user": None,
"size": None,
}
]
def test_an_entry_without_a_usable_id_is_left_out(self, driver):
# Nothing could read or revert it: the id goes into the request path.
items = [
{"id": "../config.xml", "time": "1"},
{"id": "config-1/../../x.xml", "time": "1"},
{"time": "1"},
HISTORY["items"][0],
]
_on(driver, Firewall(history={"items": items}))
assert [r["id"] for r in driver.get_config_revisions()] == [NEWEST]
def test_no_history_is_an_empty_list(self, driver):
_on(driver, Firewall(history={"items": []}))
assert driver.get_config_revisions() == []
def test_a_failed_read_raises(self, driver):
_on(driver, Firewall(history=requests.HTTPError("403 Forbidden")))
with pytest.raises(requests.HTTPError, match="403"):
driver.get_config_revisions()
@pytest.mark.parametrize("answer", [[], {"items": "x"}, {}], ids=["list", "items", "empty"])
def test_an_answer_of_another_shape_raises(self, driver, answer):
# "No history" would be a reading; this is none.
_on(driver, Firewall(history=answer))
with pytest.raises(ValueError, match="history"):
driver.get_config_revisions()
def test_a_reading_only_reads(self, driver):
firewall = _on(driver, Firewall())
driver.get_config_revisions()
assert firewall.requests == [("GET", HISTORY_PATH)]
class TestGetConfigRevision:
def test_the_revisions_config_xml(self, driver):
firewall = _on(driver, Firewall())
assert driver.get_config_revision(OLDEST) == FILES[OLDEST]
assert firewall.requests == [("GET", f"/api/core/backup/download/this/{OLDEST}")]
def test_a_revision_the_firewall_has_no_file_for_raises(self, driver):
# Rotated out of the history: the download answers with nothing.
_on(driver, Firewall(files={}))
with pytest.raises(UnknownConfigRevision, match=OLDEST):
driver.get_config_revision(OLDEST)
@pytest.mark.parametrize(
"revision_id",
["", "config.xml", "../config.xml", "config-1/../../x.xml", "config-1.xml?x=1", None],
)
def test_an_id_that_names_no_revision_is_refused_before_any_request(self, driver, revision_id):
firewall = _on(driver, Firewall())
with pytest.raises(UnknownConfigRevision):
driver.get_config_revision(revision_id)
assert firewall.requests == []
def test_a_failed_read_raises(self, driver):
resp = MagicMock()
resp.raise_for_status.side_effect = requests.HTTPError("403 Forbidden")
driver.session.get.return_value = resp
with pytest.raises(requests.HTTPError, match="403"):
driver.get_config_revision(OLDEST)
class TestRevertConfigRevision:
def test_reverts_through_the_backup_api_and_checks_the_result(self, driver):
firewall = _on(driver, Firewall())
now = driver.revert_config_revision(OLDEST)
assert now["id"] == REVERTED
assert firewall.requests == [
("GET", HISTORY_PATH),
("GET", f"/api/core/backup/download/this/{OLDEST}"),
("POST", f"/api/core/backup/revert_backup/{OLDEST}"),
("GET", HISTORY_PATH),
("GET", f"/api/core/backup/download/this/{REVERTED}"),
]
def test_an_id_with_the_suffix_of_a_fast_save(self, driver):
firewall = _on(driver, Firewall())
driver.revert_config_revision(WITH_SUFFIX)
assert firewall.posts == [f"/api/core/backup/revert_backup/{WITH_SUFFIX}"]
def test_a_revert_the_firewall_did_not_take_fails(self, driver):
# restoreBackup() falls back to the previous file and the answer is "reverted".
_on(driver, Firewall(takes=False))
with pytest.raises(ConfigRevertFailed, match=OLDEST):
driver.revert_config_revision(OLDEST)
def test_a_revision_not_in_the_history_is_refused(self, driver):
firewall = _on(driver, Firewall())
with pytest.raises(UnknownConfigRevision, match="config-1000000000.5.xml"):
driver.revert_config_revision("config-1000000000.5.xml")
assert firewall.posts == []
@pytest.mark.parametrize("revision_id", ["", "../config.xml", "config-1.xml/x", None])
def test_an_id_that_names_no_revision_never_reaches_a_request_path(self, driver, revision_id):
firewall = _on(driver, Firewall())
with pytest.raises(UnknownConfigRevision):
driver.revert_config_revision(revision_id)
assert firewall.requests == [("GET", HISTORY_PATH)]
def test_a_history_that_cannot_be_read_reverts_nothing(self, driver):
firewall = _on(driver, Firewall(history=requests.HTTPError("403 Forbidden")))
with pytest.raises(requests.HTTPError):
driver.revert_config_revision(OLDEST)
assert firewall.posts == []
def test_a_revision_gone_by_the_time_of_the_revert_is_unknown(self, driver):
_on(driver, Firewall(revert_answer={"status": "not_found"}))
with pytest.raises(UnknownConfigRevision, match=OLDEST):
driver.revert_config_revision(OLDEST)
def test_a_key_that_may_not_write_is_refused_with_the_firewalls_reason(self, driver):
# user-config-readonly: throwReadOnly() answers with an errorMessage.
reason = "User apiuser denied for write access (user-config-readonly set)"
_on(driver, Firewall(revert_answer={"errorMessage": reason, "errorTitle": "Error"}))
with pytest.raises(ConfigRevertFailed, match="user-config-readonly"):
driver.revert_config_revision(OLDEST)
def test_any_other_answer_is_a_failed_revert(self, driver):
_on(driver, Firewall(revert_answer={"status": "failed"}))
with pytest.raises(ConfigRevertFailed, match="failed"):
driver.revert_config_revision(OLDEST)
def test_an_http_error_raises(self, driver):
_on(driver, Firewall(revert_answer=requests.HTTPError("500 Server Error")))
with pytest.raises(requests.HTTPError, match="500"):
driver.revert_config_revision(OLDEST)
class TestConfigRevisionContent:
def test_the_revision_block_does_not_count(self, driver):
# Same configuration, saved by someone else at another time.
assert driver.config_revision_content(FILES[OLDEST]) == driver.config_revision_content(
FILES[WITH_SUFFIX]
)
def test_a_changed_setting_counts(self, driver):
assert driver.config_revision_content(FILES[OLDEST]) != driver.config_revision_content(
FILES[NEWEST]
)
def test_a_configuration_without_a_revision_block(self, driver):
stamped = driver.config_revision_content(FILES[OLDEST])
assert driver.config_revision_content(CONFIG_XML) == stamped
def test_a_revision_element_deeper_down_counts(self, driver):
# Only the root's <revision> is the save's stamp.
deeper = CONFIG_XML.replace("<theme>", "<theme><revision>7</revision>", 1)
assert driver.config_revision_content(deeper) != driver.config_revision_content(CONFIG_XML)
def test_how_the_xml_is_written_does_not_count(self, driver):
# Attribute order, quotes and empty elements are no difference of the configuration.
a = '<?xml version="1.0"?>\n<opnsense><x a="1" b="2"></x></opnsense>'
b = "<opnsense><x b='2' a='1'/></opnsense>"
assert driver.config_revision_content(a) == driver.config_revision_content(b)
def test_the_blanks_of_a_value_count(self, driver):
padded = CONFIG_XML.replace("<theme>opnsense</theme>", "<theme>opnsense </theme>")
assert driver.config_revision_content(padded) != driver.config_revision_content(CONFIG_XML)
def test_text_that_is_no_xml_raises(self, driver):
with pytest.raises(ParseError):
driver.config_revision_content("<html><body>Login")
class TestWhatTheDriverOffers:
def test_it_keeps_the_contract_of_device_types(self):
assert issubclass(OPNsenseDriver, ConfigRevisionsMixin)
def test_it_reads_and_reverts_revisions(self):
for name in ("get_config_revisions", "get_config_revision", "revert_config_revision"):
assert callable(getattr(OPNsenseDriver, name, None)), name
def test_it_replaces_no_configuration(self):
# No API takes an uploaded config.xml: an application asks for this and gets no.
assert getattr(OPNsenseDriver, "load_replace_candidate", None) is None