Security design

Threat model and security scope

Enroll is a privileged systems-administration CLI, not a sandbox. It tries to protect careful administrators from common mistakes, while assuming the operator controls the environment they run it in.

Core assumptions

Enroll is designed to be executed intentionally by a system administrator, often as root, to inspect a host and generate Ansible output. If an attacker controls the administrator's command line, environment, config file, working directory, PATH, SSH config, SOPS binary, Ansible installation, or harvested input bundle, they may influence what Enroll does. That is considered a local trust-boundary failure outside Enroll's intended security model.

  • The operator understands options such as --dangerous, --assume-safe-path, --sops, --remote-host, and --remote-ssh-config.
  • Configuration files loaded from enroll.ini are selected and trusted by the operator.
  • Harvest bundles used for manifest or diff come from a trusted source unless the operator is deliberately inspecting untrusted input without applying it.
  • External tools invoked by Enroll, including Ansible, SOPS, SSH, sudo, Docker, Podman, Flatpak, Snap, package managers, and system utilities, are the trusted tools the operator intended to use.

What Enroll tries to defend against

Accidental secret capture

Default mode avoids obvious sensitive paths, private keys, token/password assignments, authorization headers, credential URIs, and similar material.

Unsafe filesystem behavior

Enroll avoids symlink traversal, hardlinks, device nodes, tar path traversal, unsafe artifact paths, and common TOCTOU issues when copying and consuming artifacts.

Unsafe generated Ansible

Harvested values are serialized as Ansible data, template-looking values are tagged !unsafe, and raw task scaffold identifiers are allowlisted.

Risky privileged automation

Plain harvest outputs are private by default. Root-run output paths and unsafe root PATH entries are checked. Remote harvest rejects unknown SSH host keys by default.

What is out of scope

The following are normally operator trust failures, not Enroll vulnerabilities by themselves:

  • A malicious local user already controlling root's shell, environment, config files, PATH, binaries, SSH config, or working directory.
  • A root user intentionally loading a config file or passing options that request dangerous behavior.
  • Using --dangerous and observing that Enroll may collect sensitive information.
  • Using --assume-safe-path and observing that Enroll does not prompt about PATH.
  • Applying generated Ansible from an untrusted harvest.
  • Trusting an untrusted webhook, email target, SSH proxy command, SOPS binary, package manager, or Ansible toolchain.

Trusted harvests

Harvest bundles are sensitive administrative artifacts. They may contain hostnames, usernames, package lists, service state, filesystem metadata, configuration files, firewall snapshots, container image references, Flatpak/Snap state, and other operational details. In --dangerous mode they may contain much more sensitive material.

Important: Enroll validates harvest structure and artifact safety. It cannot prove that the desired state represented by a harvest is safe to apply. Before running manifest, diff, or Ansible, be confident the harvest came from a trusted source and has not been tampered with.
$ enroll validate ./harvest
$ enroll manifest --harvest ./harvest --out ./ansible

Useful security reports

Useful reports show Enroll behaving unsafely despite the documented trust model. Examples include:

  • Capturing a clearly sensitive default-denied file without --dangerous.
  • Following a symlink or hardlink in a way that causes privileged file disclosure or overwrite.
  • Extracting a tar member outside the intended harvest directory.
  • Accepting a malicious harvest artifact that escapes the artifact root.
  • Generating Ansible where ordinary harvested data can cause command injection or YAML/template structure injection.
  • Writing root-run output into an unsafe attacker-controlled path despite safety checks.
  • Accepting an unknown SSH host key unexpectedly.

Less useful reports are variations of “root deliberately asked Enroll to do dangerous things”. Those are expected consequences of running a privileged administration tool with trusted operator-controlled input.