Security Best Practices

Passphrase Strength

Your passphrase protects your identity's private key. A weak passphrase undermines all other security measures.

Recommendations

• Length: At least 16 characters, preferably 20+
• Type: Use a passphrase (multiple words) rather than a password
• Uniqueness: Don't reuse from other services
• Storage: Use a password manager or system keychain

Examples

Using the System Keychain

Store your passphrase in the system keychain for convenience without sacrificing security:

$ envctl init --keychain

The keychain is protected by your system login, so you don't need to enter the passphrase repeatedly.

Hardware Security (YubiKey)

For maximum security, store your private key on a YubiKey:

$ envctl init --yubikey

Benefits:

• Private key never leaves the hardware device
• Signing operations happen on the YubiKey
• Even if your machine is compromised, the key is safe
• Physical presence required to use the key

Regular Rotation

Rotate secrets periodically, not just when someone leaves.

Suggested Schedule

After Team Changes

Always rotate when:

• A team member leaves
• A contractor's engagement ends
• Access is revoked for any reason

See the Offboarding guide for details.

Principle of Least Privilege

Give team members access only to what they need.

Environment Access

# New developers: dev only
$ envctl project invite newdev --pubkey ... --env dev

# After onboarding: add staging
$ envctl project grant newdev --env staging

# Only when needed: add prod
$ envctl project grant newdev --env prod

Roles

• reader — For people who need to view but not modify (auditors, support)
• member — For developers who modify secrets
• admin — For team leads who manage membership

Production Access

Limit production access to essential personnel:

• Most developers don't need prod secrets for daily work
• Use staging for development and testing
• Grant prod access temporarily for deployments
• Review prod access regularly

Backup and Recovery

Paper Backup

Export your identity as a paper backup:

$ envctl identity export
Passphrase:

Your recovery phrase (24 words):

  1. apple      7. grape     13. mango     19. strawberry
  2. banana     8. honeydew  14. nectarine 20. tangerine
  3. cherry     9. kiwi      15. orange    21. ugli
  4. date      10. lemon     16. papaya    22. vanilla
  5. elderberry 11. lime     17. quince    23. watermelon
  6. fig       12. melon     18. raspberry 24. xigua

Write these words on paper and store in a secure location.
Do NOT store digitally or take a screenshot.

Store this in a secure physical location (safe, safety deposit box).

Recovery

$ envctl identity recover
Enter your 24-word recovery phrase:
Word 1: apple
Word 2: banana
...
✓ Identity recovered

What You Can't Recover

• Project membership — You'll need to be re-invited
• Local .env files — Re-export from envctl after recovery
• CI private keys — Generate new ones if lost

Compromised Machine Response

If you suspect a machine is compromised:

Immediate Actions

1. Rotate your identity key:

   $ envctl identity rotate-key
   ! This will re-encrypt all secrets you have access to.
   ! Other team members will need to approve the new key.
   Continue? [y/N] y

2. Notify your team — Others should be aware
3. Rotate secrets you had access to — Starting with production
4. Re-export CI bundles — If the CI key was accessible

If a Team Member's Machine is Compromised

1. Remove them from the project:

   $ envctl project remove compromised-user --reason "Security incident"

2. Rotate all secrets they had access to
3. Review audit logs for suspicious activity:

   $ envctl log --search compromised-user --since 30d

4. Re-invite them with a new identity after they've secured their machine

Audit and Monitoring

Regular Audits

Periodically review:

• Team membership: Who has access?

  $ envctl project members

• Environment access: Who can see production?

  $ envctl project access --env prod

• Recent changes: What's been modified?

  $ envctl log --since 30d

Suspicious Activity

Watch for:

• Unexpected secret changes
• Access from unusual locations (check relay logs)
• Failed authentication attempts
• Bulk secret exports

Encryption Overview

envctl uses strong, modern cryptography:

The post-quantum encryption (ML-KEM-768) protects your secrets against future quantum computer attacks.

Security Checklist

• Use a strong passphrase (16+ characters)
• Consider YubiKey for high-security environments
• Create and store a paper backup
• Limit production access to essential personnel
• Rotate secrets quarterly
• Rotate immediately when team members leave
• Review access lists monthly
• Keep envctl updated for security patches

Related

• Core Concepts: Encryption Model
• Team Offboarding
• Multiple Environments