Secrets Isolation (Enterprise)

Secrets isolation is an enterprise feature that replaces plaintext environment variable storage with secure references to external secret managers. Instead of storing API keys and credentials directly in AACWorkflow, you store only a reference (e.g., a vault path), which is resolved securely at task-launch time and injected into the agent's process environment.

Why plaintext secrets are risky

When secrets are stored as plaintext in the database:

• Accidental exposure — secrets can appear in agent transcripts or logs if pattern-matching redaction fails
• Blast radius on breach — if the AACWorkflow database is compromised, all secrets are exposed
• Compliance gaps — many standards (SOC 2, ISO 27001) require secrets to be stored outside the application database
• No audit trail — it's hard to track who accessed which secrets and when

How secret references work

With secret references enabled:

1. You define a secret reference in workspace Settings → Secrets
2. The reference points to a secret in an external manager (Vault, AWS Secrets Manager, GCP Secret Manager, or your server's environment)
3. You assign the reference a scope — which agents are allowed to access it, which repositories
4. When an agent starts a task, AACWorkflow resolves the reference to the actual value in-memory only
5. The value is injected into the agent's process environment and never stored in AACWorkflow's database

Supported secret managers

AACWorkflow supports four secret resolver backends:

env (default, built-in)

• How it works — secrets are read from your server's environment variables or a file
• Setup — set AACWORKFLOW_SECRET_PROVIDER=env (or leave unset for default)
• Use case — development, small teams, or when you don't have an external secret manager
• Security — depends on your server's environment isolation

vault (HashiCorp Vault)

• How it works — references point to keys in Vault KV v2, resolved via Vault API
• Setup — configure VAULT_ADDR and agent authentication (token or Kubernetes auth)
• Use case — enterprise with existing Vault infrastructure
• Security — Vault handles encryption at rest and in transit; AACWorkflow never stores the plaintext

aws_sm (AWS Secrets Manager)

• How it works — references are ARNs of secrets in AWS Secrets Manager
• Setup — configure AWS credentials for AACWorkflow (IAM role or keys)
• Use case — AWS-native deployments
• Security — secrets encrypted and audited by AWS; fine-grained IAM policies per secret

gcp_sm (GCP Secret Manager)

• How it works — references are resource names in GCP Secret Manager
• Setup — configure GCP service account credentials for AACWorkflow
• Use case — GCP-native deployments
• Security — secrets encrypted and audited by GCP; IAM policies control access

Setting up secret references

Step 1: Configure your secret manager

Choose your backend and set the appropriate environment variables on your AACWorkflow server:

# Example: HashiCorp Vault
export AACWORKFLOW_SECRET_PROVIDER=vault
export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=s.xxxxxxxxxxxxxxxx  # or use auth method

# Example: AWS Secrets Manager
export AACWORKFLOW_SECRET_PROVIDER=aws_sm
export AWS_REGION=us-east-1
# (assumes IAM role or ~/.aws/credentials is configured)

Step 2: Create secrets in your external manager

For Vault:

vault kv put secret/aacworkflow/ws-<workspace-id>/OPENAI_API_KEY \
  value=sk-...

For AWS Secrets Manager:

aws secretsmanager create-secret \
  --name aacworkflow/ws-<workspace-id>/OPENAI_API_KEY \
  --secret-string sk-...

Step 3: Register the reference in AACWorkflow

1. Go to workspace Settings → Secrets
2. Click Add Reference
3. Fill in:
   • Key — the environment variable name (e.g., OPENAI_API_KEY)
   • Provider — select vault, aws_sm, gcp_sm, or env
   • Handle — the path or ARN in your secret manager
   • Scope (optional) — restrict to specific agents or repositories
4. Click Save

Step 4: Use the reference in agent environment

When you set an agent's environment variable, you can now choose:

• Literal value — store as plaintext (small, trusted values only)
• Secret reference — point to your registered secret

For example, instead of pasting the OpenAI API key directly, set:

{
  "OPENAI_API_KEY": {"$secretRef": "OPENAI_API_KEY"}
}

At task launch, AACWorkflow resolves this reference and injects the actual value into the agent's environment.

Scoping secrets to agents and repositories

You can restrict which agents are allowed to access a secret:

• Agents — list of agent UUIDs; only these agents can resolve the reference
• Repositories — list of repository names; the secret is only available when the agent works on those repos

For example, a secret with scope.agents = [agent-1, agent-2] will error if agent-3 tries to use it.

How secrets are protected

1. Plaintext never stored — resolved values exist only in memory during task execution
2. Injection, not exposure — secrets are passed via environment variables to the agent's process, never rendered into prompts or logs
3. Guaranteed redaction — all resolved values are added to the redaction registry and force-scrubbed from transcripts (structural guarantee, not heuristic)
4. Audit trail — every secret resolution is logged with context (agent, task, timestamp) but not the value itself
5. Rotation without re-deploy — rotating a secret in your external manager takes effect on the next task launch; no AACWorkflow restart needed

Backward compatibility

If you're already using plaintext custom_env variables, they continue to work. You can migrate gradually:

• Existing plaintext values in custom_env are unaffected
• New values can be references
• Mix plaintext and references in the same agent environment

When you enable a new secret reference, your agents can start using it immediately without code changes.

Best practices

• Start with high-risk secrets — API keys, database passwords, tokens. Migrate these first.
• Use scope — restrict secrets to only the agents and repositories that need them
• Rotate regularly — rotate secrets in your external manager every 90 days
• Audit access — review audit logs in AACWorkflow (Settings → Audit) and your secret manager
• Use your provider's features — enable encryption, versioning, and audit logging in Vault or your cloud provider

Next steps

• Enterprise governance features — other workspace-wide security controls
• Approval policies — require review for high-risk changes
• Members and roles — understand workspace permission model