Audit & Compliance

Audit trail and compliance features of the Polycrate API: CLI activity audit, created_by_component, authentication audit, optional lifecycle activities, action run tracking and Prometheus metrics.

Audit & Compliance

Overview

The Polycrate API offers features that are relevant for audit trails, compliance requirements and forensic analysis. Administrators, IT managers and compliance officers can trace who performed which actions when, and through which channels resources were created.

CLI Activity Audit

What is logged?

The Polycrate CLI sends certain activities to the API, where they are persisted:

Activity Trigger Stored data
SSH session polycrate ssh (start and end) Host, workspace, user, duration, exit code
Workspace sync polycrate workspace sync / polycrate git sync Workspace, branch, commit, sync result, user

Prerequisites

  • Authentication: The user must be signed in with a valid API token. Only authenticated activities are logged.
  • CLI configuration: API integration must be enabled (api.enabled: true, api_key set)

Benefits for compliance

  • Complete audit trail: Who accessed which hosts via SSH and when? Who ran workspace syncs?
  • User attribution: Every activity is assigned to a user (created_by) – no anonymous actions
  • Resource linking: SSH sessions are linked to host and workspace; workspace syncs to the affected workspace

Where to view?

Activities appear in the Activity overview of the Polycrate API. They can be filtered and exported via the API (e.g. for compliance reports).

created_by_component

What does it mean?

Every ManagedObject (e.g. S3 bucket, K8sApp, credential) stores through which channel it was created:

Value Meaning
CLI Via the Polycrate CLI (e.g. workspace sync creates a bucket)
Operator By the Polycrate Operator (e.g. Kubernetes resources)
API Via the web interface or REST API (manually by a user)

Benefits for compliance

  • Source analysis: "All buckets created via CLI" – e.g. for automation audits
  • Manual vs. automated changes: Distinction between manual configuration and infrastructure-as-code
  • Reporting: Filters and reports by creation source are possible

Where to view?

  • List views: Filter "Created by component" (CLI, Operator, API)
  • Detail views: Column or field "Created by component" in the object details
  • API: Filter created_by_component on all ManagedObject lists

Authentication Audit

All authentication events are logged:

Event Logged data
Login (SSO) User, IP, time, provider
API key created User, key name, time
API key used Key ID, endpoint, IP, time
API key revoked User, key ID, time
Failed login IP, time, reason

→ Authentication

Optional Lifecycle Activities (from 0.14.3)

Since version 0.14.3, creation, deletion and state-change activities can be switched on and off via the system configuration. By default they are disabled to reduce database and cleanup load (especially in dev environments).

SystemConfig settings

Setting Default Description
Create Creation Activities off Activity on object creation
Create Deletion Activities off Activity on object deletion
Create State Change Activities off Activity on status/state change

Available under: System Configuration → category Timing & Policy Settings.

Cleaning up existing activities

Management command for deleting old activities (e.g. for prod cleanup):

# Dry run: creation, deletion, state_changed older than 7 days
python manage.py delete_old_activities 7 --kind creation,deletion,state_changed --dry-run

# Actually delete (with confirmation)
python manage.py delete_old_activities 7 --kind creation,deletion,state_changed

# All activities older than 30 days (without kind filter)
python manage.py delete_old_activities 30 --no-confirm

Block config: clear_activities

The polycrate-api block supports an optional clear_activities section in block.config. When enabled, the block automatically runs delete_old_activities before the migrate job.

clear_activities:
  enabled: false
  dry_run: false
  older_than_days: 7
  kinds: "creation,deletion,state_changed"
  batch_size: 5000

Action Run Tracking

Complete history of all CLI executions:

  • Who ran which action when in which workspace?
  • Exit codes, logs, duration
  • No manual record-keeping required – the CLI sends automatically

→ Polycrate API Overview

Prometheus Metrics for Monitoring

The API exposes Prometheus-compatible metrics under /api/v1/metrics. They can be used for monitoring, capacity planning and compliance dashboards (e.g. VictoriaMetrics, Grafana).

→ Prometheus Metrics