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:
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
trustcan 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 withchangecan 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
bwrapprogram 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¶
Runs themselves execute on the RQ workers, so a queued run that never starts means the workers are down - see Jobs.