비밀 격리(엔터프라이즈)

비밀 격리는 명문 환경 변수 저장소를 외부 비밀 관리자에 대한 보안 참조로 바꾸는 엔터프라이즈 기능입니다. API 키와 자격증명을 AACWorkflow에 직접 저장하는 대신, 참조(예: 보관소 경로)만 저장하고, 작업 시작 시 안전하게 확인되어 에이전트 프로세스 환경에 주입됩니다.

명문 비밀이 위험한 이유

비밀이 데이터베이스에 명문으로 저장되면:

• 실수로 인한 노출 — 패턴 일치 편집에 실패하면 비밀이 에이전트 기록이나 로그에 나타날 수 있음
• 침해 시 피해 범위 — AACWorkflow 데이터베이스가 손상되면 모든 비밀 노출
• 준수 간격 — 많은 표준(SOC 2, ISO 27001)은 비밀을 응용 프로그램 데이터베이스 외부에 저장할 것을 요구
• 감시 추적 없음 — 누가 어떤 비밀에 언제 접근했는지 추적하기 어려움

비밀 참조 작동 방식

비밀 참조를 활성화한 경우:

1. 워크스페이스 설정 → 비밀에서 비밀 참조 정의
2. 참조는 외부 관리자(Vault, AWS Secrets Manager, GCP Secret Manager 또는 서버 환경)의 비밀을 가리킴
3. 참조에 범위 할당 — 어느 에이전트가 접근, 어느 저장소
4. 에이전트가 작업을 시작하면 AACWorkflow가 참조를 실제 값으로 확인(메모리 전용)
5. 값이 에이전트 프로세스 환경에 주입되고 AACWorkflow 데이터베이스에 저장되지 않음

지원되는 비밀 관리자

AACWorkflow는 네 가지 비밀 확인 백엔드를 지원합니다:

env(기본값, 내장)

• 작동 방식 — 서버 환경 변수 또는 파일에서 비밀 읽음
• 설정 — AACWORKFLOW_SECRET_PROVIDER=env 설정(또는 기본값 유지)
• 사용 사례 — 개발, 소규모 팀 또는 외부 비밀 관리자가 없는 경우
• 보안 — 서버 환경 격리에 따라 달라짐

vault(HashiCorp Vault)

• 작동 방식 — 참조는 Vault KV v2의 키를 가리키며 Vault API를 통해 확인
• 설정 — VAULT_ADDR 및 에이전트 인증 구성(토큰 또는 Kubernetes 인증)
• 사용 사례 — 기존 Vault 인프라를 보유한 엔터프라이즈
• 보안 — Vault가 정지 및 전송 중 암호화 처리; AACWorkflow는 명문을 저장하지 않음

aws_sm(AWS Secrets Manager)

• 작동 방식 — 참조는 AWS Secrets Manager의 비밀 ARN
• 설정 — AACWorkflow에 대한 AWS 자격증명 구성(IAM 역할 또는 키)
• 사용 사례 — AWS 원본 배포
• 보안 — AWS가 암호화 및 감시; 비밀별 세밀한 IAM 정책

gcp_sm(GCP Secret Manager)

• 작동 방식 — 참조는 GCP Secret Manager의 리소스 이름
• 설정 — AACWorkflow에 대한 GCP 서비스 계정 자격증명 구성
• 사용 사례 — GCP 원본 배포
• 보안 — GCP가 암호화 및 감시; IAM 정책이 액세스 제어

비밀 참조 설정

단계 1: 비밀 관리자 구성

백엔드를 선택하고 AACWorkflow 서버에 적절한 환경 변수를 설정합니다:

# 예: HashiCorp Vault
export AACWORKFLOW_SECRET_PROVIDER=vault
export VAULT_ADDR=https://vault.example.com
export VAULT_TOKEN=s.xxxxxxxxxxxxxxxx  # 또는 인증 방법 사용

# 예: AWS Secrets Manager
export AACWORKFLOW_SECRET_PROVIDER=aws_sm
export AWS_REGION=us-east-1
# (IAM 역할 또는 ~/.aws/credentials가 구성되어 있다고 가정)

단계 2: 외부 관리자에서 비밀 생성

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: AACWorkflow에서 참조 등록

1. 워크스페이스 설정 → 비밀로 이동
2. 참조 추가 클릭
3. 작성:
   • 키 — 환경 변수 이름(예: OPENAI_API_KEY)
   • 제공자 — vault, aws_sm, gcp_sm 또는 env 선택
   • 핸들 — 비밀 관리자의 경로 또는 ARN
   • 범위(선택 사항) — 특정 에이전트 또는 저장소로 제한
4. 저장 클릭

단계 4: 에이전트 환경에서 참조 사용

에이전트의 환경 변수를 설정할 때 이제 선택할 수 있습니다:

• 리터럴 값 — 명문으로 저장(소규모, 신뢰할 수 있는 값만)
• 비밀 참조 — 등록된 비밀 가리키기

예를 들어 OpenAI API 키를 직접 붙여넣는 대신 설정합니다:

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

작업 시작 시 AACWorkflow는 이 참조를 확인하고 실제 값을 에이전트 환경에 주입합니다.

에이전트 및 저장소에 대한 비밀 범위 지정

비밀에 접근할 수 있는 에이전트를 제한할 수 있습니다:

• 에이전트 — 에이전트 UUID 목록; 이 에이전트만 참조를 확인할 수 있음
• 저장소 — 저장소 이름 목록; 에이전트가 이 저장소에서 작동할 때만 비밀 사용 가능

예를 들어 scope.agents = [agent-1, agent-2]인 비밀은 agent-3이 사용하려고 할 때 오류가 발생합니다.

비밀 보호 방식

1. 명문 저장 안 함 — 확인된 값은 작업 실행 중 메모리에만 존재
2. 주입, 노출 없음 — 비밀은 환경 변수를 통해 에이전트 프로세스로 전달되며 프롬프트나 로그에 렌더링되지 않음
3. 보장된 편집 — 모든 확인된 값이 편집 레지스트리에 추가되고 기록에서 강제 제거(휴리스틱이 아닌 구조 보증)
4. 감시 추적 — 모든 비밀 확인이 컨텍스트(에이전트, 작업, 타임스탬프)와 함께 기록되지만 값 자체는 아님
5. 재배포 없이 회전 — 외부 관리자에서 비밀 회전이 다음 작업 시작 시 적용; AACWorkflow 재시작 필요 없음

하위 호환성

이미 명문 custom_env 변수를 사용하는 경우 계속 작동합니다. 점진적으로 마이그레이션할 수 있습니다:

• custom_env의 기존 명문 값은 영향 없음
• 새 값은 참조가 될 수 있음
• 동일 에이전트 환경에서 명문과 참조 혼합

새 비밀 참조를 활성화하면 에이전트가 코드 변경 없이 즉시 사용 시작할 수 있습니다.

모범 사례

• 고위험 비밀부터 시작 — API 키, 데이터베이스 암호, 토큰. 먼저 이들을 마이그레이션합니다.
• 범위 사용 — 비밀을 필요로 하는 에이전트 및 저장소로만 제한
• 정기적으로 회전 — 외부 관리자에서 90일마다 비밀 회전
• 액세스 감시 — AACWorkflow(설정 → 감시)와 비밀 관리자에서 감시 로그 검토
• 제공자 기능 사용 — Vault 또는 클라우드 제공자에서 암호화, 버전 관리 및 감시 로깅 활성화

다음 단계

• 엔터프라이즈 거버넌스 기능 — 기타 워크스페이스 범위 보안 제어
• 승인 정책 — 고위험 변경에 대한 검토 요구
• 멤버와 역할 — 워크스페이스 권한 모델 이해