Overview

Security guidelines and best practices for managing secrets with Fnox.

Encryption Fundamentals

Always Encrypt Sensitive Data

# Bad: Plain text secrets committed to git
[secrets]
DATABASE_PASSWORD = "super-secret-password"
API_KEY = "sk-live-12345"

# Good: Encrypted secrets
[providers.age]
type = "age"
public_keys = ["age1ql3z..."]

[secrets]
DATABASE_PASSWORD = { provider = "age", value = "age[...]" }
API_KEY = { provider = "age", value = "age[...]" }

Use Strong Encryption

# Good: age encryption (modern, secure)
age-keygen -o ~/.config/fnox/keys/identity.txt

# Good: Cloud KMS (managed encryption)
[providers.kms]
type = "aws-kms"
key_id = "arn:aws:kms:us-east-1:..."

Key Management

Protect Private Keys

# Store age private key securely
chmod 600 ~/.config/fnox/keys/identity.txt

# Never commit private keys
echo "*.txt" >> ~/.config/fnox/keys/.gitignore

Separate Public and Private Keys

# fnox.toml (committed) - public keys only
[providers.age]
type = "age"
public_keys = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]

# fnox.local.toml (gitignored) - private keys
[providers.age]
identity = "~/.config/fnox/keys/identity.txt"

Rotate Keys Regularly

# Generate new age key
age-keygen -o ~/.config/fnox/keys/identity-2025.txt

# Re-encrypt all secrets with new key
fnox get --all | fnox set --provider age-new

Access Control

Use Least Privilege

# Good: Separate secrets by environment
[profiles.production]
[profiles.production.providers.prod-secrets]
type = "aws-sm"
region = "us-east-1"

[profiles.production.secrets]
DATABASE_URL = { provider = "prod-secrets", value = "prod/db" }

[profiles.development]
[profiles.development.secrets]
DATABASE_URL = "postgresql://localhost/dev"  # Non-sensitive

Team Access Control

# Multiple age recipients for team
[providers.age]
type = "age"
public_keys = [
  "age1ql3z...",  # Alice (admin)
  "age1qw4r...",  # Bob (developer)
  # Don't include contractors or temporary team members
]

Role-Based Secrets

# Backend secrets
[providers.backend]
type = "aws-sm"
region = "us-east-1"

# Frontend secrets (different access level)
[providers.frontend]
type = "aws-sm"
region = "us-east-1"

[secrets]
BACKEND_DB_PASSWORD = { provider = "backend", value = "backend/db-pass" }
FRONTEND_API_ENDPOINT = { provider = "frontend", value = "frontend/api-url" }

Git Security

Never Commit Sensitive Data

# .gitignore
fnox.local.toml
*.age-identity.txt
*.key
*.pem
.env

Audit Git History

# Check for accidentally committed secrets
git log -p | grep -i "password\|secret\|key"

# Remove secrets from git history (if found)
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch fnox.local.toml' \
  --prune-empty --tag-name-filter cat -- --all

Use Pre-Commit Hooks

# .git/hooks/pre-commit
#!/bin/bash
if git diff --cached --name-only | grep -q "fnox.local.toml"; then
  echo "Error: Attempting to commit fnox.local.toml"
  exit 1
fi

# Check for plain text secrets
if git diff --cached | grep -q "password.*=.*\"[^a]"; then
  echo "Warning: Possible plain text password detected"
  exit 1
fi

Environment Separation

Separate Development and Production

# fnox.toml (development)
[secrets]
DATABASE_URL = "postgresql://localhost/dev"
DEBUG = "true"

# fnox.production.toml (production secrets)
[providers.prod]
type = "aws-sm"
region = "us-east-1"

[secrets]
DATABASE_URL = { provider = "prod", value = "prod/db-url" }
DEBUG = "false"

Use Profiles for Environments

# Development
fnox exec -- node app.js

# Staging
FNOX_PROFILE=staging fnox exec -- node app.js

# Production
FNOX_PROFILE=production fnox exec -- node app.js

Cloud Provider Security

AWS Best Practices

# Use IAM roles instead of access keys
[providers.aws-sm]
type = "aws-sm"
region = "us-east-1"
# No access_key_id or secret_access_key
# Uses IAM role or AWS credentials chain

# Restrict by resource tags
[providers.aws-sm]
type = "aws-sm"
region = "us-east-1"
# Ensure IAM policy limits access to specific secrets

Azure Best Practices

# Use managed identity
[providers.azure]
type = "azure-kv"
vault_url = "https://my-vault.vault.azure.net"
# Authentication via Azure managed identity

GCP Best Practices

# Use service account with minimal permissions
[providers.gcp]
type = "gcp-sm"
project_id = "my-project"
# Service account with only secretmanager.versions.access

Audit and Monitoring

Log Secret Access

# Enable audit logging in cloud providers
# AWS CloudTrail for Secrets Manager
# Azure Monitor for Key Vault
# GCP Cloud Audit Logs for Secret Manager

Monitor for Anomalies

# Check which secrets are accessed
fnox list

# Verify provider configuration
fnox doctor

# Test provider connectivity
fnox provider test aws-sm

Regular Security Audits

# List all secrets
fnox list

# Verify encryption status
fnox doctor

# Check for plain text secrets
grep -r "password.*=.*\"[^a]" fnox.toml

Secrets Lifecycle

Rotate Secrets Regularly

# Generate new secret
NEW_PASSWORD=$(openssl rand -base64 32)

# Update in fnox
echo "$NEW_PASSWORD" | fnox set DATABASE_PASSWORD

# Update in actual service (database, API, etc.)
# Then verify application still works

Remove Obsolete Secrets

# Remove unused secret
fnox unset OLD_API_KEY

# Clean up from cloud provider
aws secretsmanager delete-secret --secret-id old/api-key

Document Secret Purpose

[secrets]
STRIPE_API_KEY = {
  provider = "age",
  value = "age[...]",
  description = "Stripe secret key for payment processing. Rotate quarterly."
}

DATABASE_PASSWORD = {
  provider = "aws-sm",
  value = "prod/db-password",
  description = "PostgreSQL master password. Last rotated: 2025-01-01"
}

CI/CD Security

Use Dedicated CI Keys

# Separate age key for CI/CD
[providers.age]
type = "age"
public_keys = [
  "age1ql3z...",  # Developer key
  "age1ci3d...",  # CI/CD key (limited access)
]

Restrict CI Secret Access

# .github/workflows/deploy.yml
env:
  FNOX_PROFILE: production
  # Use GitHub secrets for age identity
  AGE_IDENTITY: ${{ secrets.AGE_IDENTITY }}

steps:
  - name: Load secrets
    run: |
      echo "$AGE_IDENTITY" > /tmp/identity.txt
      chmod 600 /tmp/identity.txt
      fnox exec -- ./deploy.sh
      rm /tmp/identity.txt

Minimal CI Permissions

# CI profile with minimal secrets
[profiles.ci]
[profiles.ci.secrets]
DEPLOY_TOKEN = { provider = "age", value = "age[...]" }
# Don't include database passwords or API keys

Best Practices Summary

DO

✅ Always encrypt sensitive secrets ✅ Use strong encryption (age, KMS) ✅ Store private keys securely ✅ Separate dev and prod secrets ✅ Use .gitignore for local overrides ✅ Rotate keys and secrets regularly ✅ Use cloud provider managed identities ✅ Audit secret access ✅ Document secret purpose ✅ Use profiles for environments

DON'T

❌ Never commit private keys ❌ Never use plain text for sensitive data ❌ Don't share private keys between team members ❌ Don't hardcode credentials ❌ Don't mix dev and prod secrets ❌ Don't skip encryption in production ❌ Don't ignore security warnings ❌ Don't use weak passwords as secrets

Common Threats and Mitigations

Threat: Accidental Commit

# Mitigation: Pre-commit hooks
cat > .git/hooks/pre-commit <<'EOF'
#!/bin/bash
if git diff --cached fnox.local.toml > /dev/null; then
  echo "Error: fnox.local.toml should not be committed"
  exit 1
fi
EOF
chmod +x .git/hooks/pre-commit

Threat: Key Compromise

# Mitigation: Immediate rotation
# 1. Generate new key
age-keygen -o ~/.config/fnox/keys/identity-new.txt

# 2. Re-encrypt all secrets
fnox get --all | fnox set --provider age-new

# 3. Update public keys
# 4. Revoke old key

Threat: Unauthorized Access

# Mitigation: Use cloud provider IAM
[providers.aws-sm]
type = "aws-sm"
region = "us-east-1"
# Restrict with IAM policies:
# - Limit to specific secret ARNs
# - Require MFA
# - Restrict by IP range

Related Skills

• configuration: Managing fnox.toml securely
• providers: Choosing secure providers