Personal Data Inventory
This page lists every place a Hegemony installation keeps data about people: what is stored, where, why, and for how long. Use it for your records of processing (GDPR Article 30) and for a data protection impact assessment (Article 35). It describes the software as shipped. A period given below is the default; "kept until deleted" means the platform has no retention control for that data, so it stays until someone deletes it.
Who controls the data
A self-hosted installation is run by the organization that deploys it. That organization decides which people, devices and sources the platform handles and how long the data stays, so it is the controller of that data. The Hegemony project does not operate installations and receives none of this data: the software reports no usage or telemetry to the project. Data leaves an installation only for systems its operator configures: the identity provider, inventory sources, notification destinations, Git repositories, and log or trace collectors.
Whose data
| People | How they appear |
|---|---|
| Platform users | Their account, organization roles, tokens, and the actions recorded under their name. |
| People named in inventory sources | Contacts, journal authors, and free-text fields an inventory provider syncs. |
| Notification recipients | Addresses in notification destinations. |
| Callers of the platform | The network address and user agent of whoever sends a request or a webhook. |
| People in device or step output | Whatever devices, scripts and containers print: local accounts, log lines, descriptions. |
At a glance
| Data | Stored in | How long, by default |
|---|---|---|
| User accounts | users | Kept; no API deletes a user |
| Organization memberships | org_memberships | Until the membership is removed |
| Personal access tokens | personal_access_tokens | Kept after revocation or expiry |
| Audit log | audit_logs | Forever: HEGEMONY_AUDIT_RETENTION_DAYS is unset |
| Who created or changed an object | Actor columns on most tables | As long as the row |
| Approvals, comments and run events | approval_requests, step_runs, run_events | With the run; run event pruning is off |
| Run inputs, output and evidence | runs, step_runs, run_events, run_artifacts, object store | Until the run is permanently deleted |
| Free text | flow_definition_versions, ssh_host_keys, ssh_host_key_exemptions, variables, description columns | As long as the row |
| Notification recipients | notification_destinations | Until the destination is permanently deleted |
| Webhook source addresses | webhook_deliveries | Until the endpoint is permanently deleted |
| Inventory | devices, sites, inventory_objects | Until deleted; rows a provider drops are kept as stale |
| Managed Terraform state | tf_states, tf_state_versions, tf_state_events | 50 versions and 500 lock activity entries per state |
| Configuration Exchange and sync history | config_exchange_runs, config_exchange_import_plans, git_sync_history, platform_sync_runs | Kept until deleted |
| Files | Object store | Until deleted |
| Registry images | The registry's bucket in the object store | Unused cached copies and old build tags: 30 days; other images until deleted |
| Credentials | Secret store, registry_credentials | Until deleted |
| Session tickets | API memory or Redis | Until used, five minutes at most |
| Workflow history | Temporal's database | While the workflow runs, then 7 days in the bundled stack |
| Identity provider | Keycloak's database | Accounts until deleted; sessions 30 minutes idle, 10 hours at most |
| Logs and traces | Container logs | As the Docker logging configuration keeps them |
| Browser storage | The user's browser | Tokens until the tab closes |
Soft-deleted objects (deleted, but restorable) keep everything listed here until they are permanently deleted.
User accounts
- Fields: the identity provider's subject ID (
sub), username, email address, whether the account is active, when the row was created and changed, andlast_login_at: the last time the API saw a request carrying the user's identity-provider token, refreshed at most once a minute. Adisplay_namecolumn exists and is left empty. - Where: the
userstable. The row is created at the user's first sign-in, or earlier when an admin adds them to an organization by subject ID (the username is then the subject ID until they sign in). Username and email are refreshed from the token at sign-in. - Why: to tie organization roles, tokens and audit entries to a person. The last login feeds the access review export, which is built on request and not stored.
- How long: kept. No API deletes or deactivates a user; removing the account in Keycloak stops the sign-in but leaves the row.
Organization memberships
- Fields: the user, the organization, the role (
admin,editor,operator,approver,auditororviewer), how it was granted (manualoridp), and when it was created and changed. - Where:
org_memberships. - Why: authorization.
- How long: until an admin removes the member, identity-provider group sync removes it, or the organization is deleted.
Personal access tokens
- Fields: the owner's username (
user_username), the issuing admin's username (issued_by_username), the token's name and scopes, and when it was created, last used, expires and was revoked. The token itself is stored only as an HMAC digest and a short display prefix. - Where:
personal_access_tokens. - Why: API authentication, and showing who holds which token.
- How long: kept after revocation or expiry. Revoking sets
revoked_at; no API deletes the row.
Audit log
- Fields: for every entry, the actor's subject ID and username (
actor_sub,actor_username) and how they authenticated; the client address (client_ip) and user agent; the object's display name; anddetails_json, with the request method and path and the object's state before and after the change. Snapshots carry whatever the object holds: a user's email address (user.provisioned), a notification destination's recipients, token owners, registry login names, an approval's comment. Credential values are redacted (What the details hold). - Client address: the address of the connection. Behind a proxy that is the proxy, unless
HEGEMONY_TRUST_PROXY_HEADERSis on, in which case theX-Forwarded-Forentry written by the outermost trusted proxy is stored. Public webhook calls store a masked address: the first three octets of an IPv4 address, or the /64 prefix of an IPv6 one. - Where:
audit_logs. Entries outlive their organization: deleting an organization leaves its entries in place. - Why: accountability and security evidence: who changed what, and which requests were refused.
- How long: forever by default. Set
HEGEMONY_AUDIT_RETENTION_DAYSfor a rolling window; the dailyaudit_log_retentionmaintenance job then deletes older entries (Retention and immutability).
Actor columns
Most tables record who created, changed or deleted a row. The value is the person's subject ID or username. Actors that are not people appear as system, webhook, flow, pat:<id> (a personal access token) or run:<run id>/<step id> (a run step).
| Columns | Tables |
|---|---|
created_by, updated_by, deleted_by | sites, devices, inventory_objects, inventory_provider_configs, variables, flow_definitions, runs, schedules, git_repositories, platform_sync_profiles, webhook_endpoints |
created_by, updated_by | tf_states, secrets, secrets_backends |
created_by | flow_definition_versions, flow_attachments, flow_attachment_versions, ssh_host_keys (for an accepted key, the member who accepted it), ssh_host_key_exemptions, trusted_cas, tf_state_versions |
updated_by, a username | permission_overrides, permission_action_overrides, permission_step_up_overrides, platform_extensions, platform_setting_overrides |
decided_by, a username | approval_requests |
requested_by | git_sync_history, platform_sync_runs |
actor_user_id | platform_sync_runs, config_exchange_import_plans |
actor | config_exchange_runs, tf_state_events (with holder, who held the state) |
locked_by | tf_states |
created_by, created_by_sub | registry_image_transfers (registry extension) |
updated_by, updated_by_sub | registry_retention_policies (registry extension) |
- Why: to show on each object who made it and who last changed it.
- How long: as long as the row.
Approvals, comments and run events
- Fields: an approval decision stores the decider's username (
approval_requests.decided_by) and comment (decision_comment). Both are repeated in the approval step's result (step_runs.result_json) and in run events whose messages name the decider and quote a rejection's comment. Pausing and resuming a run add run events naming who did it, with the actor inattrs. - Where: the tables named above.
- Why: the run's history, and evidence of who approved what.
- How long: approvals, step results and run events stay with their run until it is permanently deleted: once a run is deleted, an admin can delete it permanently, which removes its steps, events, artifacts and approvals. Run event pruning is off by default (
HEGEMONY_MAINTENANCE_RUN_EVENT_PRUNING_INTERVAL_SECONDSis0). Set it above0and therun_event_pruningjob deletes the events of finished runs older thanHEGEMONY_MAINTENANCE_RUN_EVENT_RETENTION_DAYS(90 by default).
Run inputs, output and evidence
- Fields:
- Inputs: what the person starting the run entered (
runs.submitted_inputs_json,resolved_inputs_json,params_json). A run started by a webhook takes the request body as its parameters (or the body'sparamsobject, when it has one), so they hold what the sender put there; NetBox's webhook body, for example, names the NetBox user who made the change. - Output: step log lines (
run_events.message), step results and errors (step_runs), and evidence (run_artifacts: text and JSON in the database, files in the object store). They hold whatever devices and steps print: configurations with local user accounts, session listings, log lines, interface descriptions, container output.
- Inputs: what the person starting the run entered (
- Why: the run's history and evidence of the change it made.
- How long: until the run is permanently deleted, which also deletes its files from the object store. A binary artifact's file can be purged earlier from the Binary Artifacts page; its row stays. Run events follow the pruning setting above.
Free text
Some fields hold whatever people type, which can name or describe a person. They live with their own objects, not with runs, so deleting a run leaves them in place.
| Field | Stored in | How long |
|---|---|---|
| Flow version messages | flow_definition_versions.message | Until the flow is permanently deleted, which deletes its versions |
| An admin's comment on a pinned SSH host key | ssh_host_keys.comment | Until an admin forgets the key or the organization is deleted |
| An admin's comment on a host exempt from the SSH host key check | ssh_host_key_exemptions.comment | Until an admin removes the exemption or the organization is deleted |
| Variable values, stored in clear text | variables.value | Until the variable is permanently deleted |
| Descriptions | description on flow_definitions, sites, variables, webhook_endpoints, platform_sync_profiles, secrets, secrets_backends, registry_credentials and organizations | As long as the row |
- Why: to explain objects and changes to the people who use them.
- How long: as in the table. A soft-deleted object keeps its text until it is permanently deleted.
Notification recipients
- Fields: a destination's configuration (
notification_destinations.config_json): for email, theto,ccandfromaddresses; for an outgoing webhook, its URL and headers. A Shoutrrr URL is a secret reference, so its address is in the secret store. - Messages: notifications send run details to these destinations and, for approval events, the decider's username and comment. A message is outside the platform once delivered.
- Copies: in audit snapshots, in workflow history (each dispatch carries the destination's configuration), and in Git or an export file when Platform sync or Configuration Exchange exports the configuration.
- Why: to deliver notifications.
- How long: until the destination is permanently deleted.
Webhook deliveries
- Fields: the caller's address (
webhook_deliveries.source_ip), stored in full, with the delivery time, the idempotency key, a hash of the body (not the body), the response status and error, and the runs it started. It is the address of the connection that delivered the request, so behind a proxy it can be the proxy's;HEGEMONY_TRUST_PROXY_HEADERSdoes not apply to it. The audit entries for the same delivery keep only a masked address (source_ip_masked). - Why: troubleshooting, replay protection, and evidence for source address allowlists.
- How long: until the webhook endpoint is permanently deleted. Deliveries have no retention control of their own.
Inventory
Network devices are not people, but inventory sources often name people.
- Fields:
- Devices (
devices): name, hostname, management addresses, tags, and the provider's facts indescriptiveandattributes. From NetBox these include the tenant, serial number, asset tag, location, latitude and longitude, description, comments, config context and custom fields. - Sites (
sites): name, description, andlocation, which can be a street address. - Other object types (
inventory_objects): every family the provider serves, unless the provider's object-type selection or inventory filters leave it out. The NetBox provider serves contacts (name, title, phone, email, postal address, comments), contact assignments, and journal entries (the author's NetBox user ID and the comment). It never reads NetBox's users, tokens or change log. - Devices and sites created by hand hold what people type into them.
- Devices (
- Copies: a run's workflow input carries each target device's facts, and Configuration Exchange and Platform sync exports include local devices and sites.
- Why: targeting runs and showing the inventory.
- How long: until deleted. A row its provider stops reporting is marked stale, not deleted.
Managed Terraform and OpenTofu state
- Fields: the lock document the tool sends (
tf_states.lock_info), whoseWhofield is the user and host name of the machine that took the lock; who holds the lock (locked_by); who wrote each version (tf_state_versions.created_by); and the lock activity, naming who acted and who held the state (tf_state_events.actor,holder). The state itself, stored encrypted, holds whatever the managed resources contain. - Why: locking, version history, and the state's lock activity.
- How long: 50 versions per state (
HEGEMONY_TF_STATE_KEEP_VERSIONS) and 500 lock activity entries (HEGEMONY_TF_STATE_KEEP_EVENTS); the state and its lock until the state is deleted.
Configuration Exchange and sync history
- Fields: who ran an import, export, plan or apply (
config_exchange_runs.actor); who made a plan (config_exchange_import_plans.actor_user_id) and the uploaded bundle itself (content_bytes); who requested a flow's Git sync (git_sync_history.requested_by) or a platform sync (platform_sync_runs.requested_by,actor_user_id). Bundles and exports carry configuration, including notification recipients, registry login names, variable values, local devices and sites, the devices and repository files (by path) a flow's steps use, and each secret's name, description, backend, path and key names (never its values). A bundle uploaded for import may also carry secret values; the plan made from it keeps the bundle as uploaded until the plan is deleted. Git commits the platform makes are authored asHegemony <hegemony@noreply>, not as the user. - Members in YAML exports: every YAML export from Configuration Exchange carries the whole organization directory, whichever organization is active: every organization's members, each with their subject ID, username, role, and whether the role was granted by hand or by the identity provider, and each organization's identity-provider group mappings. By default only platform admins may export (
config_exchange:execute). The platform keeps no copy of an export, only its size inconfig_exchange_runs, so give downloaded files their own access and retention controls. Platform sync's Git exports and a flow's own Git sync carry no organizations or members. - Why: the history of configuration changes.
- How long: kept until deleted, expired plans included.
Files
- Fields: whatever people upload to file repositories, and the files runs keep as evidence. The database keeps file names, sizes and hashes (
stored_files,run_artifacts). - Where: the object store: the bundled S3 gateway, or the S3 service you point the platform at.
- Why: serving files to devices and steps, and keeping run evidence.
- How long: until deleted. Run evidence follows its run (above).
Registry images
With the registry extension, the platform registry keeps container images, which hold whatever their builders put in them.
Fields: the images build steps push, the images admins import, and the copies of upstream images that steps cache.
Where: the object store, in the registry's bucket (
HEGEMONY_REGISTRY_BUCKET,hegemony-registryby default).Why: serving images to steps.
How long: a daily cleanup (
registry:image_retention) deletes what the rules on Artifacts → Container Images → Retention remove. Until a platform admin saves other rules:- a cached copy nobody pulled or pushed for 30 days is deleted (
HEGEMONY_REGISTRY_CACHE_RETENTION,720h), except the most recently used copy of each repository; - in an organization's own repositories, a
run-<id>tag thatcontainer.buildgave an image is deleted 30 days after its push, except the 10 newest of each repository. An image goes with its last tag; one that also has a tag people set stays under it; - every other image stays until someone deletes it.
The cleanup keeps an image a run that has not finished still names, and an image pulled within the last day. A rule of 0 days never deletes (Retention).
- a cached copy nobody pulled or pushed for 30 days is deleted (
Credentials
- Fields: secret values, which can be a person's own login; the login name for an external container registry (
registry_credentials.username). - Where: values in the secret store (the bundled OpenBao or your own); the database keeps only names and paths, and the registry login name. Configuration Exchange and Platform sync exports carry a secret's name, path and key names, never its values.
- Why: reaching devices and services.
- How long: until deleted.
Settings → Platform Configuration shows the platform's own settings to platform admins. It holds no personal data beyond who last changed a setting stored there (see Actor columns), and it never shows a secret setting or a password inside a URL: the API sends only whether a secret is set. No secret can be stored there, and its export leaves secrets out.
Session tickets
- Fields: the signed-in identity (subject ID, username, email, roles and groups) bound to a single-use ticket the UI uses for live event streams.
- Where: the API's memory by default, or Redis when
HEGEMONY_BFF_TICKET_STOREisredis. In Redis the identity is encrypted with a key derived from the ticket and entries are named by hashes, so the store holds no readable identity and no usable ticket. - Why: to authenticate event-stream connections, which cannot send an authorization header.
- How long: until the ticket is used, five minutes at most.
Temporal workflow history
- Fields: a run's workflow input (its parameters and resolved inputs, the flow graph, and each target device's inventory facts); step inputs and results; approval decisions (the decider's username and comment); and each notification dispatch, with the destination configurations (recipient addresses) and the run and approval details it reports. Secret values never enter workflow history (Secrets Management).
- Where: the Temporal server's database (
postgres-temporalin the bundled stack). - Why: durable execution of runs and notifications.
- How long: while the workflow runs (an approval can hold a run for days), then for the namespace retention: 7 days in the bundled stack, set when the namespace is created (Temporal Retention & History Limits).
Keycloak
- Fields: user accounts (username, email, first and last name, password hash, and one-time-code credentials, which users with the
adminrole must enroll), group and role assignments, sessions with the client address and times, and brute-force protection's record of recent failed sign-ins. The shippedhegemonyrealm does not enable login or admin events; when an administrator enables them, Keycloak stores each with the user, client address and time. - Where: Keycloak's database (
postgres-keycloakin the bundled stack). With user federation or an external identity provider, Keycloak also keeps copies of the imported users. - Why: sign-in.
- How long: accounts until an administrator deletes them in Keycloak. Sessions end after 30 minutes idle or 10 hours (
ssoSessionIdleTimeoutandssoSessionMaxLifespanin the shipped realm). An offline session, which only a client that asks for offline access gets (the web app does not), ends after 30 days idle (offlineSessionIdleTimeout). Events, when enabled, as long as the realm's event settings keep them.
Logs and traces
| Source | What it records about people |
|---|---|
| API access log | Client address, method, path with its query string, and status of each request, except health checks and internal polls. The value of a ticket query parameter, the token in a webhook's URL and the token in a file download link (/dl/…) are replaced with [redacted]. |
| UI nginx | The nginx image's default access log: client address, request line, status, referrer, user agent and X-Forwarded-For. Requests for file download links (/api/dl/…) are logged neither there nor in the error log, because the token in their path is their credential. |
| Application log | INFO lines when a local user is provisioned (subject ID and username), joins the default organization, or has identity-provider memberships reconciled; WARNING lines naming a user who was denied access; INFO lines naming a user asked to sign in again before a sensitive action; the worker's INFO line naming who decided an approval; webhook warnings with the caller's address. The SSH libraries behind the device transports (scrapli, netmiko, paramiko, asyncssh) stay at INFO even when HEGEMONY_LOG_LEVEL is DEBUG, so what a device session sends and receives, credentials and download-link tokens included, is not logged. |
hegemony.audit logger | Refused requests that name no user (client address and user agent), audit entries a rollback lost, and every audit entry when HEGEMONY_AUDIT_LOG_MIRROR is on. |
| Traces | With OTEL_EXPORTER_OTLP_ENDPOINT set, as the production example sets it, API request spans carry the client address, user agent and path; the bundled collector prints sampled spans to its log. |
| Other services | Keycloak, Temporal, OpenBao, the S3 gateway and the platform registry write their own logs. |
- Where: each container's standard output.
- Why: operating and troubleshooting the platform.
- How long: the compose files set no logging options, so the Docker daemon's logging configuration decides. Ship the logs to a store whose retention you control.
In the browser
- Session storage: the identity provider's tokens, which carry the username, the email and when the user last signed in; cleared when the tab closes.
- Local storage: the active organization and the theme, keyed by the user's subject ID, and display preferences.
- Cookies: Keycloak's own session cookies.