Skip to main content

API

Everything the dashboard does goes through a JSON API under /api/ on the server. Scripts, CI pipelines and other tools use it with an API token.

API tokens​

Create one under My account → API tokens:

  • Name: what uses it, such as CI pipeline, so you know what stops working if you revoke it.
  • Role: Viewer, Operator or Admin, up to your own. Viewer reads everything; Operator also starts scans and audits and changes tags; Admin also manages machines and settings. See Roles.
  • Lasts: 30, 90, 180 or 365 days, or until revoked.

The token, starting dgt_, is shown once; only a hash of it is stored. Keep it in a secret store, such as your CI system's secrets.

A token acts as its account:

  • It never has more than the account's role: if an admin demotes the account, its tokens are demoted too. A disabled account's tokens stop working.
  • It can't manage accounts, API tokens or sign-in (/api/account…, /api/users…, /api/tokens…, /api/settings/security), so a leaked token can't make itself a lasting way in.
  • Its actions are in the Audit log as NAME (API token TOKEN).

My account shows each token's role, when it expires, and when and from which address it was last used. Revoke stops it at once. Admins see every account's tokens on the Accounts page and can revoke any of them. Revoked and expired tokens are listed for 30 days.

Making requests​

Send the token in the Authorization header. Requests that change something send JSON:

export DEACONGUARD=https://deaconguard.example.com:8443
export DEACONGUARD_TOKEN=dgt_…

curl -H "Authorization: Bearer $DEACONGUARD_TOKEN" "$DEACONGUARD/api/vulnerabilities"

curl -H "Authorization: Bearer $DEACONGUARD_TOKEN" -H "Content-Type: application/json" \
-d '{"checks": ["packages"]}' "$DEACONGUARD/api/hosts/HOST_ID/scans"

With the server's self-signed certificate, give curl the certificate with --cacert, or use your own trusted certificate; don't turn verification off.

Errors come back as {"error": "…"} with the HTTP status: 401 for a token that is wrong, revoked or expired, 403 for one whose role isn't enough, 429 after too many wrong tokens from one address (wait 15 minutes).

Useful endpoints​

Method and pathRoleDoes
GET /api/summaryViewerThe dashboard's numbers: hosts, what to fix, known exploited, overdue. A cluster's nodes' vulnerabilities count once, as the cluster's (1.29.0 and later)
GET /api/hostsViewerEvery host with its latest results and tags. An agent older than the server has agent.upgrade: to (the server's version), checks it can't run yet, live when it can't run live detection yet, and command, the install-script command that upgrades it (1.23.0 and later). Agent hosts and clusters have live, their live detection, as GET /api/hosts/{id}/live gives it (1.27.0 and later). A cluster has nodes, its nodes' vulnerabilities each counted once: findings, severity, fixes, exploit and scanned (1.29.0 and later)
GET /api/hosts/{id}ViewerOne host, with its scan history. A host whose token was revoked with its machines has disconnected (at, by, reason); a node of a cluster has cluster_id (1.21.0 and later), and excluded when it's left out of its cluster's scans and live detection, and left_cluster_at when the cluster stopped listing it (1.28.0 and later)
GET /api/hosts/{id}/cluster/findings?check=packagesViewerA cluster's nodes' findings of one check, packages, malware, antivirus or integrity, from their latest scans, each once with the nodes it's on: vulnerabilities (cve, package, severity, fix, fixed_version, and each node's installed_version) or findings (rule, severity, title, detail, evidence), counts by severity, and how many nodes the cluster has, how many were checked and excluded (1.29.0 and later)
GET /api/hosts/{id}/clusterViewerA Kubernetes cluster's page: its nodes, namespaces, workloads, pods and containers, with the problems in each (1.21.0 and later)
GET /api/hosts/{id}/liveViewerThe host's live detection: status (state: active, stopped, off, unsupported, agent_too_old, waiting or starting; reason, since, updated_at, kernel, events_last_hour, lost, suppressed, cpu_percent, memory_bytes, enabled, and alerts_24h by severity) and its newest 200 alerts. A cluster's status counts its nodes' (nodes, nodes_active) (1.27.0 and later); from 1.28.0 its enabled is the cluster's own switch, its alerts are all its nodes', each with host, the node's name, and nodes lists each node's host_id, host, excluded and status. An alert about a connection has remote, the address and port it went to (1.30.0 and later). An alert from a container has container_id, container, image, and in Kubernetes namespace and pod; allow has the allowlist rules that apply here, the alerts they skipped here, and last_at (1.33.0 and later)
PUT /api/hosts/{id}/liveAdminTurn live detection on or off for a host, or for a cluster and all its nodes: {"enabled": false}. A node follows its cluster: 409 (1.28.0 and later)
PUT /api/hosts/{id}/excludedAdminLeave a node out of its cluster's scans, schedules and live detection, or bring it back: {"excluded": true}; 409 for a host that isn't a node (1.28.0 and later)
POST /api/hosts/{id}/live/testOperatorAsk the host's agent for a test alert, which arrives within about 20 seconds; refused unless detection is active there. For a cluster, every node where it's active sends one (1.28.0 and later)
GET /api/updateAdminWhether a newer release is out, as the server last learned: enabled, current, latest, available, notes_url, checked_at, and error when the last check failed; managed when the environment turned the check off (1.34.0 and later)
PUT /api/settings/updatesAdminTurn the daily check for new releases on or off: {"enabled": false}. Turning it on checks straight away (1.34.0 and later)
GET /api/settings/liveViewerSettings → Live detection: new_hosts, and how many servers and clusters have it on, off, unsupported and agent_too_old, a cluster counted once with its nodes from 1.28.0 (1.27.0 and later)
PUT /api/settings/liveAdminWhether servers enrolled from now on start with live detection on: {"new_hosts": true}; a cluster's nodes follow their cluster
POST /api/settings/live/hostsAdminTurn live detection on or off for every server and cluster, and so the clusters' nodes: {"enabled": true}
GET /api/live/allowlistViewerThe live detection allowlist, newest first: each rule's id, rule, program, path, image, container, namespace, host_id (empty for all hosts) and scope, its name, note, created_by, created_at, updated_at, and the alerts it skipped with last_at (1.33.0 and later)
POST /api/live/allowlistAdminAdd a rule: {"rule": "DG-RT-031", "program": "/usr/sbin/insmod", "path": "/opt/zfs/zfs.ko", "host_id": "", "note": "the vendor's ZFS module"}. rule and at least one of program, path, image, container and namespace are required; an image without a tag or digest matches every tag. At most 500 rules (1.33.0 and later)
PUT /api/live/allowlist/{id}AdminChange a rule, with the same fields; what it skipped so far is kept (1.33.0 and later)
DELETE /api/live/allowlist/{id}AdminRemove a rule (1.33.0 and later)
PATCH /api/hosts/{id}OperatorChange a host's settings: {"name": "payments-api-prod"} for its display name ("" shows its hostname again), {"auto_scan_containers": true} for an agent's automatic container scans (for a cluster, scanning it when it changes, and its nodes' new containers; a node follows its cluster: 409, 1.28.0 and later), or {"allow_sudo": true} for this machine. Hosts have address (what they are called), hostname and name
POST /api/hosts/{id}/scansOperatorStart a scan: {"checks": ["packages", "libraries", "containers", "integrity", "malware", "config", "changes", "paths", "hardening", "antivirus", "yara"]}, or ["kubernetes"] for a cluster; see Checks for each ID. For a cluster, the Kubernetes check runs on the cluster and the other checks given on each of its nodes not excluded; the answer adds nodes_started and nodes_skipped, each with why (1.28.0 and later)
GET /api/diagnostics/cpu?seconds=30AdminA CPU profile of the server over the next 5 to 60 seconds (30 by default), as a .pprof file for go tool pprof
POST /api/hosts/{id}/auditsOperatorStart a server audit: {}
GET /api/scans/{id}ViewerA scan's status and full results; poll until scan.status is succeeded or failed
GET /api/scans/{id}/sbom?format=cyclonedxViewerThe scan's software bill of materials, as CycloneDX 1.6 (cyclonedx, the default) or SPDX 2.3 (spdx) JSON; 404 for scans from before 1.1.0
GET /api/vulnerabilitiesViewerEvery CVE on every host, most urgent first, with KEV, EPSS, CVSS and fix deadlines
GET /api/vulnerabilities/{cve}ViewerThe hosts and packages one CVE affects
GET /api/imagesViewerThe registry images DeaconGuard checks, each with its latest scan
POST /api/imagesOperatorAdd an image and start its first scan: {"reference": "ghcr.io/acme/shop:4.2", "platform": "linux/amd64", "watch": true}; watching is on unless watch is false
POST /api/images/{id}/scansOperatorScan an image again, for example from CI after a push; 409 while a scan of it is queued or running
PATCH /api/images/{id}OperatorWatch an image for new builds, or stop: {"watch": false}
GET /api/images/{id}ViewerOne image with its last 20 scans, without their results
GET /api/image-scans/{id}ViewerOne image scan with its full result; poll until status is succeeded or failed
POST /api/registry-loginsAdminSave a registry login: {"registry": "ghcr.io", "username": "robot", "secret": "…"}, or for Amazon ECR "kind": "ecr" with an access key ID as username; the secret is never returned
POST /api/registry-logins/{id}/checkAdminLog in to the registry with a saved login: status is ok, failed (with message) or unchecked
GET /api/registry-logins/{id}/repositoriesOperatorThe repositories the login can see; listed is false when the registry won't list them
GET /api/registry-logins/{id}/tags?repository=team/app&pattern=&platform=OperatorA repository's tags, newest first, each with whether it matches pattern, its digest and pushed_at where the registry gives them (Amazon ECR, Docker Hub, GHCR with a login, Google Artifact Registry, Azure Container Registry, Quay, Harbor and GitLab), and a note when the registry's own API failed and the registry API listed them instead. With platform (such as linux/amd64), the matching tags get created, when their image was built, and are ordered by it where there are no push times, as a watch's first check orders them
GET /api/repository-watchesViewerThe watched repositories
POST /api/repository-watchesOperatorWatch a repository: {"registry": "ghcr.io", "repository": "acme/app", "tag_pattern": "^v\\d+", "platform": "linux/amd64", "keep": 5, "history": 50, "notify_level": "any", "notify_channels": []}; notify_level is off, any, low, medium, high, critical or exploited, and empty notify_channels means every channel that takes image_report
GET /api/repository-watches/{id}ViewerOne watched repository with its builds: every scan of the images it added, newest first, at most 1,000
PATCH /api/repository-watches/{id}OperatorChange a watch: any of tag_pattern, keep, history, notify_level and notify_channels
DELETE /api/repository-watches/{id}OperatorStop watching a repository; the images it added stay, no longer watched
POST /api/repository-watches/{id}/checkOperatorCheck a watched repository for new pushes now
GET /api/repository-watches/report-channelsOperatorThe notification channels a watch's reports can go to, by name
GET /api/network-targetsViewerThe network targets the server scans, each with its latest scan
POST /api/network-targetsAdminAdd a network target and start its first scan: {"name": "Office", "targets": ["10.0.0.0/24", "shop.example.com"], "ports": "", "tls": true, "web": true, "web_paths": true, "interval_hours": 24}; ports empty means the default ports, web checks each web site found and web_paths also asks for the paths a site should never publish (both default to true, 1.25.0 and later), and interval_hours is 0 (only on demand), 1, 6, 12, 24 or 168
PATCH /api/network-targets/{id}AdminChange a network target: send every field, as when adding it; web and web_paths keep their values when left out
DELETE /api/network-targets/{id}AdminRemove a network target and its scans
GET /api/network-targets/{id}ViewerOne network target with its last 20 scans, without their results
POST /api/network-targets/{id}/scansOperatorScan a network target now; 409 while a scan of it is queued or running
GET /api/network-scans/{id}ViewerOne network scan with its full result: hosts, open ports, TLS and findings
GET /api/auditsViewerAudits, with their grades
PUT /api/hosts/{id}/tagsOperatorSet a host's tags: {"tags": ["prod", "web"]}. A cluster's tags are its nodes' tags; a node's can't be set: 409 (1.28.0 and later)
GET /api/trends?days=90&tag=prodViewerOpen vulnerabilities per day
POST /api/reportsOperatorCreate a report of a scan or audit
GET /api/reports/{id}/download?format=pdfViewerDownload a report as pdf, html, xlsx, csv or json

Notifications​

Admins set up notifications with these, as the dashboard's Settings → Notifications page does:

Method and pathRoleDoes
GET /api/notificationsAdminThe channels, with their secrets left out; the last 100 messages sent and how each went; the dashboard's address; and the events a channel can take
POST /api/notifications/channelsAdminAdd a channel: {"name": "Security team", "kind": "slack", "config": {"url": "https://hooks.slack.com/…"}, "events": ["exploited", "critical", "malware", "config"], "tags": [], "digest": "daily", "digest_time": "08:00", "timezone": "UTC"}. kind is email, slack, teams, webhook, syslog, splunk, jira or servicenow; config takes what that kind needs, as on Channels; events are the ones under Events, by their webhook names; digest is none, daily or weekly (with digest_days, 0 for Sunday)
PATCH /api/notifications/channels/{id}AdminChange a channel: send every field, as when adding it, and "enabled": false to turn it off; secrets left empty are kept
DELETE /api/notifications/channels/{id}AdminRemove a channel
POST /api/notifications/channels/{id}/testAdminSend a test message now and answer whether it arrived
PUT /api/notifications/settingsAdminSet the dashboard's address, for links in messages: {"dashboard_url": "https://deaconguard.example.com"}
GET /api/maintenanceViewerThe maintenance windows
POST /api/maintenanceOperatorAdd one: {"name": "Patching", "tags": ["prod"], "starts_at": "2026-11-01T22:00:00Z", "ends_at": "2026-11-02T02:00:00Z", "skip_scans": true}; no tags means every host
DELETE /api/maintenance/{id}OperatorEnd or remove a maintenance window

For example, fail a pipeline when a host has a known exploited vulnerability with a fix:

count=$(curl -fsS -H "Authorization: Bearer $DEACONGUARD_TOKEN" "$DEACONGUARD/api/summary" | jq '.exploit.known_fixable')
[ "$count" -eq 0 ] || { echo "$count known exploited vulnerabilities have a fix waiting"; exit 1; }