위협 모델¶
English | 한국어
보호 대상¶
이 문서는 다음 정보에 대한 위협과 라이브러리의 보호 기능, 애플리케이션에서 별도로 관리할 영역을 설명합니다. **불투명 토큰(opaque token)**은 탐지된 개인정보를 대신하는 문자열로, 원문 값을 직접 드러내지 않습니다.
- 모델 입력, 검색 콘텐츠, 도구 입력·결과와 최종 출력에 포함될 수 있는 원문 개인정보(PII).
- 요청별
PrivacySession을 통해 관리되는 불투명 토큰과 개인정보 원문 값 사이의 매핑. - 원격 분석 서비스에 사용하는 인증 정보와 분석 요청·응답.
- 도구마다 공개 가능한 엔티티 유형을 정의한 원문 값 공개 정책.
- Spring Security 통합을 활성화한 경우, 현재 사용자의 권한에 따른 도구 공개·실행 허용 여부.
신뢰 경계¶
개인정보 보호를 구성하면 라이브러리가 지원하는 연동 경로에서 모델·도구에 전달할 데이터를 검사하고 보호합니다. 다른 경로로 전달하는 데이터는 애플리케이션에서 관리해야 합니다.
Presidio 같은 원격 분석 서비스에는 검사할 원문 텍스트가 전송됩니다. 원격 분석 서비스와 모델 제공자의 인증 정보 관리, 전송 보안 설정과 데이터 보존 정책 확인은 애플리케이션의 책임입니다.
사용자 정의 분석기, Advisor와 도구 구현은 신뢰할 수 있는 애플리케이션 코드라는 전제에서 사용합니다. 라이브러리는 탐지 결과를 검증하고 지원하는 처리 지점에서 데이터를 보호하지만, 그 밖에서 애플리케이션 코드가 수행하는 동작까지 제한하지는 않습니다.
Spring Security 통합은 애플리케이션의 인증 방식과 도구 권한 정책을 사용합니다. 개인정보 보호를 함께 적용하면, 도구를 등록하거나 실행을 허용하는 것만으로는 원문 공개가 허용되지 않습니다. 불투명 토큰을 원문으로 복원할 수 있는 엔티티 유형을 도구별로 따로 설정해야 합니다.
위협과 통제¶
모델 입력과 출력¶
| 위협 | 라이브러리의 통제 |
|---|---|
| 모델 입력·최종 응답의 개인정보 노출 | 지원되는 모델 입력 텍스트에서 탐지된 개인정보를 모델 호출 전에 불투명 토큰으로 바꿉니다. 출력 보호를 활성화하면 최종 응답의 본문과 지원하는 추론 텍스트에 설정한 출력 정책을 적용합니다. |
구조화된 값·스트리밍·returnDirect를 통한 검사 우회 |
JSON과 지원되는 값 구조는 크기와 복잡도 상한을 적용해 검사합니다. 출력 보호를 활성화하면 스트리밍 응답을 끝까지 모아 검사하고, returnDirect 결과에도 설정한 출력 정책을 적용합니다. |
| 지원하지 않는 메시지 형식을 통한 검사 우회 | 지원하지 않는 Message 구현은 모델에 전달하지 않고 오류로 처리합니다. |
보호 범위와 고려사항
- 보호 범위: 지원하지 않는 콘텐츠와 최종 개인정보 검사 이후에 추가·변경된 데이터는 자동 보호 범위에 포함되지 않습니다.
- 인코딩·압축된 콘텐츠: 인코딩되거나 압축되어 원문을 바로 읽을 수 없는 콘텐츠는 검사 전에 애플리케이션에서 텍스트나 지원되는 JSON 형태로 변환해야 합니다.
- 메타데이터와 미디어: 지원하는 추론 텍스트를 제외한 응답 메타데이터와 이미지·오디오 같은 비텍스트 콘텐츠는 별도로 보호해야 합니다. 미디어 제한은 데이터 크기만 확인하며 내용의 개인정보를 탐지하지 않습니다.
도구 개인정보 보호와 권한¶
| 위협 | 라이브러리의 통제 |
|---|---|
| 허용되지 않은 원문 전달·도구 결과의 새 개인정보 | 개인정보 보호를 적용한 도구에서는 불투명 토큰의 원문 복원을 기본적으로 허용하지 않습니다. 명시한 엔티티 유형만 실행 직전에 복원하며, 도구 결과에서 탐지된 개인정보는 다음 단계로 전달하기 전에 불투명 토큰으로 바꿉니다. |
| 사용자 정의 Advisor·도구 경로의 보호 단계 누락 | 라이브러리의 표준 개인정보 보호 구성을 적용한 ChatClient에서는 필수 Advisor의 누락·중복과 보호되지 않은 도구 콜백을 확인합니다. |
| 권한 없는 도구 공개·실행 | Spring Security 통합을 구성하면 거부된 도구는 모델에 제공할 목록에서 제외하며, 이름으로 요청해도 실행하지 않습니다. 한 모델 응답에서 요청한 도구 전체의 권한을 먼저 확인한 뒤 실행을 시작합니다. 각 도구의 실행 직전에 다시 확인하며, 개인정보 보호도 활성화한 경우에는 원문 복원 전에 확인합니다. |
| 권한 확인 뒤 콜백 추가·교체 | Spring Security 통합을 구성하면 요청 시작 시 확인한 도구 콜백을 기준으로, 지원하지 않는 콜백 추가·교체를 실행 전에 거부합니다. |
보호 범위와 고려사항
- 도구 개인정보 보호: 원문 복원과 도구 결과의 개인정보 토큰화는
PrivacyToolCallbackFactory로 감싼 도구에 적용합니다. 그 밖의 실행 경로는 별도로 보호해야 합니다. - 사용자 정의 실행 경로: 개인정보 보호 경계 밖에서 데이터를 변경하는 Advisor나 사용자 정의
ToolCallingManager·ToolCallbackResolver를 사용하는 별도 실행 경로는 애플리케이션에서 보호해야 합니다. - 도구 권한 검사: Spring Security 통합을 구성한 클라이언트에 적용합니다. 이 검사를 거치지 않고 도구를 직접 호출하는 경로는 보호 범위에 포함되지 않습니다. 지원하는 구성은 Spring Security 도구 권한을 참고하세요.
- 인증과 데이터 접근: 인증과 권한 정책의 정확성은 애플리케이션의 책임입니다. 도구 인자의 고객번호 등에 따른 개별 데이터 접근 권한은 해당 도구나 서비스에서 검사해야 합니다.
- 요청 중 권한 변경: 권한 검사는 요청 시작 시 확보한 인증 정보를 사용합니다. 장시간 요청 중 권한 철회를 반영하려면 정책이 현재 외부 상태를 조회해야 합니다.
탐지와 진단¶
| 위협 | 라이브러리의 통제 |
|---|---|
| 유효하지 않거나 겹치는 탐지 결과·분석기 실패 | 라이브러리는 탐지 결과의 위치와 엔티티 유형을 검증합니다. 결과가 겹치거나 유형이 충돌하면 정해진 규칙에 따라 정리하고, 분석기 실패는 설정한 실패 정책에 따라 처리합니다. |
| 오류·진단 정보의 개인정보 노출 | 라이브러리가 생성하는 개인정보 보호 오류와 분석기 실패 알림에는 개인정보 원문 값이나 분석 서비스의 응답 내용을 넣지 않습니다. |
보호 범위와 고려사항
- 외부 오류와 로그: 모델 제공자와 도구의 오류 메시지 및 SDK 로그는 각 구성 요소의 설정에 따라 관리해야 합니다.
세션과 자원 사용¶
| 위협 | 라이브러리의 통제 |
|---|---|
| 다른 요청의 불투명 토큰 재사용·유효하지 않은 세션 접근 | 불투명 토큰과 원본 값의 매핑은 요청별 PrivacySession을 통해 각각 관리됩니다. 다른 요청의 불투명 토큰은 원본 값으로 복원하지 않으며, 알 수 없거나 종료된 세션은 오류로 처리합니다. |
| 요청 종료 뒤 세션에 남은 개인정보 | 표준 개인정보 보호 구성을 적용한 Spring AI 요청이 정상 완료되거나 오류·스트림 취소로 끝나면 라이브러리가 관리하는 불투명 토큰과 원문 값의 매핑을 정리합니다. 이 매핑 자체는 모델 요청이나 도구 입력에 포함하지 않습니다. |
| 매우 크거나 깊게 중첩된 입력으로 인한 자원 소모 | 라이브러리는 지원되는 텍스트·JSON과 값 구조, 응답을 검사할 때 크기·개수·중첩 깊이 등의 상한을 적용합니다. |
보호 범위와 고려사항
- API 직접 사용:
PrivacyService를 직접 사용하는 경우에는 애플리케이션이 각PrivacySession의 수명주기를 관리하고 세션을 닫아야 합니다. - 실행 제한: 사용자 정의 분석기와 도구의 실행 시간 및 자원 제한은 애플리케이션에서 설정해야 합니다. 스트림 취소는 세션을 정리하지만 이미 실행 중인 동기식 분석기나 도구 코드를 강제로 중단하지는 않습니다.
정확한 정책과 처리 상한은 설정을 참고하세요.
중요한 한계¶
개인정보 보호는 설정한 분석기가 탐지한 콘텐츠에 적용됩니다. 모든 민감한 값을 항상 탐지하거나 분류한다고 보장하지는 않습니다. 탐지 범위는 분석기와 신뢰도 기준에 따라 달라지며, 일부 분석기의 실패를 허용하면 성공한 결과만으로 처리를 계속하므로 범위가 줄어들 수 있습니다. 자세한 내용은 탐지와 해석을 참고하세요.
개인정보를 불투명 토큰으로 바꾸어도 익명화가 보장되지는 않습니다. 불투명 토큰과 세션 식별자(PrivacyContextHandle)를
사용자 인증이나 권한의 근거로 사용해서는 안 됩니다.
세션 정리는 라이브러리가 보유한 매핑을 해제합니다. 저장소에 이미 저장한 데이터나 다른 구성 요소가 보관한 문자열·사본까지 삭제하지는 않습니다.
Spring Security 통합은 모델에 공개할 도구와 실행 가능한 도구를 제어합니다. 개인정보
보호와 함께 사용해도 tools.disclosures에 설정한 도구별·엔티티 유형별 공개 범위가
적용되며, 권한 검사를 활성화한다고 이 설정이 사용자별로 달라지지는 않습니다.
별도로 관리할 영역¶
이 문서의 보호 기능은 라이브러리의 개인정보 보호 API와 지원하는 Spring AI 연동을 사용할 때 적용됩니다. 다음 항목은 애플리케이션과 배포 환경에서 별도로 관리해야 합니다.
- 프롬프트 주입과 모델 콘텐츠 안전성.
- 애플리케이션·호스트 보안, 인증, 권한 정책 설계, 권한 검사를 거치지 않는 도구 호출, 저장소 접근 제어, 네트워크 보안과 로그 관리.
- 모델·분석 서비스의 데이터 보존 정책과 법률·규제 준수.