Security Best Practices Guide

This guide covers security considerations for deploying and using StateSet Sandbox, including isolation options, secret management, network policies, and compliance.

Security Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                            API Gateway                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │ TLS Termination │ Rate Limiting │ API Key Auth │ CORS │ WAF        │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                         Controller                                        │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────────────┐  │
│  │ Input      │  │ Auth/Authz │  │ Secret     │  │ Audit Logging     │  │
│  │ Validation │  │            │  │ Management │  │                   │  │
│  └────────────┘  └────────────┘  └────────────┘  └───────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                         Sandbox Isolation                                 │
│  ┌─────────────────────┐  ┌─────────────────────────────────────────┐   │
│  │ Container           │  │ gVisor / Kata / Firecracker             │   │
│  │ ├─ seccomp          │  │ ├─ Separate kernel/VM per sandbox       │   │
│  │ ├─ AppArmor         │  │ ├─ Memory isolation                     │   │
│  │ ├─ Resource limits  │  │ └─ Full syscall filtering               │   │
│  │ └─ Network policies │  │                                         │   │
│  └─────────────────────┘  └─────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────────┘

Isolation Levels

Isolation is enforced at the Kubernetes pod level via RuntimeClass (and your cluster’s configured runtimes).

Container: default runtime (no RuntimeClass)
gVisor: a gVisor RuntimeClass (often named gvisor)
MicroVM: a Kata/Firecracker RuntimeClass (often named kata-qemu)

In the Node controller, SANDBOX_RUNTIME_CLASS is applied to all sandbox pods:

# Example: run sandboxes under gVisor
SANDBOX_RUNTIME_CLASS=gvisor

The sandbox create API accepts an isolation field (container | gvisor | microvm) which is currently used for warm pool profile matching and labeling; the actual isolation boundary is provided by the RuntimeClass.

API Key Security

Key Management

Generate strong keys:
openssl rand -base64 32
Use environment variables (never hardcode):
export STATESET_API_KEY="sk_..."

Rotate keys regularly:

# Create new key
curl -X POST https://api.sandbox.stateset.com/api/v1/api-keys \
  -H "Authorization: ApiKey $OLD_KEY" \
  -d '{"name": "production-v2"}'

# Update your systems with new key

# Revoke old key
curl -X DELETE https://api.sandbox.stateset.com/api/v1/api-keys/$OLD_KEY_ID \
  -H "Authorization: ApiKey $NEW_KEY"

Use scoped keys when possible:
- Read-only keys for monitoring
- Limited keys for specific sandboxes

Key Storage

Environment	Recommendation
Development	`.env` file (gitignored)
CI/CD	Pipeline secrets (GitHub Actions, GitLab CI)
Production	Secret manager (Vault, AWS Secrets Manager, GCP Secret Manager)
Kubernetes	Kubernetes Secrets (encrypted at rest)

Secret Management

StateSet stores secrets at the organization level and injects them into sandbox pods as environment variables at creation time.

Create / Update Secrets (BYOK)

# Create a secret (values are never returned after creation)
curl -X POST https://api.sandbox.stateset.com/api/v1/secrets \
  -H "Authorization: ApiKey $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ANTHROPIC_API_KEY",
    "value": "sk-ant-REDACTED",
    "scope": "sandbox"
  }'

# Update a secret
curl -X PUT https://api.sandbox.stateset.com/api/v1/secrets/ANTHROPIC_API_KEY \
  -H "Authorization: ApiKey $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk-ant-REDACTED" }'

Security properties:

Encrypted at rest in Postgres using AES-256-GCM (DATABASE_ENCRYPTION_KEY is required in production when DATABASE_URL is set)
Never logged or returned by list endpoints
Persist until deleted (not tied to a single sandbox lifetime)
Can be restricted to specific sandboxes using allowed_sandbox_patterns

Secret Access Logging

Enable audit logging for secret access:

AUDIT_LOGS_ENABLED=true

Query audit logs:

SELECT * FROM secret_access_log
WHERE secret_name = 'OPENAI_API_KEY'
ORDER BY accessed_at DESC;

Network Security

Default Network Policy

In the provided Kubernetes manifests (k8s/network-policy.yaml), sandbox pods:

Allow ingress only from the controller
Allow egress only to:
- DNS (kube-dns)
- TCP 443 to a Cloudflare IP allowlist (to reach api.anthropic.com)

This is intentionally restrictive and IP-based (NetworkPolicy cannot match by DNS name). If you need broader egress or DNS-aware allowlisting, use an egress proxy/service mesh or a CNI with DNS-aware policies (e.g., Cilium).

Custom Network Policies

Create Kubernetes NetworkPolicy for additional restrictions:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sandbox-egress
  namespace: stateset-sandbox
spec:
  podSelector:
    matchLabels:
      app: stateset-sandbox
  policyTypes:
    - Egress
  egress:
    # Allow DNS
    - to:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              k8s-app: kube-dns
      ports:
        - protocol: UDP
          port: 53
    # Allow HTTPS only
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
              - 169.254.0.0/16
      ports:
        - protocol: TCP
          port: 443

Webhook URL Validation

Webhooks cannot target:

localhost
Private IP addresses
Cluster-internal services

Webhook requests:

Follow up to 3 redirects
Block cross-host redirects
Block HTTPS→HTTP downgrades

Input Validation

Path Traversal Prevention

All file paths are validated:

No .. components allowed
Must be within sandbox workspace
Absolute paths normalized

# Rejected
"/workspace/../etc/passwd"
"../../secrets"

# Allowed
"/workspace/src/app.py"
"/workspace/data.json"

Command Injection Prevention

Prefer passing commands as arrays to avoid shell interpolation. If you send a string command, the controller executes it via sh -c.

# Recommended (no shell)
sdk.sandbox.execute(sandbox_id, ["ls", "-la", "/workspace"])

# String form is supported, but uses a shell:
sdk.sandbox.execute(sandbox_id, "ls -la /workspace")

Request Size Limits

Limit	Default	Max
File content (per file)	10MB	10MB (hard limit)
JSON request body	10MB	10MB (hard limit)
Files per request	100	100 (hard limit)
Stripe webhook payload	1MB	5MB (via `STRIPE_WEBHOOK_MAX_BYTES`)

Pod Security

Security Context

Sandbox pods run with restricted security context:

securityContext:
  runAsUser: 1001
  runAsGroup: 1001
  runAsNonRoot: true
  readOnlyRootFilesystem: true  # When enabled
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

Service Account

Sandboxes use a dedicated service account without cluster access:

automountServiceAccountToken: false
enableServiceLinks: false

Configuration:

SANDBOX_AUTOMOUNT_SERVICE_ACCOUNT_TOKEN=false
SANDBOX_ENABLE_SERVICE_LINKS=false

Resource Limits

All sandboxes have enforced limits:

resources:
  limits:
    cpu: "2"
    memory: "4Gi"
    ephemeral-storage: "10Gi"
  requests:
    cpu: "100m"
    memory: "128Mi"

Database Security

Encryption at Rest

Sensitive values stored in the database (e.g., organization secrets and webhook secrets) are encrypted with AES-256-GCM. API keys are stored as one-way hashes (not reversible); only prefixes are returned for display. Configuration:

DATABASE_ENCRYPTION_KEY=<64-hex-character-key>

Generate key:

openssl rand -hex 32

Connection Security

# Use SSL for database connections
DATABASE_URL="postgres://user:pass@host:5432/sandbox?sslmode=require"

Access Control

Use separate database users:

Application user with limited permissions
Migration user for schema changes
Read-only user for analytics

Authentication & Authorization

JWT Configuration

# Strong secret (minimum 32 characters)
JWT_SECRET=$(openssl rand -base64 32)

# Short token lifetime for security
JWT_EXPIRY=3600  # 1 hour

Admin Access

Protect admin endpoints:

ADMIN_API_KEY=<strong-unique-key>
# Or use username/password
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=<bcrypt-hash>

Generate bcrypt hash:

const bcrypt = require('bcrypt');
console.log(bcrypt.hashSync('your-password', 10));

Internal Endpoints

Protect internal endpoints (/metrics, /health/detailed):

INTERNAL_API_KEY=<internal-key>

Audit Logging

Enable Audit Logs

AUDIT_LOGS_ENABLED=true

Logged Events

Sandbox creation/termination
Command execution
File operations
Secret access
API key operations
Admin actions

Log Format

{
  "timestamp": "2024-01-21T12:00:00.000Z",
  "event": "sandbox.created",
  "org_id": "org-123",
  "user_id": "user-456",
  "sandbox_id": "sb-abc789",
  "ip_address": "203.0.113.50",
  "user_agent": "StateSet-SDK/1.0.0",
  "details": {
    "cpus": "2",
    "memory": "4Gi"
  }
}

Log Retention

Configure retention policy based on compliance requirements:

SOC2: 1 year minimum
HIPAA: 6 years
GDPR: Document justification for retention period

Production Hardening Checklist

Environment Configuration

NODE_ENV=production
DEV_MODE=false
LOG_LEVEL=info (not debug/trace)

Authentication

JWT_SECRET is unique, 32+ characters
ADMIN_API_KEY is set and strong
INTERNAL_API_KEY is set for metrics
API keys are rotated regularly

Database

DATABASE_ENCRYPTION_KEY is set (64 hex chars)
SSL enabled for database connection
Database credentials are from secret manager
Regular backups configured

Network

CORS restricted to your domains: CORS_ORIGIN=https://app.example.com
TLS/HTTPS enforced
WEBHOOK_ALLOW_PRIVATE=false
WS_ALLOW_QUERY_AUTH=false (legacy/deprecated; query-token auth is disabled for Events/WebSocket)

Sandbox Security

SANDBOX_READ_ONLY_ROOT=true
SANDBOX_AUTOMOUNT_SERVICE_ACCOUNT_TOKEN=false
SANDBOX_ENABLE_SERVICE_LINKS=false
Appropriate isolation level set
Resource limits configured

Monitoring

AUDIT_LOGS_ENABLED=true
Metrics collection configured
Alerting for security events
Log aggregation configured

Incident Response

Suspicious Activity

Identify: Check audit logs for anomalies

Contain: Suspend affected organization

curl -X POST https://api.sandbox.stateset.com/api/admin/orgs/$ORG_ID/suspend \
  -H "Authorization: Bearer $ADMIN_KEY"

Investigate: Review logs, metrics, sandbox contents
Remediate: Revoke compromised keys, patch vulnerabilities
Document: Post-incident report

Key Compromise

Revoke the compromised key immediately
Generate new keys
Audit recent activity with the compromised key
Notify affected users
Review how the key was exposed

Data Breach Response

Assess scope of breach
Contain the breach (suspend orgs, terminate sandboxes)
Notify affected parties per GDPR/regulatory requirements
Document timeline and response
Improve security controls

Compliance Considerations

SOC2

Enable audit logging
Encrypt data at rest
Implement access controls
Monitor for anomalies
Document security policies

Document data processing purposes
Implement data retention policies
Support data export and deletion
Log consent and access
Appoint DPO if required

HIPAA

Sign BAA with cloud providers
Enable audit logging
Encrypt all PHI
Implement access controls
Train staff on HIPAA

Security Contacts

Security issues: security@stateset.com
Bug bounty: https://stateset.com/security/bounty
Security documentation: https://stateset.com/security

​Security Best Practices Guide

​Security Architecture

​Isolation Levels

​API Key Security

​Key Management

​Key Storage

​Secret Management

​Create / Update Secrets (BYOK)

​Secret Access Logging

​Network Security

​Default Network Policy

​Custom Network Policies

​Webhook URL Validation

​Input Validation

​Path Traversal Prevention

​Command Injection Prevention

​Request Size Limits

​Pod Security

​Security Context

​Service Account

​Resource Limits

​Database Security

​Encryption at Rest

​Connection Security

​Access Control

​Authentication & Authorization

​JWT Configuration

​Admin Access

​Internal Endpoints

​Audit Logging

​Enable Audit Logs

​Logged Events

​Log Format

​Log Retention

​Production Hardening Checklist

​Environment Configuration

​Authentication

​Database

​Network

​Sandbox Security

​Monitoring

​Incident Response

​Suspicious Activity

​Key Compromise

​Data Breach Response

​Compliance Considerations

​SOC2

​GDPR

​HIPAA

​Security Contacts