--- title: "Security Design" html_title: "Enroll Security" description: "Security posture and safe workflows for Enroll outputs." ---
Security

Safe by default. Powerful when you opt in.

Enroll can touch sensitive files. This page helps you use it confidently.

Default behavior

In normal mode, Enroll attempts to avoid harvesting likely secrets using a combination of path deny-lists, content sniffing, and size caps. This means you may see some files intentionally skipped.

The --dangerous flag

This disables secret-safety checks. It can copy private keys, API tokens, DB passwords, TLS key material, etc.

Rule: if you use --dangerous, treat the output as sensitive data and plan secure storage before you run it. Don't store secrets in plaintext in a public place!

Encrypt bundles at rest with SOPS

You can install SOPS on your $PATH, then use --sops to write a single encrypted .tar.gz.sops file for harvests and/or manifests. This is meant for storage-at-rest and backups.

$ enroll harvest --out /tmp/enroll-harvest --dangerous --sops <FINGERPRINT>
$ enroll manifest --harvest /tmp/enroll-harvest/harvest.tar.gz.sops \
  --target ansible --out /tmp/enroll-ansible --sops <FINGERPRINT>
Important
In manifest --sops mode, you'll need to decrypt and extract the bundle before running ansible-playbook, puppet apply, or salt-call.

Filesystem hardening for root runs

Enroll is often run as root because it needs to inspect system state. Version 0.5.5 added stricter filesystem checks so root does not accidentally write harvests or generated output through an unsafe path.

Private output directories

Harvest and manifest outputs are created with restrictive permissions, and Enroll refuses to reuse an existing harvest directory unless that mode is explicitly expected for an internal workflow.

Symlink and parent checks

When running as root, Enroll checks path components and parent directories so output is not created below a parent controlled by another user. This reduces the risk of symlink and time-of-check/time-of-use path races.

Safer artifact handling

Captured files and generated artifacts are validated as regular files, with traversal, symlink, hardlink, and special-file cases rejected when bundles are validated or extracted.

Root PATH hygiene

For root runs, Enroll warns about unsafe PATH entries so helper commands are not resolved from relative, writable, or non-root-owned directories.

Why this can feel strict
A command that writes under a user-owned directory may be convenient, but it can also be hard to prove safe when the process is running as root. Prefer a root-owned output area such as /var/tmp/enroll, /root, or a fresh directory directly under the normal sticky /tmp.
Recommended workflow
  1. Start with default mode (no --dangerous).
  2. Add --include-path for a small set of extra files you genuinely want managed.
  3. If you must capture secrets, use --dangerous and --sops.
  4. Keep outputs out of public repos; review before committing.
  5. Rotate credentials if you ever suspect they were captured or exposed.
Storage ideas
  • Encrypted SOPS bundle stored in a password manager vault
  • Private git repo with additional encryption at rest
  • Offline backup in an encrypted volume
Scope control

You can explicitly include or exclude paths. Excludes take precedence over includes.

$ enroll harvest \
  --out /tmp/enroll-harvest \
  --include-path '/home/*/.profile' \
  --exclude-path '/home/*/.ssh/**'

Threat model and security scope

Enroll is a command-line systems administration tool. It is designed to be run intentionally by an administrator, often as root, to inspect a host, harvest selected system state, and optionally generate or apply configuration-management output.

That makes Enroll different from a web application, daemon, network service, or setuid helper. It is not intended to be a sandbox for hostile local users. Instead, it assumes an operator-controlled execution environment, while still adding defense-in-depth checks for common filesystem, path traversal, secret-handling, and command-resolution mistakes.

Trusted operator assumptions
  • If Enroll is run as root, the root user is assumed to control and understand the command line, environment, configuration file, and output location.
  • If an enroll.ini file is loaded, its location and contents are assumed to be owned, selected, and understood by the operator.
  • The operator is expected to understand the implications of options such as --dangerous, --assume-safe-path, --sops, --enforce, --remote-host, and --remote-ssh-config.
  • Harvest bundles used for manifest, diff, or diff --enforce are assumed to come from a trusted source unless the operator is deliberately inspecting them without applying them.
Trusted local tools

Enroll invokes ordinary administrative tools such as SSH, sudo, SOPS, package managers, Docker, Podman, Flatpak, Snap, Ansible, Puppet, Salt, and system utilities. These are assumed to be the trusted tools the operator intended to execute.

If an attacker can replace or redirect those tools, the host already has a local trust-boundary problem outside Enroll's ability to fully solve.

What Enroll tries to protect against

Enroll still performs substantial hardening because privileged CLI tools can otherwise be easy to misuse. These controls are intended to protect careful administrators from common dangerous mistakes.

  • Accidentally copying obvious secrets in default mode
  • Harvesting huge or unbounded file sets by mistake
  • Writing root-run output through unsafe symlinks, hardlinks, special files, or path-race situations
  • Extracting harvest tar members outside the intended bundle directory
  • Copying unsafe harvested artifacts into generated manifests
  • Resolving helper commands from suspicious PATH entries during root runs
  • Generating manifest commands where ordinary harvested values could become shell injection
  • Accepting unknown SSH host keys during remote harvests
  • Confusing one host's data with another host's data in multi-site outputs
  • Applying structurally unsafe harvest bundles

What is out of scope

The following are normally considered local compromise, operator-controlled behavior, or trust-boundary failures rather than Enroll vulnerabilities by themselves:

  • A malicious local user who can already control root's command line, shell environment, config file, working directory, PATH, or invoked binaries
  • A root user loading an enroll.ini file whose contents intentionally request dangerous behavior
  • A root user passing --dangerous and observing that Enroll may collect sensitive data
  • A root user passing --assume-safe-path and observing that Enroll does not prompt about PATH safety
  • A user applying generated Ansible, Puppet, or Salt output from a harvest bundle they do not trust
  • A user enforcing a malicious or manually edited harvest bundle with diff --enforce
  • A user configuring an untrusted webhook, SSH proxy command, SOPS binary, or configuration-management tool
  • Reports that amount to: root can run Enroll with malicious options and make the system do dangerous things
Plain-language summary
Enroll is an administrator's tool, not a local privilege boundary. If the operator's root execution environment is already attacker-controlled, Enroll cannot make that safe. Enroll does, however, try to reduce the damage from common path, permission, traversal, secret-handling, and manifest-generation mistakes.

Trusted harvests and enforcement

Harvest bundles should be treated as sensitive administrative artifacts. A harvest 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 it may contain substantially more sensitive material.

Enroll validates harvest structure and artifact safety, but validation does not prove that the desired state represented by a harvest is safe to apply. Only run manifest, diff, or especially diff --enforce against bundles that came from hosts and people you trust.

Security report scope

Useful reports
  • Enroll captures clearly sensitive default-denied files without --dangerous
  • Enroll follows a symlink or hardlink in a way that causes privileged file disclosure or overwrite
  • Enroll extracts a tar member outside the intended harvest directory
  • Enroll accepts an artifact path that escapes the artifact root
  • Ordinary harvested data can cause command injection in generated manifests
  • Enroll silently ignores a failed safety check and proceeds anyway
Normally out-of-scope reports
  • Root can configure Enroll to collect sensitive files
  • Root can pass --dangerous and collect dangerous data
  • Root can pass --assume-safe-path and bypass the root PATH warning
  • Root can point Enroll at a malicious config file
  • Root can enforce a malicious harvest bundle
  • A local attacker can influence Enroll after already controlling root's environment or binaries

Security researchers

Found a vulnerability in Enroll?
  • Please contact me using the contact form or via Signal (mig5.55)
  • My GPG public key is here
  • Unfortunately, I cannot offer financial bounty rewards at this time, but you will receive full credit for valid security issues.