Auditable Operations: SSH Sessions and CLI Activities with Polycrate API

TL;DR

• Polycrate not only logs Action Runs (Ansible playbooks) but also SSH sessions, workspace syncs, and CLI instances – all centrally accessible via the Polycrate API.
• SSH session logging answers the classic incident response question: Who accessed which server via SSH, when, for how long, and with what exit code?
• Workspace sync logs capture Git branch, commit SHA, encryption status, and sync results, making changes to automation traceable and audit-proof.
• The Polycrate API allows for centralized management of encryption keys for encrypted workspaces – a crucial component for NIS-2 and GDPR-compliant operational processes.
• ayedo provides an auditable operations stack with Polycrate, the API, and accompanying platform engineering services that can be integrated into existing compliance and security processes.

Why Operations Audit is a Top Priority Today

Both NIS-2 and GDPR increase the pressure for traceable, documented IT operational behavior:

• The NIS-2 Directive (EU) 2022/2555 must be transposed into national law by EU member states by 17.10.2024. It requires, among other things, technical and organizational measures for logging and monitoring security-relevant events.
• The GDPR (General Data Protection Regulation) has been in effect since 25.05.2018 and requires accountability: You must be able to demonstrate who accessed or changed systems processing personal data and when.

For orientation on regulatory frameworks and how to operationalize them, see the Compliance Compass landing page.

In security incidents, one of the first questions that almost always arises is:

Who accessed which server via SSH and when?

With a classic tool mix – a bit of Ansible, some manual SSH, local ~/.bash_history, scattered syslog entries – this question is often only answerable with great effort, sometimes not at all.

Polycrate addresses this precisely: It makes Ansible, SSH access, and workspace synchronization auditable – without your team having to deploy additional agents or special tools on all servers. Everything runs through the Polycrate CLI and the Polycrate API, see API documentation and SSH integration.

Polycrate as the Audit Backbone for Your Operations

Before diving into the details of the audit trail, let’s briefly outline what Polycrate generally offers:

• Dependency problem solved: Ansible, Python, kubectl, Helm & Co. run in a container managed by Polycrate. You don’t need to install Ansible locally, juggle Python versions, and face fewer supply chain risks. Everyone on the team works with the same, reproducible toolchain – a core principle of good platform engineering.
• Structure instead of playbook sprawl: The block model gives Ansible a reusable, versionable structure. Blocks can be shared via OCI registry or PolyHub – including all audit data provided by the API.
• Workspace encryption: Secrets in the workspace are encrypted with age, see workspace encryption. No external vault needed – an important detail for GDPR and NIS-2 audits.

On this basis, Polycrate adds an additional layer: a central audit trail for all operational actions, accessible and integrable via the Polycrate API.

Beyond Action Runs: What Really Happens Day-to-Day

In many teams, the day-to-day looks like this:

• Planned changes run via Ansible playbook (or CI pipeline).
• Urgent hotfixes or debug sessions happen “just quickly” via SSH.
• Workspaces and inventories are irregularly updated via git pull or distributed via copy/paste.

With plain Ansible, at best you have:

• Log files on the control host (if you have configured logging cleanly).
• SSH logs on the target systems – distributed, differently configured, sometimes rotated or deleted.
• No central picture of who executed which operation with which tool version.

Polycrate fills these gaps:

1. Action Runs (Ansible playbooks) are centrally logged.
2. SSH sessions started via Polycrate generate their own audit entries.
3. Workspace syncs are logged with Git metadata and encryption status.
4. CLI instances report to the API – including Polycrate version and hostname.

This creates a complete operations history, where automated and manual interventions appear equally.

SSH Session Logging: Finally an Answer to “Who Accessed via SSH and When?”

SSH is the classic for incident response questions – and one of the biggest blind spots in many environments.

With Polycrate, an SSH session typically runs like this:

polycrate ssh server01.acme-corp.com

Details on the SSH function can be found in the SSH documentation.

When you use SSH via Polycrate, the following happens in the background:

• At the start of the session, an audit event is sent to the Polycrate API.
• At the end of the session, another event is sent, including:
  • Exit code
  • Duration
  • Possible termination reason (timeout, network error, etc.)

Typical dataset in the API (simplified example):

{
  "type": "ssh_session",
  "id": "c5f4411d-641a-4b0a-8ee6-291d1c725c20",
  "workspace": "acme-corp-automation",
  "user": "alice",
  "cli_instance_id": "cli-8f3891b2",
  "host": {
    "inventory_name": "server01.acme-corp.com",
    "ansible_host": "10.0.12.34",
    "hostname_reported": "srv-web-01"
  },
  "started_at": "2026-03-24T10:12:03Z",
  "ended_at": "2026-03-24T10:27:45Z",
  "duration_seconds": 942,
  "exit_code": 0
}

This allows you to specifically ask in an incident:

• What SSH sessions occurred on server01.acme-corp.com during period X–Y?
• Who logged in?
• Which workspace version was in use?
• Were Ansible action runs executed in parallel?

Important:
The SSH connection itself still runs via SSH client, not through an API tunnel. Polycrate uses the API only for the audit event – no additional agent installation on the target systems.

In comparison, with plain Ansible you would have to:

• Set up central SSH jump host logging,
• Configure log rotation and aggregation,
• Correlate user identities with technical accounts,
• and still have no direct reference to workspaces and Ansible runs.

With Polycrate, a consistent entry point (polycrate ssh) is sufficient – the rest happens automatically.

Workspace Sync Logging: Who Pulled Which Playbook in Which Direction?

Polycrate workspaces are the unit in which you manage blocks, inventories, and configuration, see workspaces documentation.

Typical workflow:

polycrate workspace sync

This usually involves a Git pull/push or a sync against a central repository. Polycrate logs via the API, among other things:

• Workspace name
• Git remote URL (pseudonymized/shortened, depending on configuration)
• Git branch
• Commit SHA before and after the sync
• Encryption status:
  • Are secrets in the workspace encrypted?
  • Was a key rotation event detected?
• Result: Success, conflict, abort, error message

Example of an API entry:

{
  "type": "workspace_sync",
  "id": "0c19e60f-9d4f-4f3b-b9fb-909cb7ab2f37",
  "workspace": "acme-corp-automation",
  "user": "bob",
  "git": {
    "branch": "main",
    "before_sha": "dc3a1f7",
    "after_sha": "a42b9e1"
  },
  "encryption": {
    "enabled": true,
    "key_id": "age1qg4...",
    "status": "ok"
  },
  "result": "success",
  "timestamp": "2026-03-24T08:02:11Z"
}

This is invaluable for compliance and audit security:

• You can see when new playbook versions arrived in the workspace.
• You can link action runs and SSH sessions with the used commit.
• You can demonstrate that secrets in the workspace were encrypted when a change was rolled out.

With plain Ansible, you would have to correlate external Git logs, CI logs, and manual documentation.

CLI Instance Tracking: Which Polycrate Version is in Use Where?

A frequently underestimated question in audits is:

Which version of the operations tools is in use – and where?

Polycrate answers this by having each CLI instance regularly report to the API, e.g., when starting an action, a sync, or an SSH session. A dataset includes, among other things:

• cli_instance_id
• Polycrate version (cli_version)
• Operating system and architecture
• Hostname or anonymized host ID
• Workspace references

Example:

{
  "type": "cli_instance",
  "id": "cli-8f3891b2",
  "user": "alice",
  "cli_version": "0.8.4",
  "os": "linux",
  "arch": "amd64",
  "hostname": "alice-laptop",
  "first_seen": "2026-03-22T09:00:00Z",
  "last_seen": "2026-03-24T10:27:45Z"
}

This allows you to:

• Ensure that security-critical CLI versions are rolled out,
• Identify old, vulnerable, or non-compliant configured versions,
• Show in the audit that only approved tool versions were used.

Encryption Key Management via API: Team-Wide Encryption Under Control

Polycrate encrypts workspace secrets with age, see workspace encryption. Instead of managing each workspace individually, you can use the API to:

• Manage key IDs and metadata (e.g., for team keys, project keys).
• Plan and monitor key rotation – including audit entries for when a workspace was elevated to a new key.
• Control access rights to encryption keys at the API level (e.g., only certain roles may create or delete keys).

In NIS-2 and GDPR contexts, this is crucial:

• You can demonstrate that sensitive configuration and credentials in the workspace are stored encrypted.
• You have an audit trail of who created, changed, or deactivated keys and when.
• You reduce the proliferation of locally stored key materials.

Concrete Example: A Patched Server with a Complete Audit Trail

To make this tangible, let’s look at a small but complete workflow:

• A workspace acme-corp-automation
• A block linux-patch that executes an Ansible playbook
• An inventory in the workspace root (inventory.yml)
• An admin who checks the server via SSH before and after the patch

Workspace Definition with API Configuration

# workspace.poly
name: acme-corp-automation
organization: acme

config:
  api_base_url: "https://polycrate-api.acme-corp.com"

blocks:
  - name: linux-patch
    from: linux-patch
    config:
      target_hosts: "all"

Further details on workspaces can be found in the workspaces documentation and best practices in the Polycrate best practices.

Block Definition for the Patch

# blocks/linux-patch/block.poly
name: linux-patch
version: 0.1.0
kind: generic

config:
  target_hosts: "all"

actions:
  - name: patch
    description: "Install security updates on Linux servers"
    type: ansible
    playbook: patch.yml

The block is located locally in the workspace (./blocks/linux-patch). In real setups, you could also source this block from a registry or PolyHub – always with explicit versioning, see registry documentation.

Inventory with Remote Hosts

# inventory.yml (workspace root)
all:
  hosts:
    server01.acme-corp.com:
      ansible_host: 10.0.12.34
      ansible_user: ubuntu
    server02.acme-corp.com:
      ansible_host: 10.0.12.35
      ansible_user: ubuntu

Polycrate automatically sets ANSIBLE_INVENTORY to this YAML inventory, see Ansible integration.

Important: We do not use hosts: localhost with connection: local, because that would only apply inside the Polycrate container.

Ansible Playbook for the Patch

# blocks/linux-patch/patch.yml
- name: Install security patches
  hosts: "{{ block.config.target_hosts }}"
  become: true
  gather_facts: false

  tasks:
    - name: Update package lists (APT)
      ansible.builtin.apt:
        update_cache: true
      when: ansible_facts.os_family == "Debian"

    - name: Install security updates (APT)
      ansible.builtin.apt:
        upgrade: dist
      when: ansible_facts.os_family == "Debian"

    - name: Update all packages (YUM/DNF)
      ansible.builtin.yum:
        name: "*"
        state: latest
      when: ansible_facts.os_family in ["RedHat", "Rocky", "AlmaLinux"]

The variable block.config.target_hosts comes directly from block.poly and is injected into the Ansible context by Polycrate, see Actions documentation.

Polycrate Run with Audit

Start the patch run with:

polycrate run linux-patch patch

What happens from an audit perspective?

1. The Polycrate CLI creates an Action Run entry via the API:
   • Workspace, block, action name
   • Start time, user, CLI version, inventory hosts
2. Ansible runs in the container; logs and exit status are linked to the Action Run.
3. When finished, the CLI sends the final status (success/failure, duration, affected hosts) to the API.

If the admin additionally connects via SSH to server01.acme-corp.com:

polycrate ssh server01.acme-corp.com

…additional SSH session events are created that you can later correlate with the patch run and the commit SHA from the last polycrate workspace sync.

In the Polycrate API backend, this yields a coherent picture:

• Workspace sync → new playbook version
• Action Run linux-patch/patch → rolled-out change
• SSH sessions → manual follow-up or debugging

More on how blocks, workflows, and actions interact can be found in the Blocks documentation and Workflows.

NIS-2 and GDPR: What the Audit Trail Covers – and What It Does Not

Polycrate helps you address core requirements from NIS-2 and GDPR:

• Demonstrability of changes: Who rolled out which infrastructure or configuration changes via Ansible and when?
• Logging of administrator access: SSH sessions are captured centrally, not only in scattered syslogs.
• Protection of credentials: Workspace encryption and API-based key management reduce the risk of plaintext secrets.
• Tool governance: CLI instance tracking supports proving that only approved tool versions are used.

It is equally important to state what is not in scope:

• Polycrate does not replace logging inside business applications (e.g. who changed data in a line-of-business system).
• Polycrate does not see commands that bypass it entirely (e.g. manual ssh from a terminal without the Polycrate wrapper).
• OS logs, network logs, and SIEM rules remain necessary – Polycrate adds complementary, highly structured data.

In practice, Polycrate is thus an important building block in a comprehensive audit and monitoring stack integrated with SIEM or GRC systems.

Polycrate vs. Plain Ansible: The Missing Protocol

With plain Ansible you could rebuild much of this:

• A central bastion where all admins log in to run playbooks.
• Shell scripts that log timestamps before and after ansible-playbook.
• Manual configuration of SSH logging and central syslog collection.
• A separate tool to link Git commits to deployments.

All of that is feasible – but it requires:

• significant manual effort,
• strong team discipline,
• and often remains fragile when new tools or workflows appear.

Polycrate brings these capabilities integrated:

• The containerized toolchain solves the dependency problem and gives you consistent execution environments.
• The block and workspace structure prevents playbook sprawl and makes automation shareable.
• The Polycrate API provides the full audit trail: Action Runs, SSH, syncs, CLI instances, key management.

You do not need to build extra infrastructure – only run your existing workflows consistently through Polycrate.

Frequently Asked Questions

Do I really capture every SSH session when I introduce Polycrate?

Polycrate captures all SSH sessions started through Polycrate (e.g. polycrate ssh host). If an admin runs ssh host directly in a terminal without Polycrate, the API does not see that session.

In practice you therefore establish a process:

• Administrator access to production systems generally goes through Polycrate.
• Direct SSH logins are organizationally prohibited or heavily restricted.
• Optionally, target systems enforce that only certain jump hosts are allowed, with Polycrate installed on them.

That makes Polycrate the natural entry point for operations – and the audit trail becomes complete.

How do I integrate the Polycrate audit trail into my central SIEM?

The Polycrate API offers structured JSON events for Action Runs, SSH sessions, workspace syncs, and more, see API documentation. Typical integration paths are:

• Pull: a central script or service periodically fetches new events and pushes them to the SIEM.
• Push: a small forwarder service subscribes to events (or polls incrementally) and forwards them in near real time.
• Mapping: in the SIEM, corresponding fields (user, host, workspace, etc.) are mapped to internal data models.

Because of the clear structure, Polycrate fits well into existing use cases such as “Privileged Access Monitoring” or “Change Tracking”.

Does CLI instance tracking store personal data?

The Polycrate API stores usernames, hostnames, and CLI version information, among other things, to ensure auditability. How “personal” these data are depends on context (e.g. mapping to real individuals).

For GDPR-aligned use we recommend:

• Clear communication to employees about logging (transparency).
• Role-based access control to audit data.
• Pseudonymization of hostnames or user IDs where compatible with your compliance policies.

ayedo can help you configure and integrate Polycrate so your data protection officer’s requirements are met.

More questions? See our FAQ

Compliance in Practice

With Polycrate and its API you get more than “just” an automation tool: you get an operations layer that combines technical excellence with auditability.

In this post you have seen:

• how Action Runs, SSH sessions, and workspace syncs merge into a continuous audit trail,
• how CLI instance tracking and centralized key management help implement governance requirements,
• and how this data supports NIS-2 and GDPR requirements in practice – without burdening your team with extra tool sprawl.

ayedo supports teams at exactly this intersection of automation and compliance: from shaping your platform engineering approach through introducing Polycrate to integrating the Polycrate API with your existing SIEM and GRC systems.

If you want to see what the audit trail could look like in your environment, good next steps are:

• Polycrate API documentation
• Workshops – guided sessions with examples from your context