ruvector/docs/development/SECURITY.md

Security Best Practices for Ruvector Development

Environment Variables and Secrets

Never Commit Secrets

Critical: Never commit API keys, tokens, or credentials to version control.

Protected Files

The following files are in .gitignore and should NEVER be committed:

.env                    # Main environment configuration
.env.local             # Local overrides
.env.*.local           # Environment-specific local configs
*.key                  # Private keys
*.pem                  # Certificates
credentials.json       # Credential files

Using .env Files

1. Copy the template:

   cp .env.example .env
   

2. Add your credentials:

   # Edit .env with your actual values
   nano .env
   

3. Verify .env is ignored:

   git status --ignored | grep .env
   # Should show: .env (in gitignore)
   

API Keys Management

Crates.io API Key

Required for publishing crates to crates.io

1. Generate Token:

   • Visit crates.io/me
   • Click "New Token"
   • Name: "Ruvector Publishing"
   • Permissions: "publish-new" and "publish-update"
   • Copy the token immediately (shown only once)

2. Store Securely:

   # Add to .env (which is gitignored)
   echo "CRATES_API_KEY=your-actual-token-here" >> .env
   

3. Use from .env:

   # Publishing script automatically loads from .env
   ./scripts/publish-crates.sh
   

Key Rotation

Rotate API keys regularly:

# 1. Generate new token on crates.io
# 2. Update .env with new token
# 3. Test with: cargo login $CRATES_API_KEY
# 4. Revoke old token on crates.io

Development Secrets

What NOT to Commit

❌ Never commit:

• API keys (crates.io, npm, etc.)
• Database credentials
• Private keys (.key, .pem files)
• OAuth tokens
• Session secrets
• Encryption keys
• Service account credentials

✅ Safe to commit:

• .env.example (template with no real values)
• Public configuration
• Example data (non-sensitive)
• Documentation

Pre-commit Checks

Before committing, verify no secrets are staged:

# Check staged files
git diff --staged

# Search for potential secrets
git diff --staged | grep -i "api_key\|secret\|password\|token"

# Use git-secrets (optional)
git secrets --scan

GitHub Secret Scanning

GitHub automatically scans for common secrets. If detected:

1. Immediately revoke the exposed credential
2. Generate a new credential
3. Update .env with new credential
4. Force push to remove from history (if needed):

   # Dangerous! Only if absolutely necessary
   git filter-branch --force --index-filter \
     "git rm --cached --ignore-unmatch .env" \
     --prune-empty --tag-name-filter cat -- --all
   

CI/CD Secrets

GitHub Actions

Store secrets in GitHub repository settings:

1. Go to repository Settings → Secrets and variables → Actions

2. Add secrets:

   • CRATES_API_KEY - for publishing
   • CODECOV_TOKEN - for code coverage (optional)

3. Use in workflows:

   - name: Publish to crates.io
     env:
       CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_API_KEY }}
     run: cargo publish
   

Local Development

For local development, use .env:

# .env (gitignored)
CRATES_API_KEY=cio-xxx...
RUST_LOG=debug

Load in scripts:

# Load from .env
export $(grep -v '^#' .env | xargs)

Code Signing

Signing Releases

For production releases:

# Generate GPG key (if not exists)
gpg --gen-key

# Sign git tags
git tag -s v0.1.0 -m "Release v0.1.0"

# Verify signature
git tag -v v0.1.0

Cargo Package Signing

Cargo doesn't support package signing yet, but you can:

1. Sign the git tag
2. Include checksums in release notes
3. Provide GPG signatures for binary releases

Dependency Security

Audit Dependencies

Regularly audit dependencies for vulnerabilities:

# Install cargo-audit
cargo install cargo-audit

# Run security audit
cargo audit

# Fix vulnerabilities
cargo audit fix

Automated Scanning

Enable GitHub Dependabot:

1. Go to repository Settings → Security → Dependabot
2. Enable "Dependabot alerts"
3. Enable "Dependabot security updates"

Reporting Security Issues

Responsible Disclosure

If you discover a security vulnerability:

1. Do NOT open a public GitHub issue
2. Email: security@ruv.io
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

Response Timeline

• 24 hours: Initial response
• 7 days: Status update
• 30 days: Fix released (if confirmed)

Security Checklist

Before releasing:

• No secrets in code or config files
• .env is in .gitignore
• .env.example has no real values
• All dependencies audited (cargo audit)
• Git tags are signed
• API keys rotated if exposed
• Security scan passed (GitHub)
• Documentation reviewed for sensitive info

Resources

• Cargo Security Guidelines
• GitHub Secret Scanning
• OWASP Top 10
• Rust Security Guidelines

Support

For security questions:

• Email: security@ruv.io
• Documentation: docs.ruv.io
• Community: Discord