This page covers the ways Bogolang reads other than SSH: web APIs, Meraki, RESTCONF, the serial
console and an inventory from an API. It also covers the one thing Bogolang posts (webhook),
the five service checks and the reading of capture files.
Everything here only reads, but for webhook. A change to a device stays in a change block
over SSH or the console (see changes). Every call works on saved answers with
bogo run --replay FOLDER and is a line of the run record (see the tools).
Stored tokens
A token or an API key is never written in a program. It is stored once, under a name, in the protected store of the operating system:
bogo login --api nms
bogo logout --api nms
A program gives the name, token="nms", never the value. A name is made of letters, digits,
dot, dash and underscore. A program that names a token that is not stored stops with:
No token is stored under the name 'nms'. Store it first with: bogo login --api nms. In a
replay no token is read.
http_get
| Command | Gives |
|---|---|
http_get(url: str, token: str = '', params: dict[str, str] \| None = None, verify: bool = True, timeout: Duration = 10s) |
Reply |
- Only reading exists: every request is a GET. There is no
http_post. - The token is sent as
Authorization: Bearer. - A token never goes to another host. A redirect is followed only to the same host, port and scheme. Any other is refused, and the other host is never contacted.
- A token is masked as
***in errors and in saved replay files, even when the server repeats it in its answer. paramsare added to the address as a query.verify=Falseaccepts a certificate the computer does not trust, for a server that signed its own. Bogolang then says so on standard error, once per host.- An answer of 400 or more stops the program with the status and a hint (401: the token is missing or not accepted; 403: not allowed; 404: nothing there; 429: too many requests).
Reply
| Member | Gives |
|---|---|
.status |
int |
.text |
str, the answer as it came |
.url |
str |
.headers |
dict[str, str], names in small letters |
.data() |
object, the answer read as JSON |
.rows(key: str = '') |
list[Row], when the answer is a JSON list of objects; key names the list when it sits inside an object |
.value(path: str) |
str, one value of the JSON, the path written a.b.0.c |
A value inside a row is text. A whole number written 20.0 reads as 20. A list or an object
inside a row is kept as its JSON text. A name of a data model that holds a dot cannot be reached
with .rows() or .value(); colons and dashes work.
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"])
Run with --replay on a saved answer:
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
In a replay each answer is read from FOLDER/web/NAME.json. A run with
--save-replay FOLDER writes those files. A missing file stops the program and names the file
it needs.
webhook
| Command | Does |
|---|---|
webhook(name: str, text: str) |
posts one text to the webhook stored under that name |
bogo login --webhook noc
bogo logout --webhook noc
- The address of a webhook is a secret: whoever has it can post. So it is stored once, and a program holds only its name. The address is never shown, in an error, the run record or the output.
- The address must start with
https://. - The text is posted as JSON,
{"text": "..."}. Slack, Mattermost, Google Chat and Teams workflows read this form. - No redirect is followed. An answer of 300 or more is an error. The time limit is 10 seconds.
- A post leaves the computer and cannot be taken back.
- With
bogo run --drythe text is shown and not sent:
DRY RUN: webhook noc would post this text. Nothing is sent.
dist-sw9 has a platform Bogolang does not know
Under --replay nothing is posted either. Each real post is a line of the run record: the
name, and whether it left. No webhook has been posted to a real service. See
watching and listening for webhook inside alert when.
Meraki
| Command | Gives |
|---|---|
meraki(org: str = '', token: str = 'meraki') |
MerakiSession |
orgis the name or the number of the organisation. It may be left out when the key sees only one. A name that matches none, or more than one, is an error that lists the organisations the key sees.tokenis the name of the stored API key:bogo login --api meraki.
| Member | Gives |
|---|---|
.organizations() |
list[Row] |
.networks() |
list[Row], of the organisation |
.devices() |
list[Row], of the organisation |
.uplinks() |
list[Row], one row per uplink of each appliance, with the appliance's values beside it |
.get(path: str, **params: str) |
Reply, any other read of the Dashboard API: one request, no paging; path starts with / |
.org_id, .org_name |
str |
- Long lists are fetched page by page without the program asking. The next page is followed only on Meraki's own API host.
- When Meraki answers "too many requests", Bogolang waits the time Meraki gives, at most 60 seconds, and asks again, up to 5 times.
- Only reading exists. The run record names the device
meraki. - A column name with capitals can be read with a dot:
row.publicIp,d.networkId.
The example meraki_inventory lists the devices of one organisation and those not on a wanted firmware:
```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"])
On its saved answers:
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
| Command | Gives |
|---|---|
| `restconf(d: Device, verify: bool = True)` | `RestSession`; nothing is sent yet |
| `RestSession.get(path: str)` | `Reply`: one GET of `https://DEVICE/restconf/data/PATH` |
- It works on the platforms `iosxe` and `nxos`. `ios`, which an inventory line gets when it
names no platform, is refused: an IOS-XE device needs `platform=iosxe`.
- It uses the stored device login (`bogo login`), over HTTPS, read at the first request.
- `path` is written as in the device's data model, for example `"ietf-interfaces:interfaces"`.
It is sent as written. Query options are not in this version.
- An error says what to do: a certificate the computer does not trust (use `verify=False` for a
device that signed its own), RESTCONF turned off (on IOS-XE `restconf` and
`ip http secure-server`, on NX-OS `feature restconf`), a refused login.
- NETCONF is not in this 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 has never read a real device. See not proven.
The serial console
| Command | Gives |
|---|---|
serial(port_name: str, speed: int = 9600, platform: str = 'ios', login: str = 'default') |
Session |
- The session is the same as an SSH session: read-only, with
.showand.run, and usable inchange on s:(see devices and changes). - It works on IOS and IOS-XE.
- A console that asks for no login works: with no login stored for the profile, the user and the password are empty and nothing is asked at the keyboard.
- The device is named after the port:
COM3, orttyUSB0for/dev/ttyUSB0. In a replay the saved outputs are in a folder of that name. - The break key, ROMMON and password recovery are not in this version.
s: Session = serial("COM3", speed=9600, platform="iosxe")
print(s.show("show version").text)
s.close()
The serial console has never been tried on a real port. See not proven.
An inventory from an API
| Command | Gives |
|---|---|
inventory_api(url: str, token: str = '', fields: dict[str, str] \| None = None, verify: bool = True) |
list[Device] |
- The API must answer a JSON list of objects, or an object with one list of objects inside.
fieldsmaps a Bogolang field (name,ip,platform,site,role) to the API's name for it. Without it Bogolang looks fornameorhostname,ip,ip_addressoraddress, andplatform,site,role.- Every other value goes to
d.extra. - The usual platform words of other tools are understood:
cisco_ios,cisco_xe,cisco_asa,cisco_nxos,cisco_wlc_ssh,ios-xe,nx-os. The API's own word is then kept ind.extra["api_platform"]. - A word Bogolang does not know does not stop the list. That device gets the platform
ios, with the API's word ind.extra["api_platform"]. Check a device's platform before running commands on it. - The time limit is 30 seconds.
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)
On the same saved answer as http_get above:
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 has a word no rule knows, so it became ios. The file sources (.csv, .xlsx,
.yaml) are read by inventory(path), on the devices page.
Service checks
| Command | Gives, beside .ok, .error and .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 |
A check never stops the program because the service is down. It gives .ok false and the
reason in .error. A result is true or false by itself: if http_check(url): means .ok.
Only a fault of the program (a port out of range, an unknown DNS kind, an unknown transport)
raises an error.
hostandservertake a name, an address or aDevice..timeis how long the answer took.cert_checkreads the certificate even when this computer does not trust it, and says so in.trusted..okis true when a certificate was read and has not expired. An expired certificate keeps its values, with.okfalse..days_leftcounts whole days, rounded down..self_signedmeans the subject and the issuer are the same name.http_checkis.okfor a status below 400. It sends no token.dns_checkasks the server given, or the computer's own when none is given. The kinds areA,AAAA,PTR,MX,NS,TXT,CNAMEandSOA. ForPTRthe name may be an address. A name with no record of the kind asked is.okfalse.ntp_check:.offsetis this computer's clock against the server. A server that says its own clock is not set is.okfalse.sip_checksends one OPTIONS request, which asks a SIP device what it supports and changes nothing. Any SIP answer makes.oktrue,100 Tryingincluded: the status says the rest.transportis"udp"or"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)
In a replay each result is read from FOLDER/checks/, and http_check from FOLDER/web/. A
missing saved answer is an error, not a failed check. Each check is a line of the run record.
Limits: no check has met a real server, a real certificate store, the DNS of a real computer or
a real SIP device. cert_check may fail on a very old device that speaks only TLS 1.0, because
Python refuses that version by default. An error of the operating system is shown in the
language of the computer.
Capture files
| Command | Gives |
|---|---|
read_capture(path: str, limit: int = 0) |
list[Packet]: the whole file, or its first limit packets |
each_packet(path: str) |
the packets one by one, as they are read, for a file too large for memory |
.pcap and .pcapng files are read, IPv4 and IPv6. Bogolang reads capture files. It does not
capture: that needs a driver and administrator rights.
Field of a Packet |
Type |
|---|---|
.time |
Moment, in UTC as the file stores it, to the microsecond |
.length |
Size, the length on the wire, also for a packet the capture cut short |
.src_mac, .dst_mac |
MAC \| None |
.vlan |
int \| None |
.src, .dst |
IP \| None; for ARP the two addresses of the question |
.protocol |
str: "tcp", "udp", "icmp", "icmp6", "arp", or the number as text |
.src_port, .dst_port |
int \| None |
.flags |
str, the TCP flags, such as "SA" |
.dscp, .ttl |
int \| None |
.payload_size |
Size, from the lengths the headers state |
- Headers only. DNS, SIP, HTTP and the other protocols above TCP and UDP are not decoded.
- A packet that cannot be decoded keeps its time and length, with the other values empty. A file cut short in its last packet ends the reading with no error.
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)
On a small file of three packets made for this 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
No capture made by a real tool has been read. Every test file was built from the format documents. See not proven.