Operations Guide

Workflows for rotation, compliance, and operational tasks.

Secret Rotation

Why Rotate?

• Compromised credentials
• Employee departure
• Regular security hygiene
• Compliance requirements

Rotation via Dashboard

1. Navigate to Secrets
2. Select the project and environment
3. Click the rotate icon next to the secret
4. Either:
   • Let varsafe auto-generate a new value
   • Enter a new value manually
5. Preview the change
6. Confirm rotation

The old value is immediately invalid. Applications using varsafe run receive the new value on their next run.

Rotation via API

For programmatic rotation, use the API:

curl -X POST "https://api.varsafe.dev/secrets/rotate" \
  -H "Authorization: Bearer $VARSAFE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secretId": "secret_xxx", "value": "new-value"}'

Rotation Best Practices

Recommended rotation schedule

Secret Type	Rotation Frequency
API keys	Every 90 days
Database passwords	Every 90 days
Encryption keys	Annually
After incident	Immediately

Handling Running Applications

Applications using varsafe run receive fresh secrets on startup. For running applications:

1. Stateless apps — Restart to pick up new secrets
2. CI/CD — Each run gets fresh secrets automatically

---

Encryption Key Management

Environment Keypairs

Each environment has an encryption keypair (X25519) used to encrypt .env file exports. Private keys are KMS-encrypted at rest — they never exist in plaintext in the database.

Checking Key Status

In the dashboard, navigate to Encryption Keys to see keypair status for all environments. Look for exposed status, which means a removed team member previously accessed that environment's private key.

Rotating Keys

Rotate a keypair when:

• A team member with key access is removed
• Key exposure is suspected
• Regular security hygiene (see rotation schedule below)

Rotate from the dashboard under Encryption Keys. After rotation, existing encrypted .env files are automatically re-encrypted on next use with varsafe run --env-file.

Auto-Rotation on Member Removal

By default, varsafe automatically rotates keypairs when a team member is removed, for every environment whose private key they accessed. This is tracked via audit events.

To switch to manual rotation (team setting):

# Via API
curl -X PATCH "https://api.varsafe.dev/teams/$TEAM_ID/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keyRotationOnMemberRemoval": "manual"}'

Rotation schedule

Key Type	Rotation Frequency
Environment keypairs	Auto on member removal, or 1 year
After key exposure	Immediately

---

API Token Management

Creating Tokens

1. Go to your team settings in the dashboard
2. Navigate to API Tokens
3. Click Create token
4. Enter a descriptive name (e.g., "GitHub Actions - Production")
5. Copy the token immediately

Token Rotation

Rotate tokens regularly for security:

1. Click Rotate next to the token
2. Copy the new token
3. Update your CI/CD configuration
4. The old token is immediately invalidated

Token Revocation

If a token is compromised

1. Click Revoke immediately
2. Create a new token
3. Update your configurations
4. Review audit logs for unauthorized access

---

Environment Rollback

When to Rollback

• Accidental secret deletion
• Bad configuration deployed
• Need to restore previous state

How to Rollback

1. Navigate to Secrets in the dashboard
2. Select project and environment
3. Click History
4. Click Rollback next to the target operation
5. Review the preview:
   • Secrets to delete
   • Secrets to restore
   • Secrets to revert
6. Confirm rollback

What Rollback Does

Rollback restores the environment to its state before the selected operation:

• Created secrets are deleted
• Deleted secrets are restored
• Updated secrets are reverted to previous versions

---

Compliance Exports

SOC 2 Type II

Export audit trail for SOC 2 audits:

1. Navigate to Audit Log
2. Set date range (audit period)
3. Click Export → SOC 2
4. Download JSON file

The export includes:

• All security-relevant events
• User access patterns
• Authentication events
• Secret access logs

GDPR Article 30

Export processing activities record:

1. Navigate to Audit Log
2. Click Export → GDPR
3. Download JSON file

The export includes:

• Data processing activities
• Data subjects affected
• Legal basis for processing
• Retention periods

HIPAA

Export access controls audit:

1. Navigate to Audit Log
2. Click Export → HIPAA
3. Download JSON file

The export includes:

• PHI access events
• User authentication events
• Access control decisions

CSV Export

For general analysis:

1. Navigate to Audit Log
2. Apply any filters needed
3. Click Export CSV

---

Access Reviews

Quarterly Access Review

1. List team members:

   • Dashboard → Teams → Expand each team
   • Note members and their roles

2. Review for:

   • Departed employees (should be removed)
   • Role appropriateness (least privilege)
   • Inactive accounts

3. Take action:

   • Remove departed members
   • Downgrade excessive roles
   • Document review completion

Checking API Tokens

1. Go to team settings → API Tokens
2. Review each token:
   • Is it still needed?
   • Who created it?
   • When was it last used?
3. Revoke unused tokens

---

Audit Log Management

Retention

Plan	Retention
Developer	7 days
Team	90 days

TIP

For longer retention, export audit logs regularly and store in your compliance archive.

Alert-worthy Events

Monitor your audit logs for these events

Event	Concern
Multiple login_failed	Brute force attempt
secret.accessed (production)	Verify authorized access
member_invited (admin role)	Privilege escalation
2fa_disabled	Security downgrade
Unfamiliar IP addresses	Unauthorized access

---

Incident Response

Compromised Secret

Immediate actions required

1. Rotate immediately — Dashboard → Secrets → Rotate, or via API for automation
2. Review audit logs — Who had access? When? From what IP addresses?
3. Assess impact — What systems use this secret? Was there unauthorized access?
4. Document incident — Timeline, actions taken, lessons learned

Compromised Account

Immediate actions required

1. Revoke sessions immediately — Profile → Security → Revoke all sessions
2. Reset password — Or require passkey-only authentication
3. Review audit logs — What did the account access? Were any secrets exported?
4. Rotate affected secrets — Assume compromise, rotate all secrets the account had access to
5. Report to team — Notify security team, document for compliance

Compromised API Token

Immediate actions required

1. Revoke immediately — Team settings → API Tokens → Revoke
2. Create new token — With fresh credentials
3. Update configurations — CI/CD systems, automated scripts
4. Review token usage — Check audit logs for unauthorized access

---

Troubleshooting

"Authentication required"

varsafe login

"Permission denied"

Check:

1. Team membership exists
2. Role permits the action
3. Environment is not protected (for members)

"Project not found"

Either:

1. Create the project in dashboard
2. Use varsafe use to set context
3. Specify with -p flag

"Rate limited"

Wait and retry. If persistent:

1. Check for automation running too frequently
2. Contact support for limit increase