Skip to content

Scripts

A script is Python you write in Danbyte that reads and writes your data through the API, as you. Use one to ingest or fix data in bulk, or to produce a report: the classic case is "which routers have no OSPF area set?", answered as a CSV you can download.

Scripts run on a button and on a schedule, take parameters, write files, and can be shared with colleagues. They never see more than the person they run as would see on the page.

Writing one

You can also ask for one. With the assistant turned on, "write a script that lists devices with no serial number" gets a saved script with its parameters filled in, ready to read and run. It writes the script; you run it.

Scripts → New script gives you a name and an editor. Everything the script needs comes from one import:

"""Routers with no OSPF area."""
from danbyte_sdk import db, run

missing = [
    d for d in db.list("devices", role="core")
    if not d["custom_fields"].get("CF_OSPF_AREA_X")
]
run.log(f"{len(missing)} of the core routers have no OSPF area")
run.output_csv("missing-ospf", missing, fields=["name", "site_name", "primary_ip"])

db is the API client, run is this run: its parameters, its log and its files. The full list of calls is in the SDK reference.

Anything printed lands in the run log. run.log(...) adds a timestamp and flushes immediately, which is what you want inside a loop.

Parameters

Declare parameters under How it runs, and the Run dialog builds itself from them: text, whole number, number, yes/no, long text, or one of a list. Read them with run.param("site"); a missing required parameter is refused before the script starts, not halfway through.

Scheduled runs use the parameters saved on the Schedule tab.

As a deploy target

A script can be the runner behind an automation target: a device's Deploy button then starts it with the deployed ids. For that it must declare a parameter named device_ids; a target refuses a script without one. A deploy also sets event (manual, bulk, auto, drift, provision) and object_type (device, or virtualmachine for a provision), plus the target's extra vars. A dry-run deploy adds dry_run: true. As a step of a deploy pipeline it also gets pipeline_run_id, step, dry_run and steps, the earlier steps with their status and output download links.

From a deploy, device_ids is always a list of id strings. Pressing Run by hand passes whatever the Run dialog sends, so a script used both ways should accept either:

ids = run.param("device_ids") or []
if isinstance(ids, str):
    ids = [ids]

The deploy run takes its final status from the script run: exit code 0 is succeeded, anything else (an error, a timeout, a stop) is failed.

What a script may do

Every run gets a run token: an API key minted for that run only, as the run-as account, expiring with it. So a script sees exactly the tenant, the sites and the objects that account sees, and every change it makes is in the change log under that name.

Two settings shape it:

  • API access - read and write, or read only. A read-only run cannot create, change or delete anything, whatever the code says.
  • Runs as - the person who clicks Run, or the script's owner. Choose the owner when you share a script and want it to see the same data for everyone. Because that lends the owner's identity to the code, only the owner or someone with trust can choose it, and only they can change what such a script executes: its source, its parameters and its schedule parameters, and only they can widen its API access from read only to read and write. Anyone with change can still switch it back to the caller, or to read only.

A run is stopped when it exceeds its timeout (five minutes by default, an hour at most), uses too much memory, or writes more log or files than the limits allow. Stopping a run takes the whole process tree with it.

Sharing

A new script is private to you. On the Sharing tab:

Who can see it Means
Only me The owner, and nobody else
Chosen users The people you pick
Chosen groups Everyone in the groups you pick
Everyone in the tenant Published - needs the publish permission

The pickers list the members of the tenant and the groups they are in, and the API refuses people and groups of another tenant. Superusers and deployment admins, who work across tenants, may pick anyone. Sharing only ever narrows: a colleague also needs the view permission on scripts, and running one needs run. Deleting and editing follow the same permissions as any other object.

Schedules

The Schedule tab runs a script hourly, daily, weekly or monthly. A scheduled run belongs to the owner and uses the owner's access, so turning a schedule on, changing what a scheduled script executes and widening its API access follow the same rule as running as the owner: the owner or someone with trust. The danbyte-scripts timer checks every minute, and a schedule fires once per occurrence even if the machine was asleep.

Keep runs prunes finished runs and their files after each scheduled run, by count or by age.

Runs and files

Every run has its own page: the live log (which follows the tail while it runs), the parameters it got, how long it took, the code as it was when it started, and the files it produced. Files come from run.output_csv(...) and friends.

The Files tab shows what is in them, not just their names: a CSV renders as a table, JSON and text render as themselves, and the download is still there for the copy you keep. A single file opens expanded. Very large files are download-only.

A run that is still going can be stopped from the same page.

Trusted scripts

A normal script talks to the API and is bound by it. A trusted script additionally gets danbyte_sdk.orm, which reaches the database directly - useful for a bulk job that would otherwise be thousands of API calls.

from danbyte_sdk import orm, run

for device in orm.objects("device").filter(status__slug="active"):
    run.log(device.name)

orm.objects(slug) is already restricted to what the run-as account may view. orm.model(slug) is not, and neither is anything else the script imports.

Marking a script trusted is a separate permission (trust on scripts) for that reason. A trusted script runs with the worker's own privileges: it can reach the database and the host as the Danbyte service account. Only grant it to people you would give a shell.

Trust approves the code as it is. When anyone without trust - the owner included - changes the source, the parameters or the schedule parameters, the script goes back to sandboxed, and the change log shows the reset next to the edit. Someone with trust re-approves it; their own edits keep it trusted. Settings that do not change what runs, such as the timeout, the API access or the sharing, leave it alone.

What a sandboxed script cannot do

Being honest about the boundary:

  • It gets no database credentials, no encryption keys and no Django settings. Its whole access is the run token.
  • It cannot read another tenant's data, because the token cannot.
  • It is confined in layers. Landlock, a Linux feature that needs no package or root, is always there. bubblewrap adds namespaces around it where the bwrap program is installed and allowed to run.

What each layer blocks:

Landlock alone bubblewrap + Landlock
Files Reads the system and the Python install; reads and writes its own work directory Sees nothing else at all: the system and Python read-only, the work directory, a minimal /dev. The script, its SDK copy and the launcher are read-only
/proc, the Danbyte directory, .env, backups, media, other runs Denied Not there
Network Redis and database ports refused; everything else open, including your devices No network: one loopback port, relayed to the Danbyte API. Devices and outside services are unreachable
Unix sockets Refused Refused
Other processes Cannot signal or trace processes outside the run Its own process namespace: it sees only its own processes
User The service account nobody (65534) in its own user namespace, which cannot create further namespaces; still the service account to the host
Host name, IPC The host's Its own
Processes 256 more than the service account already runs 256 for the run

Both layers apply together: inside bubblewrap the run is still under Landlock and the unix-socket filter, so a missing or refused bwrap leaves Landlock alone, never less. It still runs as the Danbyte service account on the host, not as a separate user, so treat "who may write a script here" as a real permission, which is why publishing to everyone and marking trusted each need one.

The first line of every run log names the layers in force, for example Sandbox: bubblewrap, Landlock, seccomp. When bubblewrap is installed but cannot run, the next line says why. Each worker tests bwrap once and shares the answer for ten minutes.

Choosing the level

DANBYTE_SCRIPT_SANDBOX picks it. See Settings.

Value Means
auto Default. bubblewrap + Landlock where bwrap works, Landlock alone where it does not
bwrap bubblewrap + Landlock, or the run is refused
landlock Landlock alone. Scripts keep the network, so they can reach your devices
none Unconfined, and every run log says so

A script that talks to devices directly, rather than through the Danbyte API, needs landlock: under bubblewrap its only network is the API.

Landlock needs Linux 5.13 or later with Landlock enabled. Current Ubuntu, Debian and RHEL kernels have it, and the default Docker seccomp profile allows it. Every level except none refuses a run on a host without it, and the run fails with that reason. The port block needs Linux 6.7 and the signal block 6.12; on an older kernel the run starts and its log names what is not blocked.

bubblewrap needs the bubblewrap package (install.sh installs it unless given --without-bubblewrap; an existing install it is added to keeps its scripts on Landlock until .env says otherwise; see Installation) and unprivileged user namespaces. Ubuntu 24.04 and later allow them for bwrap through its AppArmor profile, and Debian allows them by default. Docker's default profiles refuse them; see Docker → Script sandbox.

Under bubblewrap the script reaches the API at the same URL, except that an address becomes 127.0.0.1 and a port below 1024 becomes 8080; a host name is kept, so TLS still checks it. With an https DANBYTE_INTERNAL_URL, use a host name, not an address.

Versions

The Versions tab lists every saved source of the script from the change log, with who saved it and when. Tick one to diff it against the current source, or two to compare them, and Restore this version saves the old source as a new version through a normal edit - the owner and trust rules above still apply. See Versions and restore for the endpoints and what the change log does not keep.

Permissions

Grant Lets someone
script: view See the scripts shared with them
script: add / change / delete Author and manage scripts
script: run Run one, and stop a run; also needed to set it on, or deploy through, a script deploy target
script: trust Mark a script trusted, edit one without clearing that, edit or schedule scripts that run as their owner, and set or deploy through a trusted script on a deploy target
scripts.publish Publish a script to everyone in the tenant

Bulk changes

Tick rows in the script list - with script: change or delete - to reveal the bulk bar. Every action reaches only the scripts you can see, as the list does:

  • Enable and Disable switch every selected script on or off.
  • Export downloads the selected scripts as CSV, Excel or JSON. Export and import, here and from Import / Export, read only the scripts you can see: a private script of someone else's never leaves in a file, and an import does not match it.
  • Edit sets Enabled or the Description. The code, who it runs as, its sharing and its schedule stay per script, under the rules above.
  • Delete first shows what would happen - with the runs that go along - then deletes the scripts.

POST /api/scripts/bulk-update/ needs script: change; POST /api/scripts/bulk-delete/ needs script: delete.

From the shell

manage.py run_scripts     # the tick: fire due schedules, prune, drop dead run tokens

Runs themselves execute on the RQ workers, so a queued run that never starts means the workers are down - see Jobs.