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
paramssont ajoutés à l'adresse sous forme de requête. verify=Falseaccepte 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.
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 |
orgest 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.tokenest 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
.showet.run, et utilisable danschange 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, outtyUSB0pour/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.
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.
fieldsassocie un champ Bogolang (name,ip,platform,site,role) au nom que l'API lui donne. Sans lui, Bogolang cherchenameouhostname,ip,ip_addressouaddress, etplatform,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é dansd.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 dansd.extra["api_platform"]. Vérifiez la plateforme d'un équipement avant de lancer des commandes dessus. - Le délai maximal est de 30 secondes.
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.
hostetserveracceptent un nom, une adresse ou unDevice..timeest le temps que la réponse a pris.cert_checklit le certificat même quand cet ordinateur ne lui fait pas confiance, et le signale dans.trusted..okest vrai quand un certificat a été lu et n'a pas expiré. Un certificat expiré garde ses valeurs, avec.okà faux..days_leftcompte des jours entiers, arrondis vers le bas..self_signedsignifie que le sujet et l'émetteur portent le même nom.http_checkest.okpour un statut inférieur à 400. Il n'envoie aucun jeton.dns_checkinterroge le serveur donné, ou celui de l'ordinateur quand aucun n'est donné. Les types sontA,AAAA,PTR,MX,NS,TXT,CNAMEetSOA. PourPTR, le nom peut être une adresse. Un nom sans enregistrement du type demandé est.okà faux.ntp_check:.offsetest 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_checkenvoie une requête OPTIONS, qui demande à un équipement SIP ce qu'il prend en charge et ne change rien. Toute réponse SIP rend.okvrai,100 Tryingcompris : le statut dit le reste.transportvaut"udp"ou"tcp".
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.
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é.