Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Configurations, règles d'audit et modèles

La configuration comme un objet, règles d'audit, modèles.

Toutes les pages de documentation

Cette page présente ce qu'un programme peut faire d'une configuration d'équipement une fois qu'il en a une : la lire comme un objet, en comparer deux, la vérifier par rapport aux règles maison avec rule et audit, et écrire des lignes d'équipement à partir de modèles. Rien de tout cela ne modifie un équipement.

Exemples : audit_rules, backup_diff.

D'où vient une configuration

Appel Résultat
backup(d) La configuration en cours, lue sur l'équipement (voir devices.md)
load_config(path, platform="ios") Un fichier enregistré, comme une sauvegarde de nuit. Ne lit aucun équipement
Config(device, text, taken) Une configuration faite à partir d'un texte, comme dans un test
snapshot(d).config La configuration contenue dans un instantané
Bogolang
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
print(cfg.hostname, len(cfg.lines))

load_config nomme l'équipement d'après la ligne hostname du fichier, ou d'après le nom du fichier quand il n'y en a pas. Le mot platform décide de la façon dont le fichier est lu : junos lit les formes Junos (voir plus bas), tout autre mot lit les blocs par indentation, comme IOS, IOS-XE, ASA et NX-OS les écrivent. L'objet configuration fonctionne sur ios, iosxe, asa, nxos et junos ; sur aireos, il est refusé.

La configuration comme objet

Sur une Config Résultat
.text, .lines Le texte entier, et ses lignes
.hostname str, tiré de la ligne hostname
.find(start) list[str] : chaque ligne qui commence par ce texte, à n'importe quelle profondeur
.has(start) bool : existe-t-il une telle ligne
.section(start) list[Section] : chaque bloc dont la première ligne commence par ce texte
.interfaces list[InterfaceConfig] : un par bloc interface
.save(path) Écrit le texte dans un fichier
.warnings list[str] : ce qu'un lecteur de cette configuration doit savoir. Vide dans la plupart des cas

Une Section est un bloc : .line est sa première ligne, .lines les lignes en dessous, sans l'indentation propre au bloc, et elle a ses propres .find, .has et .section pour les blocs qu'elle contient.

Bogolang
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
for vty in cfg.section("line vty"):
    if vty.find("transport input") != ["transport input ssh"]:
        print(f"{vty.line}: {vty.lines}")
print(cfg.has("service password-encryption"))

Sur un fichier avec deux blocs line vty, dont le second autorise telnet, ceci affiche :

line vty 5 15: ['transport input ssh telnet']
True

Comment les lignes sont reconnues :

  • Une correspondance regarde le début d'une ligne, après les espaces du début. Les majuscules comptent telles qu'elles sont écrites.
  • find et section cherchent à toutes les profondeurs. cfg.section("address-family") trouve aussi les blocs sous router bgp.
  • Les lignes qui commencent par !, les lignes vides, et les deux lignes qu'IOS écrit en tête de show running-config ne sont pas du contenu.
  • Le texte d'une bannière est gardé sous sa ligne de bannière et n'est jamais fouillé, donc une bannière qui contient des lignes ressemblant à de la configuration ne donne pas de fausse correspondance.
  • Une interface n'est jamais lue comme faisant partie d'une autre interface, même là où IOS-XE en écrit une décalée d'un espace.

Interfaces

Une InterfaceConfig est une Section avec ces champs, lus une seule fois :

Champ Type Signification
.name Intf Gi1/0/1 et GigabitEthernet1/0/1 sont le même nom
.description str Vide quand il n'y en a pas
.shutdown bool
.address IfAddr ou None L'adresse IPv4 principale. Pas une secondary, pas dhcp
.mode str "access", "trunk", "routed" ou vide
.access_vlan int ou None
.trunk_vlans VlanSet ou None None quand il n'y a pas de ligne allowed vlan, ce qui sur IOS veut dire tous les VLAN. Les lignes add, remove et except sont suivies
Bogolang
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
for i in cfg.interfaces:
    if not i.shutdown and i.description == "":
        print(f"{i.name}: no description, mode {i.mode or 'not set'}")

Lu sur un petit fichier :

Gi1/0/1 'uplink to edge-rt1' False None 'trunk' None 10,20
Gi1/0/2 '' False None 'access' 10 None
Gi1/0/3 '' True None '' None None
Vl10 '' False 192.0.2.1/24 'routed' None None

(nom, description, shutdown, adresse, mode, VLAN d'accès, VLAN du trunk). Une interface dont le nom ne peut pas être lu est laissée hors de .interfaces ; cfg.section("interface ...") la trouve quand même. Une ligne d'une interface qui ne peut pas être lue laisse son champ vide.

diff

diff(a: Config, b: Config) -> ConfigDiff

diff compare deux configurations section par section. Un ConfigDiff a .removed et .added, chacun une liste de lignes écrites avec leur section devant : interface GigabitEthernet1/0/3 / shutdown. Une ligne qui a seulement changé de place, les lignes ! et le nombre d'octets en tête ne sont pas des changements. Il est faux quand rien n'a changé, et s'affiche sous forme de lignes - et +, ou No difference..

Bogolang
old: Config = load_config("backups/core-sw1.cfg", platform="iosxe")
new: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
changes: ConfigDiff = diff(old, new)
print(f"{len(changes.removed)} removed, {len(changes.added)} added")
print(changes)

La sortie de backup_diff se trouve sur devices.md.

Configurations Junos

Junos écrit sa configuration avec des accolades ou sous forme de lignes set. load_config(path, platform="junos") lit l'une ou l'autre forme et reconnaît de lui-même laquelle c'est. backup(d) sur Junos garde la forme avec accolades.

L'objet travaille sur des chemins : chaque instruction est un chemin de mots, comme dans la forme set sans le mot set. Une recherche peut commencer à n'importe quel niveau, et les mots sont comparés en entier.

Sur une Config Junos Résultat
.has("system services telnet") Existe-t-il une instruction dont le chemin commence par ces mots
.find("system services") Les instructions dont le chemin commence ainsi, sous forme de chemins complets
.section("interfaces ge-0/0/1") Les blocs à ce chemin, sous forme de Section
.hostname Tiré de system host-name
.set_lines Toute la configuration sous la forme set
.inactive Les instructions désactivées
.interfaces Une par interface et une par unité, comme ge-0/0/0.0
Bogolang
j: Config = load_config("edge-sw2.conf", platform="junos")
print(j.hostname, j.has("system services telnet"), j.inactive)

Sur un fichier avec set system services telnet et deactivate system services telnet, ceci affiche edge-sw2 False ['system services telnet'].

  • Une instruction désactivée n'est pas en vigueur. has, find et section la laissent de côté ; elle figure dans .inactive. Une règle d'audit ne réussit jamais sur une ligne que l'équipement ignore.
  • Les instructions sous groups sont des motifs, pas en vigueur : une recherche les laisse de côté, sauf si elle commence par le mot groups.
  • Groupes. Un fichier enregistré montre apply-groups mais pas ce dont l'équipement hérite. Quand un fichier l'utilise, .warnings dit que les instructions héritées ne sont pas comptées, et chaque ligne audit de cet équipement porte la même phrase. Un audit en direct lit show configuration | display inheritance no-comments, qui les montre.
  • Une ligne que le lecteur ne peut pas transformer en chemin l'arrête avec une erreur qui désigne la ligne par son numéro et ne montre jamais la ligne, car une configuration contient des secrets.
  • diff de deux configurations Junos compare leurs lignes set.
  • Sur les interfaces, .shutdown est vrai pour disable ; .mode vient de la famille de commutation, ou vaut "routed" quand l'unité a une adresse. Les VLAN désignés par leur nom sont retrouvés par le bloc vlans ; quand un nom n'est pas trouvé, .trunk_vlans est vide.

.set_lines et .inactive sur une configuration d'une autre plateforme sont refusés.

Règles d'audit

Une rule est une liste de tests, un par ligne, chacun vrai ou faux. audit(devices) exécute chaque règle sur chaque équipement qu'elle concerne et donne une ligne par équipement et par règle.

Bogolang
edition 2027


class HouseRules:
    rule "vty takes ssh only" for d:
        config.section("line vty") != []
        all(v.find("transport input") == ["transport input ssh"] for v in config.section("line vty"))

    rule "passwords are encrypted" for d:
        config.has("service password-encryption")

    rule "clock from ntp" for d where d.role != "lab":
        config.has("ntp server")  # every device but the lab ones

    @staticmethod
    def main(args: list[str]) -> None:
        devices: list[Device] = inventory("devices.csv")
        result: AuditResult = audit(devices, configs="configs")
        print(result)
        for row in result.failed:
            print(f"{row.device} fails '{row.rule}': {row.detail}")
  • Dans une règle, trois noms existent : l'équipement (d ici, le mot après for), config (sa configuration, lue une fois par équipement) et show(...), qui lit l'équipement en direct.
  • where dit quels équipements une règle concerne. Un where qui lève une erreur donne une ligne en échec pour cet équipement et cette règle.
  • Un équipement échoue à une règle dès son premier test faux. Ce test est le détail de la ligne.
  • Un test qui lève une erreur compte comme échoué, avec l'erreur comme détail. Il n'arrête pas l'audit.
  • Un commentaire en fin de ligne de test est permis et ne fait pas partie du détail.
  • Une règle ne contient pas de blocs : chaque test est écrit sur une seule ligne.
  • Une règle se place dans le corps d'une classe ou dans une méthode. Dans le corps d'une classe, un champ de la classe est atteint à travers la classe : HouseRules.servers.
  • Deux règles du même nom arrêtent le programme quand il s'exécute.

audit

audit(devices: list[Device], configs: str = '', parallel: int = 10) -> AuditResult
  • Avec configs="folder", chaque configuration est lue depuis folder/NAME.cfg et aucun équipement n'est contacté. Une règle qui appelle show échoue alors sur cet équipement, avec une phrase qui dit pourquoi. Un fichier manquant fait échouer toutes les règles de cet équipement.
  • Sans configs, chaque équipement est lu par SSH, jusqu'à parallel à la fois, avec les identifiants enregistrés par bogo login. Un équipement qui ne peut pas être lu échoue à toutes ses règles ; les autres continuent.
  • Un équipement dont la plateforme n'a pas d'objet configuration échoue à ses règles avec la phrase du tableau des plateformes.
Sur un AuditResult Résultat
.rows list[AuditRow], une par équipement et par règle, dans l'ordre des équipements
.failed Les lignes en échec
.passed Vrai quand aucune n'a échoué. bool(result) est identique
print(result) Un tableau, et une dernière ligne comme 2 of 3 failed

Un AuditRow a .device, .rule, .passed et .detail. table(result.failed, ["device", "rule", "detail"]) affiche les lignes en échec sous forme de tableau, comme le fait audit_rules :

bogo run audit_rules.bogo
device      rule                        detail
----------  --------------------------  ---------------------------------------------------------------
core-sw1    vty takes ssh only          all(AuditRules.ssh_only(v) for v in config.section("line vty"))
core-sw1    ports in use are described  AuditRules.undescribed(config) == []
access-sw2  vty takes ssh only          all(AuditRules.ssh_only(v) for v in config.section("line vty"))
access-sw2  passwords are encrypted     config.has("service password-encryption")
access-sw2  logs go to a server         config.has("logging host")
access-sw2  clock from ntp              config.has("ntp server")
access-sw2  ports in use are described  AuditRules.undescribed(config) == []

7 of 14 checks failed.
core-sw1: no description on Gi1/0/3
access-sw2: no description on Vl10

Modèles

Un modèle est un fichier texte de lignes d'équipement avec des trous écrits {name}, sous la même forme que dans un bloc change.

template(path: str) -> Template
Template.fill(d: Device, **values) -> str

Un fichier access-port.txt :

interface {port}
 description {what}
 switchport mode access
 switchport access vlan {vlan}
 snmp-server location {site}
Bogolang
t: Template = template("access-port.txt")
d: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe", site="north")
lines: str = t.fill(d, port=Intf("Gi1/0/7"), what="camera", vlan=30)
print(lines)
print(t.holes)
interface Gi1/0/7
 description camera
 switchport mode access
 switchport access vlan 30
 snmp-server location north
  • Un trou prend sa valeur d'abord dans les noms donnés à fill, puis dans l'équipement : name, ip, site, role, platform et chaque colonne supplémentaire de l'inventaire.
  • Une valeur peut être du texte, un nombre entier ou un type d'adresse (IP, Net, IfAddr, MAC, Intf, VlanSet). Un Secret ne peut pas remplir un trou.
  • Un trou sans valeur est une erreur qui nomme le trou et l'équipement :
ValueError: access-port.txt, line 4: the hole {vlan} has no value for device core-sw1. Give it as fill(d, vlan=...) or fill the 'vlan' column of the inventory.

Une cellule vide de l'inventaire compte comme une absence de valeur. Un texte vide donné exprès à fill est accepté. - Un trou est un simple nom. {vlan + 1} est refusé quand le fichier est lu : calculez la valeur en Bogolang et passez-la par son nom. Un modèle n'a ni boucles ni conditions. - {{ et }} sont de vraies accolades. Une } seule ou une { non fermée est refusée quand le fichier est lu, avec le numéro de ligne. - Les trous sont vérifiés quand le programme s'exécute, pas avant.

Un modèle rempli va dans un bloc change, seul sur sa ligne, et il est envoyé comme plusieurs lignes :

Bogolang
t: Template = template("access-port.txt")
for d in inventory("devices.csv"):
    change on d:
        apply:
            {t.fill(d, port=Intf("Gi1/0/7"), what="camera", vlan=30)}
        rollback:
            default interface Gi1/0/7
        verify:
            "camera" in show("interfaces Gi1/0/7 description")

Voir changes.md.

Non prouvé

L'objet configuration a lu 86 vrais fichiers de sauvegarde sans erreur, et cinq règles d'audit ont été exécutées sur les 78 équipements IOS et IOS-XE qui en font partie. Les mises en forme d'ASA, NX-OS et AireOS ont été laissées hors de cet essai. Le lecteur Junos a été essayé sur les configurations de commutateurs Junos virtuels seulement. Voir not-proven.md.