Security Best Practices

PAT Creation Best Practices

• Use Minimum Required Scopes:
  • Build: Read - Read build/release data
  • Code: Read - Access repository information (if needed)
  • Avoid Full Access or Agent Pools: Read & manage
• Set Short Expiration: 90 days maximum, 30 days recommended
• Rotate Regularly: Update PATs before expiration
• Use Descriptive Names: "DeployBrief-Prod-BuildAccess-Exp2024-06"

Encrypted Storage

DeployBrief encrypts PATs at rest using:

• Azure Key Vault: For production environments (recommended)
• Application-Level Encryption: With ASP.NET Core Data Protection
• Database-Level Encryption: PostgreSQL transparent data encryption (TDE)

Revoking Compromised PATs

If a PAT is exposed:

1. Revoke immediately in Azure DevOps → User Settings → Personal Access Tokens
2. Delete connection in DeployBrief UI or via API
3. Create new PAT with minimum scopes
4. Update connection with new PAT
5. Review audit logs for unauthorized access

Scoping API Keys

Always use the principle of least privilege when creating API keys:

// Good: Scoped for specific operations
{
  "name": "CI/CD Pipeline Key",
  "scopes": ["briefs:write"],
  "expiresInDays": 90
}

// Bad: Excessive permissions
{
  "name": "CI/CD Pipeline Key",
  "scopes": ["briefs:read", "briefs:write", "briefs:delete", 
             "connections:read", "presets:read"],
  "expiresInDays": 365
}

Available Scopes

• briefs:read - Read briefs only
• briefs:write - Create and update briefs
• briefs:delete - Delete briefs (use sparingly)
• connections:read - List Azure DevOps connections
• presets:read - List pipeline presets

Key Storage

Store API keys securely in CI/CD systems:

# Settings → Secrets and variables → Actions
DEPLOYBRIEF_API_KEY: your-api-key-here

# Pipelines → Library → Variable Groups
DEPLOYBRIEF_API_KEY: your-api-key-here (set as secret)

Key Rotation

Rotate API keys every 90 days or when:

• An employee with access leaves the workspace
• A key may have been exposed (logs, repositories, etc.)
• Security policies require it

Rotation process:

1. Create new API key
2. Update CI/CD pipelines with new key
3. Test deployments
4. Revoke old key

OAuth 2.0 with Microsoft Entra ID

DeployBrief uses Microsoft Entra ID (Azure AD) for user authentication:

• Single Sign-On (SSO): Leverage existing workspaceal credentials
• Multi-Factor Authentication (MFA): Enforce via Entra ID policies
• Conditional Access: Apply location, device, and risk-based policies

Role-Based Access Control (RBAC)

DeployBrief implements workspace-level RBAC:

Session Security

• Secure Cookies: HttpOnly, Secure, SameSite=Strict flags
• Session Timeout: 24 hours for web sessions, configurable
• Token Refresh: Automatic refresh for active sessions
• Logout: Clears server-side session and client-side tokens

Encryption at Rest

• Database Encryption: PostgreSQL TDE (Transparent Data Encryption)
• Credential Encryption: ASP.NET Core Data Protection with Key Vault
• Azure Storage: AES-256 encryption for any file storage

Encryption in Transit

• HTTPS/TLS 1.2+: All API and web traffic
• Certificate Management: Let's Encrypt or Azure managed certificates
• Database Connections: SSL/TLS for PostgreSQL connections

Azure Key Vault Integration

Store sensitive configuration in Azure Key Vault:

// appsettings.json
{
  "AzureKeyVault": {
    "VaultUri": "https://deploybrief-kv.vault.azure.net/"
  }
}

// Access in code
var dbConnectionString = configuration["ConnectionStrings:DeployBrief"];
// Retrieved securely from Key Vault

Sensitive Data Handling

• Never log sensitive data: PATs, passwords, API keys
• Redact in responses: Return masked values like sk-***xyz
• Secure disposal: Overwrite sensitive data in memory

DeployBrief logs all security-relevant events to the audit_log table:

Logged Events

• User login/logout
• Workspace membership changes
• Azure DevOps connection creation/deletion
• API key creation/revocation
• Brief generation (who, when, preset used)
• Template and preset modifications
• Failed authentication attempts

Audit Log Schema

CREATE TABLE audit_log (
  id SERIAL PRIMARY KEY,
  timestamp TIMESTAMPTZ DEFAULT NOW(),
  user_id INTEGER REFERENCES users(id),
  workspace_id INTEGER REFERENCES workspaces(id),
  action VARCHAR(100) NOT NULL,
  resource_type VARCHAR(50),
  resource_id INTEGER,
  details JSONB,
  ip_address VARCHAR(45),
  user_agent VARCHAR(500)
);

Querying Audit Logs

-- Recent API key creations
SELECT * FROM audit_log 
WHERE action = 'api_key.created'
ORDER BY timestamp DESC LIMIT 10;

-- Connection activity for a user
SELECT * FROM audit_log
WHERE user_id = 123 AND resource_type = 'ado_connection'
ORDER BY timestamp DESC;

Retention Policy

• Retain for 90 days minimum (configurable)
• Archive to cold storage for compliance (1+ years)
• Automated cleanup: Remove logs older than retention period

Azure App Service Security

• Managed Identity: Access Azure resources without storing credentials
• Virtual Network Integration: Isolate backend resources
• Private Endpoints: Database access without public exposure
• IP Restrictions: Limit API access to known IPs (optional)

Rate Limiting

Protect against abuse with rate limits:

• API Endpoints: 100 requests/minute per API key
• Authentication: 10 failed login attempts → temporary lockout
• Brief Generation: 50 briefs/day per workspace

CORS Configuration

// Program.cs
builder.Services.AddCors(options => {
  options.AddPolicy("AllowUI", policy => {
    policy.WithOrigins("https://deploybrief.com")
          .AllowAnyMethod()
          .AllowAnyHeader()
          .AllowCredentials();
  });
}});

Security Checklist

• Azure DevOps PATs use minimum scopes
• PATs expire within 90 days
• API keys are scoped appropriately
• Secrets stored in Key Vault (not appsettings.json)
• HTTPS enforced for all endpoints
• Database connections use SSL/TLS
• Audit logging enabled
• Rate limiting configured
• Regular security updates applied
• Backup and disaster recovery plan in place

Incident Response

If a security incident occurs:

1. Identify: What data/credentials were exposed?
2. Contain: Revoke compromised keys/PATs immediately
3. Investigate: Review audit logs for unauthorized access
4. Remediate: Patch vulnerabilities, rotate credentials
5. Notify: Inform affected users if PII was exposed
6. Learn: Update policies to prevent recurrence

Regular Reviews

• Quarterly: Review API keys and PATs for expiration
• Monthly: Audit workspace memberships
• Weekly: Monitor audit logs for suspicious activity