필수 비밀 정보 보호 설정
Docker를 시작하거나 런타임을 등록하기 전에 서로 독립적인 무작위 32바이트 Base64 비밀 값 세 개를 설정하세요. 모든 노드가 같은 키를 사용하고 재시작 후에도 유지해야 합니다. HMAC_KEY와 JWT_KEY는 별도의 서명 비밀 값입니다. openssl rand -base64 32를 각각 세 번 실행하세요.
| Docker 환경 변수 | ASP.NET Core 설정 |
|---|---|
DB_ENCRYPTION_KEY | SecretProtection:DatabasePasswords:Keys:db-1 |
DML_ENCRYPTION_KEY | SecretProtection:DmlPayloads:Keys:dml-1 |
DML_FINGERPRINT_KEY | SecretProtection:DmlFingerprintKey |
SecretProtection:DatabasePasswords:ActiveKeyId는 db-1, SecretProtection:DmlPayloads:ActiveKeyId는 dml-1로 설정합니다. 누락되거나 잘못되거나 재사용된 키는 시작 실패를 일으킵니다. 예제의 자리표시자는 의도적으로 유효하지 않습니다.
HsSqlAgent.Hosting은 SecretProtection을 자동 바인딩합니다. 모듈형 호스트에서는 명시적으로 바인딩해야 합니다.
hs.AddHsSqlAgentRuntime(options =>
{
builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});새 bootstrap MCP 키에는 Bootstrap:Databases:*:McpKeys:*:Key 값을 명시하세요. 시작 시 키를 생성하거나 로그에 기록하지 않습니다. 기존 암호화 DB 비밀번호는 다시 입력해야 합니다. 기존 배포를 변경하기 전에 업그레이드 가이드를 읽으세요.
자격 증명 저장 및 키 교체
DB 비밀번호는 AES-256-GCM으로 암호화되며 용도와 신뢰할 수 있는 레코드의 SecretBindingId에 결합됩니다. 영속 실행 페이로드는 RequestId에 결합됩니다. 이전 형식 복호화 대체 경로는 없습니다. ICryptoService는 호출자가 전달하는 키 바이트 대신 컨텍스트 문자열을 받습니다.
암호화 키 링을 교체하려면 이전 키와 새 키를 서로 다른 ID로 모든 노드에 배포하고 ActiveKeyId를 변경한 뒤 비밀번호를 다시 저장하세요. 대기 또는 과거 페이로드를 조사해야 하는 동안에는 이전 DML 키를 유지하세요. 독립된 fingerprint key는 버전 관리되지 않습니다. 교체 전 승인을 모두 처리하고 과거 witness 조사를 위해 이전 비밀 값을 보관하세요.
ExtraSettings는 JSON 불리언 Encrypt와 TrustServerCertificate만 허용합니다. 알 수 없거나 중복된 필드, 문자열 값, 잘못된 JSON은 거부됩니다. 연결 테스트와 상태 점검은 드라이버 세부 정보 대신 일반적인 DB_CONNECTION_FAILED 메시지를 반환합니다.
Doctor의 security.secret-protection은 비밀 값을 반환하지 않고 키 ID, Base64 형식, 길이와 독립성을 검사합니다. 공개 예제 키는 Production 이외에서는 경고, Production에서는 오류이며 비활성 보관 키도 포함합니다. 잘못된 자리표시자는 모든 환경에서 오류입니다. 잘못된 설정은 Doctor가 준비되기 전 시작 검증에서 실패할 수 있습니다.
hs-sql-agent에는 세 가지 사용 방식이 있지만 보안 경계는 같습니다.
| 방식 | 설정 모델 |
|---|---|
| Docker / ToolBox | .env.example의 완전한 독립 서비스 환경 설정 |
HsSqlAgent.Hosting | ASP.NET Core configuration을 통한 동일한 표준 공식 구성 |
HsSqlAgent.Server | Host가 Capability별 Options를 명시적으로 선택 |
DML 승인
기본 공식 Provider는 MCP Elicitation입니다. 독립 Docker와 HsSqlAgent.Hosting은 SQL 실행 primitive를 바꾸지 않고 공식 범용 Webhook adapter로 전환할 수 있습니다.
| 환경 변수 | 용도 |
|---|---|
DML_APPROVAL_PROVIDER | McpElicitation 또는 Webhook |
DML_APPROVAL_WEBHOOK_ENDPOINT | 외부 승인 서비스 endpoint |
DML_APPROVAL_WEBHOOK_CALLBACK_URL | pending approval을 완료하는 공개 callback URL |
DML_APPROVAL_WEBHOOK_SIGNING_SECRET | Webhook signing secret, 최소 32 UTF-8 bytes |
{
"DmlApproval": {
"Provider": "Webhook",
"Webhook": {
"Endpoint": "https://approval.example.com/hssqlagent/requests",
"CallbackUrl": "https://sql-agent.example.com/api/hs-sql-agent/approvals/webhook",
"SigningSecret": "replace-with-a-unique-secret-at-least-32-bytes"
}
}
}알 수 없는 Provider 이름은 시작 시 실패합니다. 비동기 Provider는 Pending을 반환할 수 있으며 Durable Resume에는 보호된 Resume Intent와 Approval Fingerprint를 저장할 Admin Store가 필요합니다.
모듈형 HsSqlAgent.Server는 HsSqlAgent.Approvals.Webhook 또는 자체 IDmlApprovalProvider를 등록할 수 있습니다. 승인 Provider는 Database Connection, Transaction, 검증된 Plan, commit primitive를 받지 않습니다.
Application과 Control Plane
독립 서비스 설정에는 Application Hosting, Admin Database, MCP HMAC/Public Endpoint, 내장 Admin JWT, SMTP/Password Reset, OIDC/MFA, Bootstrap, Audit, Health, Delivery, Cache, Rate Limit, Policy Sync, Outbound Delivery Sync, SQL Concurrency, Prometheus, OTLP가 포함됩니다.
HMAC_KEY와 JWT_KEY는 서로 다른 32 bytes 이상의 secrets를 사용하세요. 보호된 Identity State를 사용할 때는 DATA_PROTECTION_KEY_PATH를 영속화합니다.
단일 Instance와 분산 Provider
단일 Instance는 SQLite Admin Database와 process-local Memory Provider를 사용할 수 있습니다. 여러 Instance에서는 공유 Admin Database와 Cache, Rate Limiting, Security Policy Sync, Outbound Delivery Sync, SQL Concurrency용 Redis-backed Provider를 사용합니다.
Observability
Prometheus는 PROMETHEUS_ENABLED, PROMETHEUS_HOST, PROMETHEUS_PORT의 별도 Listener를 사용하고 OTLP는 OTLP_ENDPOINT, OTEL_SERVICE_NAME으로 설정합니다.
Embedded .NET Host
HsSqlAgent.Hosting은 완전한 표준 구성을 소유합니다. HsSqlAgent.Server는 AddHsSqlAgentCore()에서 시작하고 선택된 Capability의 Options만 검증합니다. Host Authorization은 내장 Identity를 대체할 수 있고 DML 승인 Provider도 독립적으로 교체할 수 있습니다.
배포, ASP.NET Core 통합, Safe DML을 참고하세요.