This dotfiles repository contains configurations and scripts for managing development environments. While the repository itself contains no secrets (all sensitive data is stored in your vault—Bitwarden, 1Password, or pass), we take security seriously.

We provide security updates for the latest release only:

Recommendation: Always use the latest version from the main branch.

If you discover a security vulnerability, please help us responsibly:

Preferred Method: GitHub Security Advisories

1. Go to https://github.com/blackwell-systems/dotfiles/security/advisories
2. Click "Report a vulnerability"
3. Provide detailed information about the issue

Alternative Method: Private Issue

1. Contact the maintainer through GitHub (@your-username)
2. Include details about the vulnerability
3. Wait for acknowledgment before public disclosure

When reporting a security issue, please include:

• Description: Clear description of the vulnerability
• Impact: What could an attacker do with this vulnerability?
• Reproduction: Steps to reproduce the issue
• Affected Files: Which scripts or configurations are affected
• Suggested Fix: (Optional) How you would fix it

Issues we consider security-relevant:

• ✅ Scripts that could accidentally leak credentials
• ✅ File permission issues that expose sensitive data
• ✅ Command injection vulnerabilities
• ✅ Insecure defaults in configurations
• ✅ Path traversal issues in bootstrap scripts

Not security issues:

• ❌ General bugs (use regular issues)
• ❌ Feature requests
• ❌ Questions about usage

When using these dotfiles:

• All secrets should be stored in your vault (Bitwarden, 1Password, or pass)
• The .gitignore file protects common secret files
• Pre-commit hooks scan for leaked credentials
• Always review changes before committing: git diff

Before running bootstrap scripts on a new machine:

# Verify you're on the official repository
git remote -v

# Check recent commits for suspicious changes
git log --oneline -10

# Review bootstrap script before running
cat bootstrap-mac.sh  # or bootstrap-linux.sh

• Use a strong master password (20+ characters)
• Enable two-factor authentication (2FA)
• Keep your vault CLI up to date:
  • Bitwarden: brew upgrade bitwarden-cli
  • 1Password: brew upgrade --cask 1password-cli
  • pass: brew upgrade pass
• Lock your vault when not in use (e.g., bw lock for Bitwarden)

The health check validates file permissions:

# Check permissions
dotfiles doctor

# Auto-fix permission issues
dotfiles doctor --fix

Expected permissions:

• Private keys: 600 (owner read/write only)
• Public keys: 644 (owner read/write, others read)
• SSH config: 600 (owner read/write only)
• AWS credentials: 600 (owner read/write only)
• Shell configs: 644 (owner read/write, others read)

# Update dotfiles
dotfiles-upgrade

# Update Homebrew packages
brew update && brew upgrade

# Update vault CLI
brew upgrade bitwarden-cli   # or: brew upgrade --cask 1password-cli / brew upgrade pass

The vault system caches sessions in vault/.vault-session:

• File has 600 permissions (owner-only access)
• Automatically expires after vault timeout
• Recommendation: Lock your vault when leaving your machine (e.g., bw lock for Bitwarden)

SSH keys are automatically added to the agent:

• Agent stores decrypted private keys in memory
• Keys remain loaded until logout or ssh-add -D
• Recommendation: Use passphrase-protected keys

Shell history is stored in ~/workspace/.zsh_history:

• Shared between macOS and Lima VM
• May contain sensitive commands
• Recommendation: Prefix sensitive commands with a space to exclude from history

# This will be in history
echo "public command"

# Leading space prevents history recording (if HIST_IGNORE_SPACE is set)
 echo "sensitive command with secret"

Lima mounts your macOS home directory:

• Files in ~/workspace are shared between host and VM
• File permissions preserved
• Recommendation: Keep sensitive files in home directory, not workspace

When a security issue is reported:

1. Acknowledgment: Within 48 hours
2. Assessment: Severity and impact evaluation (1-3 days)
3. Fix Development: Patch created and tested (1-7 days)
4. Disclosure:
   • Fix merged to main branch
   • Security advisory published
   • CHANGELOG updated
   • Users notified via GitHub release

• Responsible Disclosure: We ask for 90 days before public disclosure
• Credit: Security researchers will be credited in release notes (unless they prefer anonymity)
• Coordination: We'll work with you on disclosure timeline

When contributing code:

• No hardcoded credentials or API keys
• File permissions are restrictive (600/644/700)
• User input is validated/sanitized
• File paths don't allow traversal attacks
• Shell commands properly quote variables
• Secrets are never logged or printed
• Pre-commit hooks pass (includes secret scanning)

For general security questions (not vulnerabilities):

• Open a GitHub Discussion
• Review the Security Maintenance section in README

• Security Issues: Use GitHub Security Advisories (preferred)
• General Questions: GitHub Discussions
• Maintainer: See GitHub profile for contact options

Last Updated: 2025-11-27