Изоляция секретов (Enterprise)

Изоляция секретов — это enterprise функция, которая заменяет plaintext хранение переменных окружения на secure references к внешним secret managers. Вместо хранения API ключей и учётных данных напрямую в AACWorkflow, вы храните только reference (например path vault), который безопасно разрешается при запуске задачи и внедряется в окружение процесса агента.

Почему plaintext секреты опасны

Когда секреты хранятся как plaintext в базе данных:

• Случайное раскрытие — секреты могут появиться в transcripts агента или логах, если pattern-matching редакция не срабатывает
• Blast radius при взломе — если база данных AACWorkflow скомпрометирована, все секреты раскрыты
• Gaps compliance — многие стандарты (SOC 2, ISO 27001) требуют, чтобы секреты хранились вне базы приложения
• Нет audit trail — сложно отследить, кто получал доступ к каким секретам и когда

Как работают secret references

С включёнными secret references:

1. Вы определяете secret reference в Параметры → Secrets рабочего пространства
2. Reference указывает на secret в external manager (Vault, AWS Secrets Manager, GCP Secret Manager или переменные окружения вашего сервера)
3. Вы назначаете reference scope — какие агенты имеют доступ, какие repositories
4. Когда агент запускает задачу, AACWorkflow разрешает reference в actual value только в памяти
5. Значение внедряется в окружение процесса агента и никогда не хранится в базе AACWorkflow

Поддерживаемые secret managers

AACWorkflow поддерживает четыре backend resolver'а для секретов:

env (по умолчанию, встроенный)

• Как работает — секреты читаются из переменных окружения вашего сервера или файла
• Setup — установите AACWORKFLOW_SECRET_PROVIDER=env (или оставьте по умолчанию)
• Use case — разработка, малые команды или когда у вас нет external secret manager
• Безопасность — зависит от изоляции окружения вашего сервера

vault (HashiCorp Vault)

• Как работает — references указывают на ключи в Vault KV v2, разрешаются через Vault API
• Setup — настройте VAULT_ADDR и аутентификацию агента (token или Kubernetes auth)
• Use case — enterprise с существующей Vault инфраструктурой
• Безопасность — Vault обрабатывает шифрование at rest и in transit; AACWorkflow никогда не хранит plaintext

aws_sm (AWS Secrets Manager)

• Как работает — references — это ARN секретов в AWS Secrets Manager
• Setup — настройте AWS credentials для AACWorkflow (IAM role или keys)
• Use case — AWS-native deployments
• Безопасность — секреты зашифрованы и аудируются AWS; fine-grained IAM policies per secret

gcp_sm (GCP Secret Manager)

• Как работает — references — это resource names в GCP Secret Manager
• Setup — настройте GCP service account credentials для AACWorkflow
• Use case — GCP-native deployments
• Безопасность — секреты зашифрованы и аудируются GCP; IAM policies контролируют доступ

Установка secret references

Шаг 1: Настроить ваш secret manager

Выберите backend и установите соответствующие переменные окружения на вашем сервере AACWorkflow:

# Пример: HashiCorp Vault
export AACWORKFLOW_SECRET_PROVIDER=vault
export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=s.xxxxxxxxxxxxxxxx  # или используйте auth method

# Пример: AWS Secrets Manager
export AACWORKFLOW_SECRET_PROVIDER=aws_sm
export AWS_REGION=us-east-1
# (предполагает IAM role или ~/.aws/credentials)

Шаг 2: Создать секреты в external manager

Для Vault:

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

Для AWS Secrets Manager:

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

Шаг 3: Зарегистрировать reference в AACWorkflow

1. Перейдите в Параметры → Secrets рабочего пространства
2. Кликните Add Reference
3. Заполните:
   • Key — имя переменной окружения (например OPENAI_API_KEY)
   • Provider — выберите vault, aws_sm, gcp_sm или env
   • Handle — path или ARN в вашем secret manager
   • Scope (опциональный) — ограничьте конкретными агентами или repositories
4. Кликните Save

Шаг 4: Использовать reference в окружении агента

Когда вы устанавливаете переменную окружения агента, вы теперь можете выбрать:

• Literal value — хранить как plaintext (только для малых, доверенных значений)
• Secret reference — указать на ваш зарегистрированный secret

Например, вместо вставления OpenAI API ключа напрямую, установите:

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

При запуске задачи AACWorkflow разрешает этот reference и внедряет actual value в окружение агента.

Scoping секретов на агенты и repositories

Вы можете ограничить, какие агенты имеют доступ к секрету:

• Agents — список UUIDs агентов; только эти агенты могут разрешить reference
• Repositories — список имён repositories; секрет доступен только когда агент работает на этих repos

Например, секрет с scope.agents = [agent-1, agent-2] будет error если agent-3 попытается использовать его.

Как защищаются секреты

1. Plaintext никогда не хранится — разрешённые значения существуют только в памяти во время выполнения задачи
2. Внедрение, не раскрытие — секреты передаются через переменные окружения в процесс агента, никогда не отображаются в prompts или logах
3. Гарантированная редакция — все разрешённые значения добавляются в registry редакции и force-scrubbed из transcripts (структурная гарантия, не heuristic)
4. Audit trail — каждое разрешение секрета логируется с контекстом (агент, задача, timestamp) но не само значение
5. Rotation без re-deploy — ротация секрета в external manager берёт эффект при следующем запуске задачи; не требуется restart AACWorkflow

Backward compatibility

Если вы уже используете plaintext custom_env переменные, они продолжают работать. Вы можете мигрировать постепенно:

• Существующие plaintext значения в custom_env не затрагиваются
• Новые значения могут быть references
• Мешайте plaintext и references в одном окружении агента

Когда вы включаете новый secret reference, ваши агенты могут начать использовать его сразу без изменения кода.

Best practices

• Начните с high-risk секретов — API ключи, database пароли, токены. Мигрируйте их первыми.
• Используйте scope — ограничьте секреты только агентам и repositories, которые их нужны
• Ротируйте регулярно — ротируйте секреты в external manager каждые 90 дней
• Аудируйте доступ — проверяйте логи аудита в AACWorkflow (Параметры → Audit) и вашем secret manager
• Используйте возможности провайдера — включите шифрование, versioning и audit logging в Vault или вашем cloud провайдере

Дальнейшие шаги

• Enterprise governance features — другие элементы управления безопасностью на уровне рабочего пространства
• Approval policies — требуют рассмотрения для высокорискованных изменений
• Members and roles — понимание модели прав рабочего пространства