---
title: "Security Design"
html_title: "Enroll Security Design"
description: "Threat model, trust boundaries, dangerous mode, SOPS, root PATH safety, and manifest safety for Enroll."
---
<header class="py-5 hero">
  <div class="container py-3">
    <div class="kicker mb-3"><i class="bi bi-shield-lock"></i> Security design</div>
    <h1 class="display-6 fw-bold mb-2">Safe-by-default collection, explicit trust at apply time.</h1>
    <p class="lead mb-0">Enroll tries hard not to accidentally copy secrets or follow hostile paths, but it cannot decide whether a structurally valid host snapshot is safe to reproduce.</p>
  </div>
</header>

<main class="py-5">
  <div class="container">
    <div class="row g-4">
      <div class="col-lg-8">
        <div class="feature-card p-4 border border-warning">
          <h2 class="h4 fw-bold mb-2">The most important warning</h2>
          <p>When manifesting, Enroll prints:</p>
          <pre class="terminal mb-3"><code>This harvest is structurally valid, but Enroll cannot prove it is semantically safe.
Only apply manifests generated from harvests whose provenance you trust.</code></pre>
          <p class="mb-0">Validation checks shape and consistency. It does not prove the captured configuration is a good idea, that service files are benign, or that the host was not already compromised.</p>
        </div>

        <div class="feature-card p-4 mt-4">
          <h2 class="h4 fw-bold mb-2">Default secret avoidance</h2>
          <p>In normal mode, Enroll uses path deny-lists, symlink-safe file opening, file size limits, binary detection, and sampled content sniffing to avoid likely secrets and noisy data.</p>
          <p>Safe-mode scanning treats common credential-looking assignments as sensitive, including password/pass/passwd/pwd/pw forms, API keys, auth tokens, client secrets, secret keys, cloud access key names, service-account key names, and similar patterns.</p>
          <div class="alert alert-secondary mb-0 small"><strong>Comment caveat:</strong> Enroll ignores comments during the sensitive-content scan. If a real secret is commented out, it may still be captured in safe mode. Use SOPS or your own encryption when in doubt.</div>
        </div>

        <div class="feature-card p-4 mt-4">
          <h2 class="h4 fw-bold mb-2"><code>--dangerous</code></h2>
          <p><code>--dangerous</code> disables likely-secret checks. It may copy private keys, TLS key material, tokens, passwords, cloud credentials, and user shell dotfiles into the harvest in plaintext.</p>
          <p class="mb-0">Use it only when you intentionally want an aggressive disaster-recovery snapshot and you already know how the output will be protected.</p>
        </div>

        <div class="feature-card p-4 mt-4">
          <h2 class="h4 fw-bold mb-2">SOPS is storage-at-rest protection</h2>
          <p><code>--sops</code> writes encrypted <code>.tar.gz.sops</code> bundles for harvest and manifest outputs. It is not the same as generating Ansible Vault or SOPS-managed inventory variables.</p>
          <div class="terminal"><pre class="mb-0"><code>enroll harvest --out ./secure-harvest --dangerous --sops &lt;GPG_FINGERPRINT&gt;
enroll manifest --harvest ./secure-harvest/harvest.tar.gz.sops \
  --out ./secure-manifest --sops &lt;GPG_FINGERPRINT&gt;</code></pre></div>
          <p class="small text-secondary mt-3 mb-0">Decrypt and extract an encrypted manifest before running Ansible.</p>
        </div>

        <div class="feature-card p-4 mt-4">
          <h2 class="h4 fw-bold mb-2">Filesystem and rendering hardening</h2>
          <ul class="mb-0">
            <li>Plaintext harvest/manifest output directories are created private and are refused when unsafe or unexpectedly pre-existing.</li>
            <li>Root-run output refuses parent directories controlled by unprivileged users, except safe sticky boundaries such as <code>/tmp</code> with further child checks.</li>
            <li>Source and artifact reads use no-follow semantics and reject symlinked components, non-regular files, hardlinks, and unexpected large inputs.</li>
            <li>Directory harvests are frozen into a private temporary copy before validation and rendering to avoid post-validation swaps.</li>
            <li>Tar/SOPS/remote inputs are extracted through safe extraction rules.</li>
            <li>Harvested strings that look like Jinja are emitted as Ansible <code>!unsafe</code> data, while generated task scaffolding only accepts strict Enroll-controlled tokens.</li>
          </ul>
        </div>
      </div>

      <div class="col-lg-4">
        <div class="callout p-4">
          <div class="fw-semibold mb-2">Recommended workflow</div>
          <ol class="small mb-0">
            <li>Harvest in normal mode first.</li>
            <li>Run <code>enroll explain</code> and <code>enroll validate</code>.</li>
            <li>Use targeted <code>--include-path</code> instead of broad <code>--dangerous</code> where possible.</li>
            <li>Encrypt outputs if they may contain sensitive data or leave the host.</li>
            <li>Run Ansible with <code>--check --diff</code> and review before applying.</li>
          </ol>
        </div>

        <div class="callout p-4 mt-3">
          <div class="fw-semibold mb-2">Root PATH safety</div>
          <p class="small text-secondary mb-2">When run as root, Enroll checks <code>PATH</code> for empty, relative, current-directory, or group/world-writable entries that could cause host tools to resolve to attacker-controlled binaries.</p>
          <p class="small mb-0">Use <code>--assume-safe-path</code> only in trusted automation where the PATH is intentional.</p>
        </div>

        <div class="callout p-4 mt-3">
          <div class="fw-semibold mb-2">Out of scope</div>
          <ul class="small text-secondary mb-0">
            <li>Proving harvested config is semantically safe</li>
            <li>Protecting against a fully compromised root account</li>
            <li>Guaranteeing generated Ansible is an ideal long-term design</li>
            <li>Secret management after you intentionally disable safety checks</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</main>