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

API et autres plateformes

API web, Meraki, RESTCONF, la console série, le tableau des plateformes.

Toutes les pages de documentation

Cette page couvre les façons de lire de Bogolang autres que SSH : les API web, Meraki, RESTCONF, la console série et un inventaire tiré d'une API. Elle couvre aussi la seule chose que Bogolang publie (webhook), les cinq vérifications de service et la lecture des fichiers de capture.

Tout ici ne fait que lire, sauf webhook. Un changement sur un équipement reste dans un bloc change sur SSH ou sur la console (voir changements). Chaque appel fonctionne sur des réponses enregistrées avec bogo run --replay FOLDER et est une ligne du journal d'exécution (voir les outils).

Jetons enregistrés

Un jeton ou une clé d'API n'est jamais écrit dans un programme. Il est enregistré une fois, sous un nom, dans le magasin protégé du système d'exploitation :

bogo login --api nms
bogo logout --api nms

Un programme donne le nom, token="nms", jamais la valeur. Un nom est fait de lettres, de chiffres, de points, de tirets et de tirets bas. Un programme qui nomme un jeton non enregistré s'arrête avec : No token is stored under the name 'nms'. Store it first with: bogo login --api nms. Dans une relecture, aucun jeton n'est lu.

http_get

Commande Donne
http_get(url: str, token: str = '', params: dict[str, str] \| None = None, verify: bool = True, timeout: Duration = 10s) Reply
  • Seule la lecture existe : chaque requête est un GET. Il n'y a pas de http_post.
  • Le jeton est envoyé comme Authorization: Bearer.
  • Un jeton ne part jamais vers un autre hôte. Une redirection n'est suivie que vers le même hôte, le même port et le même schéma. Toute autre est refusée, et l'autre hôte n'est jamais contacté.
  • Un jeton est masqué en *** dans les erreurs et dans les fichiers de relecture enregistrés, même quand le serveur le répète dans sa réponse.
  • Les params sont ajoutés à l'adresse sous forme de requête.
  • verify=False accepte un certificat auquel l'ordinateur ne fait pas confiance, pour un serveur qui a signé le sien lui-même. Bogolang le signale alors sur la sortie d'erreur standard, une fois par hôte.
  • Une réponse de 400 ou plus arrête le programme avec le statut et une indication (401 : le jeton manque ou n'est pas accepté ; 403 : non autorisé ; 404 : rien à cet endroit ; 429 : trop de requêtes).

Reply

Membre Donne
.status int
.text str, la réponse telle qu'elle est arrivée
.url str
.headers dict[str, str], noms en minuscules
.data() object, la réponse lue comme JSON
.rows(key: str = '') list[Row], quand la réponse est une liste JSON d'objets ; key nomme la liste quand elle se trouve dans un objet
.value(path: str) str, une valeur du JSON, le chemin écrit a.b.0.c

Une valeur dans une ligne est du texte. Un nombre entier écrit 20.0 se lit 20. Une liste ou un objet dans une ligne est gardé sous forme de son texte JSON. Un nom d'un modèle de données qui contient un point ne peut pas être atteint avec .rows() ou .value() ; les deux-points et les tirets fonctionnent.

Bogolang
r: Reply = http_get("https://nms.example.com/api/v1/devices", token="nms")
print(r)
print(r.status, r.value("count"), r.value("items.0.hostname"))
table(r.rows("items"), ["hostname", "ip", "device_type"])

Lancé avec --replay sur une réponse enregistrée :

Reply(200, 350 characters, https://nms.example.com/api/v1/devices)
200 3 core-sw1
hostname  ip            device_type
--------  ------------  -----------
core-sw1  192.0.2.1     cisco_xe
edge-fw1  192.0.2.3     cisco_asa
dist-sw9  198.51.100.9  acme_os

Dans une relecture, chaque réponse est lue dans FOLDER/web/NAME.json. Une exécution avec --save-replay FOLDER écrit ces fichiers. Un fichier manquant arrête le programme et nomme le fichier dont il a besoin.

webhook

Commande Fait
webhook(name: str, text: str) publie un texte vers le webhook enregistré sous ce nom
bogo login --webhook noc
bogo logout --webhook noc
  • L'adresse d'un webhook est un secret : quiconque la possède peut publier. Elle est donc enregistrée une fois, et un programme n'en garde que le nom. L'adresse n'est jamais affichée, ni dans une erreur, ni dans le journal d'exécution, ni dans la sortie.
  • L'adresse doit commencer par https://.
  • Le texte est publié en JSON, {"text": "..."}. Slack, Mattermost, Google Chat et les workflows Teams lisent cette forme.
  • Aucune redirection n'est suivie. Une réponse de 300 ou plus est une erreur. Le délai maximal est de 10 secondes.
  • Une publication quitte l'ordinateur et ne peut pas être reprise.
  • Avec bogo run --dry, le texte est affiché et pas envoyé :
DRY RUN: webhook noc would post this text. Nothing is sent.
dist-sw9 has a platform Bogolang does not know

Sous --replay, rien n'est publié non plus. Chaque vraie publication est une ligne du journal d'exécution : le nom, et si elle est partie. Aucun webhook n'a été publié vers un vrai service. Voir surveiller et écouter pour webhook dans alert when.

Meraki

Commande Donne
meraki(org: str = '', token: str = 'meraki') MerakiSession
  • org est le nom ou le numéro de l'organisation. Il peut être omis quand la clé n'en voit qu'une. Un nom qui ne correspond à aucune, ou à plus d'une, est une erreur qui liste les organisations que la clé voit.
  • token est le nom de la clé d'API enregistrée : bogo login --api meraki.
Membre Donne
.organizations() list[Row]
.networks() list[Row], de l'organisation
.devices() list[Row], de l'organisation
.uplinks() list[Row], une ligne par liaison montante de chaque appliance, avec les valeurs de l'appliance à côté
.get(path: str, **params: str) Reply, toute autre lecture de l'API Dashboard : une requête, sans pagination ; path commence par /
.org_id, .org_name str
  • Les longues listes sont récupérées page par page sans que le programme le demande. La page suivante n'est suivie que sur l'hôte d'API propre à Meraki.
  • Quand Meraki répond « trop de requêtes », Bogolang attend le temps que Meraki indique, au plus 60 secondes, et redemande, jusqu'à 5 fois.
  • Seule la lecture existe. Le journal d'exécution nomme l'équipement meraki.
  • Un nom de colonne avec des majuscules peut être lu avec un point : row.publicIp, d.networkId.

L'exemple meraki_inventory liste les équipements d'une organisation et ceux qui ne sont pas sur un firmware voulu :

```bogo skip m = meraki(org=MerakiInventory.org) networks = {n.id: n.name for n in m.networks()} devices = m.devices() print(f"{m.org_name} ({m.org_id}): {len(networks)} networks, {len(devices)} devices") table(devices, ["name", "model", "serial", "lanIp", "firmware"])


Sur ses réponses enregistrées :

Example Org (500100): 2 networks, 6 devices

name model serial lanIp firmware


hq-mx1 MX85 Q2EX-AMPL-0001 192.0.2.1 MX 18.211.2 hq-ms1 MS225-48LP Q2EX-AMPL-0002 192.0.2.2 MS 17.1.4 hq-mr1 MR46 Q2EX-AMPL-0003 192.0.2.11 MR 31.1.6 hq-mr2 MR46 Q2EX-AMPL-0004 192.0.2.12 MR 30.7 north-mx1 MX68 Q2EX-AMPL-0005 198.51.100.1 MX 18.107.10 north-mr1 MR36 Q2EX-AMPL-0006 198.51.100.11 MR 31.1.6


## RESTCONF

| Commande | Donne |
|---|---|
| `restconf(d: Device, verify: bool = True)` | `RestSession` ; rien n'est encore envoyé |
| `RestSession.get(path: str)` | `Reply` : un GET de `https://DEVICE/restconf/data/PATH` |

- Il fonctionne sur les plateformes `iosxe` et `nxos`. `ios`, que reçoit une ligne d'inventaire
  qui ne nomme aucune plateforme, est refusé : un équipement IOS-XE a besoin de `platform=iosxe`.
- Il utilise les identifiants enregistrés de l'équipement (`bogo login`), sur HTTPS, lus à la
  première requête.
- `path` s'écrit comme dans le modèle de données de l'équipement, par exemple
  `"ietf-interfaces:interfaces"`. Il est envoyé tel qu'il est écrit. Les options de requête ne
  sont pas dans cette version.
- Une erreur dit quoi faire : un certificat auquel l'ordinateur ne fait pas confiance (utilisez
  `verify=False` pour un équipement qui a signé le sien lui-même), RESTCONF désactivé (sur IOS-XE
  `restconf` et `ip http secure-server`, sur NX-OS `feature restconf`), des identifiants refusés.
- NETCONF n'est pas dans cette version.

```bogo
r1: Device = Device(name="edge-rt1", ip=192.0.2.254, platform="iosxe")
s: RestSession = restconf(r1)
ifaces: Reply = s.get("ietf-interfaces:interfaces")
print(ifaces.status)

RESTCONF n'a jamais lu un vrai équipement. Voir non prouvé.

La console série

Commande Donne
serial(port_name: str, speed: int = 9600, platform: str = 'ios', login: str = 'default') Session
  • La session est la même qu'une session SSH : en lecture seule, avec .show et .run, et utilisable dans change on s: (voir équipements et changements).
  • Elle fonctionne sur IOS et IOS-XE.
  • Une console qui ne demande pas d'identifiants fonctionne : sans identifiants enregistrés pour le profil, l'utilisateur et le mot de passe sont vides et rien n'est demandé au clavier.
  • L'équipement est nommé d'après le port : COM3, ou ttyUSB0 pour /dev/ttyUSB0. Dans une relecture, les sorties enregistrées sont dans un dossier de ce nom.
  • La touche break, ROMMON et la récupération de mot de passe ne sont pas dans cette version.
Bogolang
s: Session = serial("COM3", speed=9600, platform="iosxe")
print(s.show("show version").text)
s.close()

La console série n'a jamais été essayée sur un vrai port. Voir non prouvé.

Un inventaire tiré d'une API

Commande Donne
inventory_api(url: str, token: str = '', fields: dict[str, str] \| None = None, verify: bool = True) list[Device]
  • L'API doit répondre par une liste JSON d'objets, ou par un objet qui contient une liste d'objets.
  • fields associe un champ Bogolang (name, ip, platform, site, role) au nom que l'API lui donne. Sans lui, Bogolang cherche name ou hostname, ip, ip_address ou address, et platform, site, role.
  • Toutes les autres valeurs vont dans d.extra.
  • Les mots de plateforme habituels des autres outils sont compris : cisco_ios, cisco_xe, cisco_asa, cisco_nxos, cisco_wlc_ssh, ios-xe, nx-os. Le mot propre à l'API est alors gardé dans d.extra["api_platform"].
  • Un mot que Bogolang ne connaît pas n'arrête pas la liste. Cet équipement reçoit la plateforme ios, avec le mot de l'API dans d.extra["api_platform"]. Vérifiez la plateforme d'un équipement avant de lancer des commandes dessus.
  • Le délai maximal est de 30 secondes.
Bogolang
devices: list[Device] = inventory_api("https://nms.example.com/api/v1/devices", token="nms",
                                      fields={"name": "hostname", "platform": "device_type"})
for d in devices:
    print(d.name, d.ip, d.platform, d.site, d.extra)

Sur la même réponse enregistrée que pour http_get ci-dessus :

core-sw1 192.0.2.1 iosxe hq {'serial': 'FOC0001', 'api_platform': 'cisco_xe'}
edge-fw1 192.0.2.3 asa hq {'serial': 'JAD0002', 'api_platform': 'cisco_asa'}
dist-sw9 198.51.100.9 ios north {'serial': 'XYZ0003', 'api_platform': 'acme_os'}

dist-sw9 a un mot qu'aucune règle ne connaît, il est donc devenu ios. Les sources sous forme de fichier (.csv, .xlsx, .yaml) sont lues par inventory(path), sur la page des équipements.

Vérifications de service

Commande Donne, en plus de .ok, .error et .time
cert_check(host: Host, port: int = 443, timeout: Duration = 5s) CertCheck : .expires: Moment \| None, .days_left: int, .subject, .issuer, .names: list[str], .trusted: bool, .self_signed: bool
http_check(url: str, timeout: Duration = 10s, verify: bool = True) HttpCheck : .status: int
dns_check(name: str, server: Host \| None = None, kind: str = 'A', timeout: Duration = 2s) DnsCheck : .answers: list[str]
ntp_check(server: Host, timeout: Duration = 2s) NtpCheck : .offset: Duration, .delay: Duration, .stratum: int
sip_check(host: Host, port: int = 5060, transport: str = 'udp', timeout: Duration = 2s) SipCheck : .status: int, .reason: str, .server: str

Une vérification n'arrête jamais le programme parce que le service est en panne. Elle donne .ok à faux et la raison dans .error. Un résultat est vrai ou faux par lui-même : if http_check(url): signifie .ok. Seule une faute du programme (un port hors limites, un type DNS inconnu, un transport inconnu) lève une erreur.

  • host et server acceptent un nom, une adresse ou un Device.
  • .time est le temps que la réponse a pris.
  • cert_check lit le certificat même quand cet ordinateur ne lui fait pas confiance, et le signale dans .trusted. .ok est vrai quand un certificat a été lu et n'a pas expiré. Un certificat expiré garde ses valeurs, avec .ok à faux. .days_left compte des jours entiers, arrondis vers le bas. .self_signed signifie que le sujet et l'émetteur portent le même nom.
  • http_check est .ok pour un statut inférieur à 400. Il n'envoie aucun jeton.
  • dns_check interroge le serveur donné, ou celui de l'ordinateur quand aucun n'est donné. Les types sont A, AAAA, PTR, MX, NS, TXT, CNAME et SOA. Pour PTR, le nom peut être une adresse. Un nom sans enregistrement du type demandé est .ok à faux.
  • ntp_check : .offset est l'horloge de cet ordinateur par rapport au serveur. Un serveur qui dit que sa propre horloge n'est pas réglée est .ok à faux.
  • sip_check envoie une requête OPTIONS, qui demande à un équipement SIP ce qu'il prend en charge et ne change rien. Toute réponse SIP rend .ok vrai, 100 Trying compris : le statut dit le reste. transport vaut "udp" ou "tcp".
Bogolang
site: HttpCheck = http_check("https://portal.example.com/")
cert: CertCheck = cert_check("portal.example.com")
if not site:
    print("portal down:", site.error)
if cert.ok and cert.days_left < 30:
    print("certificate expires in", cert.days_left, "days")
print(dns_check("portal.example.com", server=192.0.2.53))
print(ntp_check(192.0.2.123).offset)
print(sip_check(192.0.2.20).status)

Dans une relecture, chaque résultat est lu dans FOLDER/checks/, et http_check dans FOLDER/web/. Une réponse enregistrée manquante est une erreur, pas une vérification échouée. Chaque vérification est une ligne du journal d'exécution.

Limites : aucune vérification n'a rencontré un vrai serveur, un vrai magasin de certificats, le DNS d'un vrai ordinateur ou un vrai équipement SIP. cert_check peut échouer sur un équipement très ancien qui ne parle que TLS 1.0, car Python refuse cette version par défaut. Une erreur du système d'exploitation est affichée dans la langue de l'ordinateur.

Fichiers de capture

Commande Donne
read_capture(path: str, limit: int = 0) list[Packet] : le fichier entier, ou ses limit premiers paquets
each_packet(path: str) les paquets un par un, au fil de la lecture, pour un fichier trop grand pour la mémoire

Les fichiers .pcap et .pcapng sont lus, en IPv4 et en IPv6. Bogolang lit les fichiers de capture. Il ne capture pas : cela demande un pilote et des droits d'administrateur.

Champ d'un Packet Type
.time Moment, en UTC comme le fichier l'enregistre, à la microseconde
.length Size, la longueur sur le fil, aussi pour un paquet que la capture a tronqué
.src_mac, .dst_mac MAC \| None
.vlan int \| None
.src, .dst IP \| None ; pour ARP, les deux adresses de la question
.protocol str : "tcp", "udp", "icmp", "icmp6", "arp", ou le numéro sous forme de texte
.src_port, .dst_port int \| None
.flags str, les drapeaux TCP, comme "SA"
.dscp, .ttl int \| None
.payload_size Size, d'après les longueurs que les en-têtes indiquent
  • Les en-têtes seulement. DNS, SIP, HTTP et les autres protocoles au-dessus de TCP et UDP ne sont pas décodés.
  • Un paquet qui ne peut pas être décodé garde son heure et sa longueur, avec les autres valeurs vides. Un fichier tronqué dans son dernier paquet termine la lecture sans erreur.
Bogolang
packets: list[Packet] = read_capture("trace.pcap")
for p in packets:
    print(p)
table(packets, ["time", "src", "dst", "protocol", "dst_port", "flags", "dscp", "length"])
for q in each_packet("trace.pcap"):
    if q.dst_port == 5060:
        print("SIP from", q.src, "payload", q.payload_size)

Sur un petit fichier de trois paquets fait pour cette page :

Packet(2026-11-18 11:06:40.000000 UTC 198.51.100.7:5060 > 192.0.2.20:5060 udp 76B)
Packet(2026-11-18 11:06:40.250000 UTC 198.51.100.7:51515 > 203.0.113.5:443 tcp S 54B)
Packet(2026-11-18 11:06:40.260000 UTC 203.0.113.5:443 > 198.51.100.7:51515 tcp SA 54B)
time                     src           dst           protocol  dst_port  flags  dscp  length
-----------------------  ------------  ------------  --------  --------  -----  ----  ------
2026-11-18 11:06:40 UTC  198.51.100.7  192.0.2.20    udp           5060           46  76B
2026-11-18 11:06:40 UTC  198.51.100.7  203.0.113.5   tcp            443  S        46  54B
2026-11-18 11:06:40 UTC  203.0.113.5   198.51.100.7  tcp          51515  SA       46  54B
SIP from 198.51.100.7 payload 34B

Aucune capture faite par un vrai outil n'a été lue. Chaque fichier de test a été construit à partir des documents du format. Voir non prouvé.