Skip to content

Threat Model and Risk Assessment ​

This page assesses the cybersecurity risks of the Hegemony platform as it ships: what it must protect, who acts on it, where trust changes hands, what can go wrong at each of those boundaries, which controls handle it today, and what risk is left. It is kept as the risk assessment that Article 13(2) and (3) of the EU Cyber Resilience Act describe, and it is revisited by the rule in Keeping This Assessment Current.

It records risk at the level of the design. Unresolved vulnerabilities are never described here: report them privately, as SECURITY.md explains.

Scope and Method ​

Scope ​

In scopeNot in scope
This repository and its five published images: api, worker, scheduler, ui, egress-nflogThe demo stack and the hegemony-demo repository
The first-party plugin wheels the images install, from the four plugin repositories, and the registry extension the API shipsDevelopment mode (HEGEMONY_AUTH_DISABLED, HEGEMONY_ENVIRONMENT=dev)
The bundled third-party services as the compose files run them: Keycloak, Temporal, PostgreSQL, OpenBao, the object store (Versity S3 Gateway), zot and Docker-in-DockerPlugins and extensions from other parties
The build and release pipeline that publishes the imagesThe OpenTelemetry collector overlay (otel), until the product boundary says whether it is part of the product
What the platform requires of the host, the network and the systems it connects toA hosted service run by a supplier

Method ​

  1. List the assets, actors, components and data flows, from the architecture pages and the compose files, checked against the code.
  2. Mark the trust boundaries: every place where data or control passes between parties that trust each other differently.
  3. Walk each boundary with STRIDE: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service and Elevation of privilege. For each threat that applies, record the controls that exist today, linked to the page that describes them, and the risk they leave.
  4. Give each residual risk a treatment:
    • Tracked: open work the maintainers track; the residual risk is stated, without a date.
    • Accepted: a documented design decision; the link says why.
    • Operator: the deployment operator closes it (Operator Responsibilities).

Risks are not scored. On a self-hosted product the same design risk weighs differently in each deployment, so the page records how each one is treated; a reported vulnerability gets its severity in the security process.

Assumptions ​

  • The platform runs on one Docker host with the shipped compose files and ENV=prod, as Production Hardening describes. A deployment that runs the images another way must give each component the same isolation.
  • HEGEMONY_ENVIRONMENT is prod or production, so the API's startup checks apply (Production Mode Enforcements).
  • The deployment operator controls the host, terminates TLS in front of the UI and Keycloak, keeps the host patched and keeps its clock synchronized.
  • Every organization on an instance trusts its platform admins and its deployment operator: organizations share one Keycloak realm, Temporal namespace, secret store and database (Multi-Tenancy).
  • Managed devices are reachable from the Docker host over a management network the operator runs.

Assets ​

AssetWhere it livesWhat must holdMain protection
Device and integration credentials (organization secrets)The secret backend; the database holds references onlyConfidentialitySecrets: resolved when a step runs, namespaced per organization, masked in output
Platform credentials: internal API token, token pepper, database, object store and Keycloak credentials, registry signing key, state encryption key, OpenBao credentials, seal and recovery keysThe env file and Docker volumes on the hostConfidentiality, integrityCredentials, Secret stores
Device access: running commands and changing configuration on managed devicesFlows, executed by the workerIntegrity, availabilityRole checks on flow editing and runs, approvals, SSH host keys, egress policies
Flow definitions, templates and attachments, and the git repositories they sync withDatabase, object store, git remotesIntegrityflow:manage, flow versions, Git Integration
Run evidence: events, step results, artifacts and logsDatabase, object storeIntegrity, then confidentialityWritten through the API's internal routes; secrets masked
Audit logDatabaseIntegrity, availabilityReliability guarantees, append-only table
Sign-in and access tokens: access tokens, personal access tokens, run tokens, event-stream tickets, webhook secrets and addressesBrowser session storage, clients; the database keeps digests onlyConfidentialitySign-in and access
Terraform and OpenTofu stateDatabase, encrypted per versionConfidentiality, integrityEncryption and Keys
Container images: the five published images, the platform registry's images and the sandbox's image storeGHCR, zot, the dind-data volumeIntegrityRelease pipeline, platform registry
Workflow state: Temporal's workflow inputs and historyTemporal's PostgreSQLConfidentiality, integrityInternal network only; no secret values in the history
Tenant data and access configuration: inventory, variables, memberships, permission overridesDatabaseConfidentiality between organizations, integrityMulti-Tenancy, Role-Based Access Control

Actors ​

ActorTrustWhat it can do
Deployment operatorFull; outside the platform's controlRuns the host, Docker and the env file, and holds every platform credential
Platform admin (realm role admin)Trusted by every organization on the instanceManages organizations, memberships, permissions, secret backends and extensions, and acts in any organization (Per-org RBAC)
Organization admin (membership role admin)Trusted within its organizationManages its organization's inventory, secrets, members and settings, including the SSH host-key mode and secret writes by steps
Membership role editorTrusted with its organization's device access and with the secrets its flows resolveEdits and commits flows, links them to git, and sets up schedules and webhooks, so decides what runs on devices and in the sandbox (Trusted input boundaries); also everything an operator can do
Membership role operatorTrusted with its organization's device accessStarts and controls runs of the flows editors built, with the inputs their launch forms accept; cannot change a flow
Membership role approverTrusted to decide approvalsApproves or rejects paused runs (Separation of Duties)
Membership roles auditor and viewerRead-onlyRead their organization's data
API clients and automationAs their token's scopesPersonal access tokens (API Tokens) and the hegemony-automation service account
Worker and schedulerPlatform servicesCall the API's internal routes with the internal token
Step codePlugin handlers are platform code in the worker; flow containers are untrusted workloads, contained by the sandboxRun what a flow asks for
Managed devicesPartly trusted: identity checked by host key, output treated as dataAnswer the worker's sessions; download files they are sent
External identity providerTrusted to authenticate its users, through KeycloakSigns users in; its groups can grant organization roles (IdP mapping)
Webhook sendersUntrusted until the endpoint's secret checks outStart the one flow an endpoint targets
Integrated systems: git remotes, inventory sources, external secret backends, registriesTrusted for what they supply: whoever can write to them changes the flows, inventory, credentials or images the platform uses (Trusted input boundaries)Supply flows, inventory, secrets and images
Notification targetsRecipients onlyReceive the run and approval events they are subscribed to
Plugin and extension authorsTheir code runs in-process with the rights of the API or workerAnything those processes can do
Anyone else on the networkUntrustedReach only what the operator publishes

Components, Data Flows and Trust Boundaries ​

The diagram marks each trust boundary (TB) on the flows that cross it. TB7 (between organizations, and between an organization and the platform) and TB8 (code supply) are not network hops; they cut across the whole picture.

IDBoundaryBetween
TB1Client edgeBrowsers and API clients, and the UI's nginx with the API behind it
TB2IdentityKeycloak, and the browsers, the API and external identity providers
TB3Public webhook ingressExternal systems, and POST /hooks/{path_token}
TB4Internal service networkThe API, worker and scheduler, with each other and with the bundled stores
TB5Flow-container sandboxThe worker, and the containers flows run
TB6OutboundThe worker, the sandbox and the API, and managed devices and integrated systems
TB7Tenant and privilegeOne organization and another; an organization and the platform
TB8Code supplyPlugins, extensions, dependencies and the release pipeline, and the running processes
TB9HostThe containers, and the Docker host and its operator

Components ​

ComponentImageZoneReachable from outside the compose network
ui: the web app, and nginx proxying /api/ to the APIhegemony/uiEdgeYes: the published UI port (UI_BIND_ADDRESS, UI_PORT)
apihegemony/apiPlatform servicesOnly through ui
worker, two replicashegemony/workerPlatform servicesNo
schedulerhegemony/schedulerPlatform servicesNo
Keycloak, with its own PostgreSQL (auth overlay)keycloak/keycloakIdentityIts port, bound to 127.0.0.1 unless KEYCLOAK_BIND_ADDRESS widens it
Temporal, with its own PostgreSQLtemporalio/auto-setupStores and orchestrationNo; its console is opt-in and loopback-only (Temporal console)
PostgreSQL for the applicationpostgresStores and orchestrationNo
OpenBao (openbao-internal overlay)openbao/openbaoStores and orchestrationNo
Object store (s3 overlay)versity/versitygwStores and orchestrationIts S3 port, bound to 127.0.0.1 unless HEGEMONY_S3_BIND_ADDRESS widens it
zot (registry overlay)project-zot/zotStores and orchestrationNo
dind, dind-initdocker:28-dind (privileged), docker:28-cliSandboxNo
egress-nfloghegemony/egress-nflogSandbox, in dind's network namespaceNo

Data Flows ​

FlowCarriesAuthenticated by
Browser to ui and apiThe web app, API calls, live event streamsKeycloak access token; a single-use event-stream ticket
API client to ui and apiAPI callsPersonal access token or service-account token
Browser to Keycloak; Keycloak to an external identity providerSign-inPassword and one-time code, or the external provider
api to KeycloakThe realm's signing keysNone needed: public keys
Webhook sender to apiWebhook deliveriesThe endpoint's HMAC or bearer secret; optionally its source addresses
worker and scheduler to apiStep status, events, artifacts, step access, schedule triggersInternal API token
api and worker to TemporalWorkflows and activitiesThe compose network only
api to PostgreSQL, object store and zotApplication data, files, imagesDatabase password; S3 keys; registry tokens the API signs
api and worker to OpenBaoSecret reads (worker), writes and Transit (API)AppRole credentials, rotated and bound to OpenBao's network
worker to the sandbox daemonContainer stepsThe compose network only: dind drops its API port on every other interface, so flow containers cannot reach it; the worker checks the daemon's marker before using it
Flow containers to api and zotManaged state; image pulls and pushesPer-step run tokens
worker, sandbox and api to devices and integrated systemsSSH sessions, HTTP requests, git, notifications, image pullsCredentials from the secret store; device host keys
Devices to the object storeFile downloadsPresigned URLs

Threats by Boundary ​

Each table walks STRIDE for one boundary. A residual risk names its treatment: "Accepted" or "Operator" when it has one; a risk with neither is tracked open work.

TB1: Client Edge ​

Everything a user or script sends enters through the UI's nginx, which serves the web app and proxies the API.

STRIDEThreatControls in placeResidual risk
SA request carries a stolen or forged identityOnly RS256 tokens from the realm, with issuer, audience and expiry checked (JWT Validation Security); personal access tokens stored as digests, expiring, revocable (API Tokens); a recent sign-in required, and tokens refused, for changing secret backends, permission overrides and organization members and for issuing a token, and for any other action an administrator switches it on for (Step-up Authentication)Tokens are readable by page scripts; the fresh sign-in covers only the actions it is on for, an administrator can switch it off for all but the permission editor (in the editor, or through a configuration import, which does not ask), and it does not prove a second factor was given; session lifetimes to review
TTraffic or the page is altered between browser and APISecurity response headers; a wildcard CORS origin refused in production (CORS)Operator: TLS in front of the UI, and the full Content Security Policy enforced once it reports nothing
RA user denies an action they tookEvery mutating route makes an audit decision, checked in CI (The gates); refusals are recorded (Access decisions)Keycloak's sign-in events are not collected with the audit log
IA caller reads data their role does not allowEvery route maps to an action with a policy, and an unmapped route falls back to requiring authentication (Role-Based Access Control); CI fails a route without a ruleCredential material in API access logs
IAn outsider learns the release to pick known exploitsGET /system/version, which names the release, commit and build date, needs a signed-in caller; the health probes name none (Policies)The public contract (/openapi.json) carries the release number
DRequest floods exhaust the APIA user holds at most 10 event-stream tickets (Rate Limit Behavior); webhook budgets (TB3)No API-wide rate limit
EA lower role reaches an admin functionOne middleware enforces every route; permission:manage cannot be overridden (Actions and Overrides); the most dangerous flow options need admin (Handler-level narrowing); production refuses to start with authentication offThe startup checks apply only when HEGEMONY_ENVIRONMENT says production; each route is not yet tested against each role over HTTP

TB2: Identity ​

Keycloak is the single trust anchor: every user, local or brokered from an outside provider, reaches the API with a token the realm signed.

STRIDEThreatControls in placeResidual risk
SSomeone guesses or reuses a passwordBrute-force lockout, password policy, no self-registration, a one-time code for admins (Keycloak Security Features, Multi-factor authentication); PKCE with S256 (Sign-in code exchange)Operator: users who sign in through an outside provider get their second factor there
TA token is forged or its signing keys are swappedThe API validates one issuer and fetches its keys from the realm (Federated identity)The API reaches Keycloak in plain text on the compose network
EAn identity-provider group grants an organization role it should notGroup mappings are managed by organization or platform admins; manual memberships are never changed by them; every change is audited with source: idp (Access decisions)Operator: who controls the provider's groups controls these roles
EA person who left keeps accessWith group sync on, memberships the claims no longer give are removed; tokens can be revoked per userLeaving the provider does not disable tokens or the user
RSign-in attempts cannot be tracedFirst sign-in and membership changes are auditedKeycloak's own events stay in Keycloak

TB3: Public Webhook Ingress ​

POST /hooks/{path_token} takes requests from anyone who can reach the API; it authenticates inside the handler. The one other such route is GET /dl/{token}/{filename}, a file download link a running step issued for a target: its token is a run token that opens one file for minutes (Download Links Issued by Steps). Who reads a link in that time can download the file, so links belong on HTTPS or on the management network (Object store data and backups).

STRIDEThreatControls in placeResidual risk
SA forged delivery starts a flowAn address with 256 random bits; HMAC-SHA256 over a timestamp and the body, HMAC-SHA512 for NetBox, or a bearer secret; signatures compared in constant time; an optional source address list (Security)Accepted: NetBox's signature carries no timestamp; its mitigations are documented (Signature Algorithm)
TA captured delivery is replayedA replay window on signed timestamps; an idempotency key answered with 409 (Idempotency)None beyond the row above
RA sender's deliveries cannot be tracedA delivery log per endpoint, and audit entries (Observability)None
DA flood costs database queries and secret lookupsAn instance-wide ceiling before the endpoint lookup, a per-endpoint budget before the body is read, a delivery limit (Public webhook endpoint)The budgets are per process; Operator: an external limiter in front of several replicas
EA delivery runs something other than its targetAn endpoint targets one flow of its own organization, and its runs pass the same admission as manual runsNone
EA payload makes the worker render a templatePayload values are data: never rendered, checked in full against the flow's fields, and dropped when the flow declares no such field (Templates in run inputs)None

TB4: Internal Service Network ​

The platform services and the bundled stores talk over the compose network. Temporal, PostgreSQL, OpenBao and zot publish no port.

STRIDEThreatControls in placeResidual risk
SSomething on the network calls the internal routes as the workerA required internal token, compared in constant time; known placeholders refused in production (Internal API Protection); internal routes take the organization from the run, never from the caller (Temporal / worker propagation)One shared token, no identity per service
I, TTraffic between services is read or changedNo published ports; OpenBao reached over verified TLS (Internal OpenBao)Temporal, PostgreSQL, worker to API and API to Keycloak are plain text
IA copy of a store's data is readSecret values only in the secret backend; state encrypted per version; no secret values in Temporal's history (Security Notes)PostgreSQL, the object store and Temporal's payloads rely on the host's disk encryption
T, RAudit entries are changed or removedEntries are written in the same transaction as the change; the table refuses updates and deletes except retention (Retention and immutability)Someone holding the database credential can still change it; no supported export to a SIEM
I, EAn admin console exposes every organizationThe Temporal, OpenBao and object store consoles are opt-in, and bound to loopback by default (Temporal console)Operator: open them only on demand
EA service's credentials reach more than it needsOnly the API, worker, scheduler and migration job load the platform env file; every other service, the ui included, gets only the settings it names (Platform environment and secret files); the worker reads secrets but writes them through the API (Secrets Written by Steps); only the API holds the registry signing key (Platform registry); OpenBao credentials expire and are bound to its network (What the bundled store already does)The API, worker, scheduler and migration job share one env file, so each holds credentials only some of them use
DA store is lostObject store backup and restore task; OpenBao unseals itself after a restartNo procedure for every store

TB5: Flow-Container Sandbox ​

Container steps run whatever image and commands a flow names, on a dedicated Docker-in-Docker daemon.

STRIDEThreatControls in placeResidual risk
EA flow container reaches the hostEvery flow container runs on the sandbox daemon, never the host's; the worker refuses a daemon that is not the attested sandbox (Flow-container sandbox); host-access options need admin (Handler-level narrowing)Accepted: the sandbox is containment, not a hard boundary, because dind runs privileged; Operator: a dedicated, patched host
E, TA step with host access controls other runs' containersOnly admin may give a step host access (Handler-level narrowing); other flow containers cannot reach the sandbox daemon's API, which dind serves on the compose network only (Flow-container sandbox)Accepted: a step with host access administers the whole sandbox; Operator: restrict who edits flows and review changes through git (Docker socket exposure)
IA container sends data where it should notEgress policies per flow and step, enforced inside the sandbox; widening one needs admin (Flow settings, Container Sandbox); each step's evidence records the policy it ran under and how it was enforced (Egress policy in the evidence)Operator: give flows an egress policy
S, EA step token is reused beyond its stepRun tokens are minted per step, stored as digests, revoked when the step ends, and scoped to one state or to the organization's registry paths (Terraform/OpenTofu State Backend, Platform Registry)Accepted: a build step may replace any tag of its organization's images; reference images by digest (Platform registry)
RA container cannot be traced to its runContainers carry the run, step and stack in their names and labels (Container Handler)None
DImages and volumes fill the sandbox's diskA maintenance job prunes dangling images and build cacheOperator: watch the dind-data volume (Host requirements)

TB6: Outbound to Devices and Integrated Systems ​

The worker logs in to devices, steps and the API reach external systems, and devices fetch files from the object store.

STRIDEThreatControls in placeResidual risk
SA device impostor receives credentialsShell and network-CLI steps check the device's and the jump host's SSH key, and store a first key before any credential is sent (SSH Host Keys)Accepted: first contact trusts whatever answers unless a key is pinned and the mode is strict; the documented limits apply
SA server impostor passes a step's TLS checkSteps trust the system store plus only the run organization's own trusted CAs, which admins manage; another organization's or the shared organization's list never applies, and a step's CA bundle pins its CAsOperator: add only CAs you control or have checked; a trusted CA can vouch for any name its certificates cover
ICredentials appear in output, evidence or logsThe values a step resolved are masked in its live output, evidence, result and the worker's log (Redaction of step output)Values resolved outside a step are not covered; Accepted: the documented limits of redaction
IRecorded device sessions are decrypted laterPost-quantum key exchange where the transport and device offer it (Network)Not on most devices yet
TAn integrated system feeds the platform hostile contentInventory files parsed safely and size-limited; the UI escapes what it renders (Trusted input boundaries)Operator: write access to git and inventory sources is editor access
I, EThe platform is used to reach internal addresseshttp.request refuses loopback, link-local, unspecified and multicast addresses; egress policies apply to worker-side steps too (Step handlers in the images); the API tests no registry login on private addressesOperator: an egress policy on flows that call http.request or netbox.*
EA step writes secrets or starts syncs beyond what was meantOff until an admin allows it, limited to named path prefixes or providers, and only for a running step whose handler declares it (Secrets Written by Steps, Inventory Syncs Started by Steps)None
REvidence claims a result that did not happenSteps record their evidence; container steps record the image digest they ran, and an install step whose SSH login fails is recorded as failedNone

TB7: Tenant and Privilege ​

Organizations share the instance; business data belongs to exactly one of them, and platform functions belong to platform admins.

STRIDEThreatControls in placeResidual risk
IOne organization reads another's dataAn organization on every row, explicit filters with a session-level safety net, cross-organization reads answered as missing, and tests that block an unclassified model (Query scoping, Cross-org integrity)A shared secret backend's paths outside orgs/<slug>/ are readable by every organization, and every secret backend is available to every organization (Multi-tenancy)
IA flow resolves another organization's secretsPaths namespaced per organization and checked by the worker before the backend is asked; env() and file() refused in organization content (Runtime template enforcement)Accepted: shared-organization secrets are readable by every tenant that can use them (Shared organization secrets)
TA tenant changes shared contentShared-organization rows are read-only to other organizations, refused at flush (Shared organization)None
EAn organization admin acts across the platformRoutes are classified organization or platform; platform routes need the realm admin role (Route Scope)Accepted: a revoked membership is honored within 30 seconds (Caching)
EA run input reads secrets the caller may notA templated run input needs the permission to edit the flow and may not use secret(), env() or file(); a parent flow's values reach its child as data (Templates in run inputs)Accepted: a run-input template can read organization variables, and a variable's value may call secret(), which the flow's own steps can read too
EOne person runs and approves the same changeapprover is separate from editor and operator (Separation of Duties)Admins and tokens with both scopes can approve their own runs; no multi-approver option

TB8: Code Supply ​

What runs in the processes: the platform's code, its dependencies, the first-party plugins, and the images that carry them.

STRIDEThreatControls in placeResidual risk
TA tampered or unexpected plugin or extension runsPlugins are installed into the API and worker environments by the deployment operator, never through the application (Installed Plugins); extensions stay off until a platform admin enables them, and conflicting ones are refused (Extensions)Plugins load with no allowlist or hash check, and installed extensions' code runs at discovery
TA published image is not what was builtEach image is pushed by digest, scanned at that digest, and only then tagged; base images are pinned by digest (Release pipeline)Images are signed and attested once the SIGN_IMAGES repository variable is set, and images released before then stay unsigned; the release workflow installs its own toolchain without a lockfile
I, EA dependency carries a known vulnerabilityBandit, pip-audit, Semgrep and gitleaks on every pull request (enforced gates); a bill of materials per image (SBOM)New vulnerable dependencies not blocked at review; automatic update pull requests cover only container images and plugin pins, with no written patch policy; the bills of materials have known gaps (SBOM); weekly checks miss one image
I, EA cached package layer retains a known vulnerability after a fix is releasedRelease builds refresh the Debian package upgrade layers for API, worker, scheduler and egress-nflog on every run and retry; scheduled image scans refresh the three Python images they build. Trivy blocks publication on fixable HIGH/CRITICAL findings (Release pipeline)Findings without an available fix remain in the non-blocking report; local builds need a new SECURITY_PATCH_REFRESH build argument to refresh cached upgrades; operators must deploy the patched release
TAn unreviewed change reaches a releaseHuman review and DCO sign-off on every pull requestRelease tags are not signed
AllA fixed vulnerability stays in deploymentsA private reporting and disclosure process (SECURITY.md)No long-term-support line is named yet (Supported versions); the platform does not tell admins that a security update is available

TB9: Host ​

The containers run on a host the deployment operator controls; some of them hold rights on that host.

STRIDEThreatControls in placeResidual risk
EA compromised worker takes over the host through the Docker socketThe socket is mounted for one query, deriving the worker id, and no flow container can reach it (Docker socket exposure)The mount itself remains; Operator: a dedicated host or a filtering socket proxy
EA compromised platform container has more rights than it needsThe API, worker and scheduler images run as an unprivileged user; the bundled OpenBao drops every capability and runs read-onlyThe same settings for the platform's own containers, and a non-root UI
IPlatform credentials are read from the hostThe OpenBao seal key is readable only by OpenBao; the registry signing key is given to the API aloneOperator: protect the env file, the volumes and the recovery keys (What you still have to decide)
DThe stack does not come back after a rebootRestart policies and fail-fast dependencies (Restart policy)One host
REvents cannot be ordered across servicesTimestamps on every audit entry and run eventOperator: NTP on every host (Time synchronization)

Operator Responsibilities ​

A self-hosted deployment is secure only with these in place. The production checklist is the full list.

Keeping This Assessment Current ​

Revisit this page, in the same pull request, when a change:

  • adds an entry point: a route with the public, custom or internal policy, a published port, or a new inbound protocol;
  • adds or moves a trust boundary: a new service or network, a change in privileges (privileged mode, capabilities, mounted sockets), or a change in which component holds a credential;
  • adds, replaces or removes a bundled third-party component;
  • adds a plugin subsystem or a way for extensions to run code;
  • removes a residual risk this page names, or adds one.

Also revisit it before each release, and after a vulnerability that touched a boundary has been disclosed. Record each review below.

Its entry in docs/docs-map.yaml makes the freshness gate flag this page when a pull request changes the production compose files and overlays, the published images' Dockerfiles, the UI's nginx or the HTTPS proxy configuration, the files that authenticate requests and classify routes, the public webhook router, or the plugin and extension loaders. Such a pull request updates the page or states why it does not need to (Docs-Not-Needed).

DateReviewWhere
2026-10-15First assessment, against develop at 6ffe7de7The pull request that added this page

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].