Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/api/springboot.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,7 +254,7 @@ Family catalog 요약:
| Monitoring | overview/resource-events/incidents list/detail/detail facade/report list/report body 200 | `WorkspaceAccessGuard.requireAccess` |
| Cluster | Kafka/connect/throughput 조회 200 | 인증 사용자, workspace scope 없음 |
| Internal `/internal` | tenant provision 200, tenant delete 202, pipeline provision 202 또는 422, status 200, delete 202 | internal control-plane surface |
| Internal `/internal/ops` read | health/version/tool-catalog 200, ready 200 또는 503, connector status/list, datasource list, SQL read, Kafka cluster info, topology/lag/log search/metrics/alerts/traces/task trace/incident summary 200 | agent-facing 내부 API. `internal.ops.token` 설정 시 `X-Internal-Token` service identity header가 필요하며, public frontend ingress는 이 경로를 프록시하지 않는다 |
| Internal `/internal/ops` read | health/version/tool-catalog 200, ready 200 또는 503, connector status/list, datasource list, SQL read, Kafka cluster info, topology/lag/log search/metrics/alerts/traces/task trace/incident summary 200 | agent-facing 내부 API. `internal.ops.token`과 일치하는 `X-Internal-Token` service identity header가 필요하며, public frontend ingress는 이 경로를 프록시하지 않는다 |
| Internal `/internal/ops` safe injection | connector fault injection create 200, cleanup 200, residuals 200 | 테스트/장애 주입용 내부 표면이며 runtime tool catalog에는 포함되지 않는다 |
| Internal `/internal/ops` mutation | connector restart/pause/resume, Kafka Connect consumer group restart: 성공 200, gate 실패 400/403/409, Connect 실패 502/504 | service identity gate 통과 후 controller가 `X-Agent-Run-Id`·`X-Agent-Step-Id`·`X-Idempotency-Key`를 필수 검증하고, `PolicyGuard` 결정에 따라 `X-Approval-Id` 또는 `X-Change-Ticket-Id`를 `MutationGate`에서 검증한다 |
| Internal governance | approvals create/preapproved 201, list/get/decision/validate 200, change-ticket create 201/approve 200/get/validate 200 | service identity gate 대상이다. approval decision과 change-ticket create/approve는 추가로 Spring Security principal이 필요하다 |
Expand All @@ -275,7 +275,7 @@ Family catalog 요약:
| `/api/v1/workspaces/{wsId}/kafka/principals` list | authenticated | workspace access |
| `/api/v1/workspaces/{wsId}/kafka/principals` create/deactivate/revoke/rotate/secret | authenticated | OWNER/ADMIN 또는 workspace owner. Secret 조회는 principal `ACTIVE`와 Secret 네이밍/키 무결성까지 확인 |
| `/api/v1/clusters/**` | authenticated | workspace scope 없음 |
| `/internal/ops/**` | optional service identity gate | `internal.ops.token` 설정 시 `X-Internal-Token`과 정확히 일치해야 한다. 토큰이 비어 있으면 로컬/기존 배포 호환을 위해 게이트가 비활성화된다. mutation은 추가로 agent headers/idempotency/policy approval 또는 change ticket/ownership을 코드에서 검증 |
| `/internal/ops/**` | service identity gate | `internal.ops.token`은 `X-Internal-Token`과 정확히 일치해야 한다. 토큰이 비어 있으면 fail-closed로 거부하며, 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 명시적으로 허용된다. mutation은 추가로 agent headers/idempotency/policy approval 또는 change ticket/ownership을 코드에서 검증 |
| `/internal/ops/approvals/{id}/decision` | service identity gate + method-level principal check | `SecurityContext`의 `AuthenticatedUser`가 `tenantId`/`decidedBy`와 일치하고 approval actor와 같아야 함 |

## Alias 제거
Expand All @@ -284,9 +284,9 @@ Family catalog 요약:

## 3. Common Headers

내부 운영 API(`/internal/ops/**`)는 public frontend ingress에 노출하지 않는 agent-facing API다. FastAPI가 내부 서비스 경로로 호출하며, `internal.ops.token`이 설정된 환경에서는 모든 `/internal/ops/**` 요청에 `X-Internal-Token` service identity header가 필요하다. agent 호출 추적에는 다음 헤더를 사용한다. `AgentHeaders`가 request id로 인정하는 이름은 `X-Agent-Request-Id`와 `X-Request-Id`이고, 둘 다 없거나 unsafe하면 서버가 UUID를 생성한다.
내부 운영 API(`/internal/ops/**`)는 public frontend ingress에 노출하지 않는 agent-facing API다. FastAPI가 내부 서비스 경로로 호출하며, 모든 `/internal/ops/**` 요청에는 `internal.ops.token`과 일치하는 `X-Internal-Token` service identity header가 필요하다. agent 호출 추적에는 다음 헤더를 사용한다. `AgentHeaders`가 request id로 인정하는 이름은 `X-Agent-Request-Id`와 `X-Request-Id`이고, 둘 다 없거나 unsafe하면 서버가 UUID를 생성한다.

- service identity: `X-Internal-Token` (설정된 경우 필수)
- service identity: `X-Internal-Token`
- request id: `X-Agent-Request-Id` 또는 `X-Request-Id`
- `X-Agent-Run-Id`
- `X-Agent-Step-Id`
Expand Down
2 changes: 1 addition & 1 deletion docs/design/backend-fastapi/server-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ Retrieval 에이전트의 **문서 RAG**([§1 Agent Principles](agent-principles
### 10. 보안

1. 현재 FastAPI route에는 frontend 사용자 JWT 검증 dependency가 연결되어 있지 않다.
2. Spring `/internal/ops/**`는 service-to-service identity gate로 보호한다(#646). FastAPI(spring_client)가 `X-Internal-Token`(설정 `AI_INTERNAL_OPS_TOKEN`)을 동봉하고, ops-backend는 `internal.ops.token`과 일치할 때만 허용한다. 토큰 미설정 시 게이트 비활성(로컬/기존 환경 호환) — gitops가 양쪽에 동일 시크릿을 주입해 활성화한다. 추가로 공개 진입점인 frontend는 `/internal/ops`를 프록시하지 않는다(에이전트 전용).
2. Spring `/internal/ops/**`는 service-to-service identity gate로 보호한다(#646). FastAPI(spring_client)가 `X-Internal-Token`(설정 `AI_INTERNAL_OPS_TOKEN`)을 동봉하고, ops-backend는 `internal.ops.token`과 일치할 때만 허용한다. 토큰 미설정은 fail-closed이며, 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 허용된다. 추가로 공개 진입점인 frontend는 `/internal/ops`를 프록시하지 않는다(에이전트 전용).
3. LLM output으로 API path를 직접 만들지 않는다.
4. tool allowlist 밖 요청은 거부한다.
5. Secret, token, connection string은 prompt와 report에 넣지 않는다.
Expand Down
2 changes: 1 addition & 1 deletion docs/design/backend-springboot/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
```

- `project_member.role`은 `OWNER`/`ADMIN`/`MEMBER`다. 멤버 목록 조회는 세 역할 모두 가능하고, workspace 수정·멤버 추가/수정/삭제·settings 수정은 `OWNER`/`ADMIN`만 가능하다.
- 내부 운영 API(`/internal/ops`)는 agent-facing 내부 API다. public frontend ingress는 이 경로를 프록시하지 않고, FastAPI가 내부 서비스 경로로 호출한다. `SecurityConfig`는 `internal.ops.token`이 설정된 경우 `X-Internal-Token` service identity header 일치를 요구하며, 토큰이 비어 있으면 로컬/기존 배포 호환을 위해 게이트를 비활성화한다. mutation controller는 여기에 더해 agent headers, approval, idempotency, project/resource ownership을 자체 검증한다([governance](./governance.md)).
- 내부 운영 API(`/internal/ops`)는 agent-facing 내부 API다. public frontend ingress는 이 경로를 프록시하지 않고, FastAPI가 내부 서비스 경로로 호출한다. `SecurityConfig`는 `internal.ops.token`과 `X-Internal-Token` service identity header 일치를 요구하며, 토큰이 비어 있으면 fail-closed로 거부한다. 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 허용된다. mutation controller는 여기에 더해 agent headers, approval, idempotency, project/resource ownership을 자체 검증한다([governance](./governance.md)).

### 5. 시드·보안

Expand Down
2 changes: 1 addition & 1 deletion docs/design/backend-springboot/governance.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
| governance facade | `/internal/ops/approvals/**`, `/internal/ops/change-tickets/**` |
| mutation subset | connector restart/pause/resume, Kafka Connect-managed consumer group restart |

`/internal/ops/**`는 agent-facing 내부 API이며 public frontend ingress에 노출하지 않는다. `SecurityConfig`는 `internal.ops.token`이 설정된 경우 `X-Internal-Token` service identity header 일치를 요구한다. 토큰이 비어 있으면 로컬/기존 배포 호환을 위해 게이트를 비활성화한다. Mutation controller가 추가로 적용하는 gate는 agent header, workspace/resource ownership, idempotency, `PolicyGuard` 기반 approval 또는 change-ticket, Kafka Connect REST 결과 mapping이다.
`/internal/ops/**`는 agent-facing 내부 API이며 public frontend ingress에 노출하지 않는다. `SecurityConfig`는 `internal.ops.token`과 `X-Internal-Token` service identity header 일치를 요구하며, 토큰이 비어 있으면 fail-closed로 거부한다. 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 명시적으로 허용된다. Mutation controller가 추가로 적용하는 gate는 agent header, workspace/resource ownership, idempotency, `PolicyGuard` 기반 approval 또는 change-ticket, Kafka Connect REST 결과 mapping이다.

### 2. Mutation 처리 순서

Expand Down
4 changes: 2 additions & 2 deletions docs/design/backend-springboot/server.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Spring Boot는 FastAPI Agent의 판단을 신뢰하지 않는다. FastAPI가 이

| 항목 | 설명 |
| --- | --- |
| service identity | `internal.ops.token` 설정 시 `X-Internal-Token` 일치를 요구한다. 토큰이 비어 있으면 로컬/기존 배포 호환을 위해 게이트가 비활성화된다 |
| service identity | `internal.ops.token`과 `X-Internal-Token` 일치를 요구한다. 토큰이 비어 있으면 fail-closed로 거부하며, 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 허용된다 |
| user/project scope | 요청 사용자가 project 권한을 갖는가 |
| resource ownership | resource가 해당 project 소유 또는 허용 범위인가 |
| operation allowlist | 현재는 controller endpoint와 `/internal/ops/admin/tool-catalog` 22개 항목이 agent-callable boundary |
Expand Down Expand Up @@ -328,7 +328,7 @@ Mutation timeout이 발생해도 Spring은 자동 재시도하지 않는다. Kaf
- idempotency replay가 중복 실행을 만들지 않아야 한다.
- before/after evidence row 생성은 `MutationGate` regression으로 확인하고, 현재 API regression 기준에서는 envelope field가 비어 있음을 확인한다.
- forbidden operation은 endpoint가 없거나 policy deny되어야 한다.
- `internal.ops.token`이 설정된 환경에서는 FastAPI service identity header가 없거나 다르면 실패해야 한다. 토큰 미설정 로컬/기존 환경은 호환을 위해 허용된다.
- FastAPI service identity header가 없거나 `internal.ops.token`과 다르면 실패해야 한다. 토큰 미설정은 fail-closed이며, 로컬/테스트 우회는 `internal.ops.auth-disabled=true`일 때만 허용된다.

### 14. 결론

Expand Down
2 changes: 1 addition & 1 deletion docs/test/agent-운영테스트-인벤토리.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ RCA 파이프라인: Classifier → (incident→rootcause map) → RCA evaluator

### B-4. 내부 토큰 우회 차단 (Spring 합동)
- agent는 Spring 호출에 `X-Internal-Token` 동봉([spring_client.py](services/ai-service/app/tools/spring_client.py)76-89), 승인 시 `X-Approval-Id` 동봉. **집행은 Spring SecurityConfig/MutationGate**.
- 측정: 무토큰으로 `/internal/ops/**` 직접 호출 시 401/403 차단율(=공개 API 우회 차단). 단 운영 토큰 설정 여부(`INTERNAL_OPS_TOKEN`) 먼저 확인 — 비면 게이트 비활성.
- 측정: 무토큰으로 `/internal/ops/**` 직접 호출 시 401/403 차단율(=공개 API 우회 차단). `INTERNAL_OPS_TOKEN` 미설정은 fail-closed이며, 로컬/테스트 우회는 `INTERNAL_OPS_AUTH_DISABLED=true`일 때만 허용된다.

---

Expand Down
Loading
Loading