Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

APIs and other platforms

Web APIs, Meraki, RESTCONF, the serial console, the table of platforms.

All documentation pages

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.
  • params are added to the address as a query.
  • verify=False accepts 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.

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"])

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 --dry the 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
  • org is 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.
  • token is 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 .show and .run, and usable in change 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, or ttyUSB0 for /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.
Bogolang
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.
  • fields maps a Bogolang field (name, ip, platform, site, role) to the API's name for it. Without it Bogolang looks for name or hostname, ip, ip_address or address, and platform, 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 in d.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 in d.extra["api_platform"]. Check a device's platform before running commands on it.
  • The time limit is 30 seconds.
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)

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.

  • host and server take a name, an address or a Device.
  • .time is how long the answer took.
  • cert_check reads the certificate even when this computer does not trust it, and says so in .trusted. .ok is true when a certificate was read and has not expired. An expired certificate keeps its values, with .ok false. .days_left counts whole days, rounded down. .self_signed means the subject and the issuer are the same name.
  • http_check is .ok for a status below 400. It sends no token.
  • dns_check asks the server given, or the computer's own when none is given. The kinds are A, AAAA, PTR, MX, NS, TXT, CNAME and SOA. For PTR the name may be an address. A name with no record of the kind asked is .ok false.
  • ntp_check: .offset is this computer's clock against the server. A server that says its own clock is not set is .ok false.
  • sip_check sends one OPTIONS request, which asks a SIP device what it supports and changes nothing. Any SIP answer makes .ok true, 100 Trying included: the status says the rest. transport is "udp" or "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)

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.
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)

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.