306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
# PII Masking 기준
|
|
|
|
## 1. 목적
|
|
|
|
이 문서는 로그, 트레이스, 운영 이벤트 기록에서 개인정보(PII)와 민감정보를 어떻게 마스킹하거나 제거할지 정의한다.
|
|
|
|
이 문서의 목표는 다음과 같다.
|
|
|
|
- 운영에 필요한 관측 가능성을 유지하면서 민감정보 노출을 막는다
|
|
- 로그 레벨과 무관하게 보호해야 하는 데이터를 명확히 한다
|
|
- 마스킹 책임을 개별 개발자 습관이 아니라 공통 규칙으로 만든다
|
|
- request/response, exception, external API payload, structured logging 모두에 같은 기준을 적용한다
|
|
|
|
## 2. 근거 수준
|
|
|
|
- Official: OWASP, Spring Boot 공식 문서에서 직접 확인되는 내용
|
|
- Official + Practice: 공식 가이드 위에 일반적인 운영/보안 관행을 결합한 내용
|
|
- Project Recommendation: 이 프로젝트 구조와 운영 방식에 맞춘 규칙
|
|
|
|
## 3. 기본 원칙
|
|
|
|
### 3.1 민감정보 보호는 예외가 아니라 기본값이다
|
|
|
|
OWASP는 세션 식별값, 액세스 토큰, 민감한 개인정보, 비밀번호, DB 연결 문자열, 암호화 키, 결제 데이터 등은 로그에 직접 기록하지 말고 제거·마스킹·정제·해시·암호화하라고 권고합니다. 따라서 이 프로젝트에서는 “필요할 때만 숨긴다”가 아니라 기본적으로 숨기고, 꼭 필요한 최소 정보만 남긴다를 원칙으로 둔다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 민감정보는 기본 비기록(non-log) 이 원칙
|
|
- 필요하면 원문 대신 마스킹/해시/요약값을 남긴다
|
|
- “디버깅 중이라서”, “DEBUG니까”, “내부망이라서” 같은 이유로 예외를 만들지 않는다
|
|
|
|
### 3.2 로그 레벨이 낮다고 민감정보를 찍어도 되는 것은 아니다
|
|
|
|
OWASP는 민감정보 자체를 직접 기록하지 말라고 하며, 이는 특정 로그 레벨에 한정된 예외를 두지 않습니다. 이 프로젝트도 DEBUG/TRACE를 보안 예외 구간으로 취급하지 않는다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- INFO, DEBUG, TRACE 모두 같은 마스킹 규칙을 따른다
|
|
- 낮은 레벨은 더 자세할 수 있을 뿐, 더 위험한 데이터를 허용하는 레벨이 아니다
|
|
|
|
### 3.3 민감정보 마스킹은 로깅 호출부와 공통 로깅 파이프라인이 함께 책임진다
|
|
|
|
Spring Boot는 MDC를 로그 패턴과 structured logging JSON에 포함할 수 있고, JSON 필드의 include/exclude/rename/add와 customizer도 지원합니다. 따라서 민감정보 보호는 “개발자가 매번 조심해서 안 찍는 것”만으로 끝내지 않고, 공통 로깅 구성을 통한 2차 방어선도 둘 수 있다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 1차 방어: 애플리케이션 코드에서 원문을 로그 인자로 넘기지 않는다
|
|
- 2차 방어: 공통 로깅 설정/structured logging customizer/appender 등에서 추가 마스킹을 검토한다
|
|
- 둘 중 하나만 믿지 않는다
|
|
|
|
## 4. 데이터 분류 규칙
|
|
|
|
### 4.1 절대 원문 기록 금지 데이터
|
|
|
|
OWASP 기준으로 직접 기록하지 말아야 할 대표 데이터는 다음과 같습니다. 세션 식별값, 액세스 토큰, 민감한 개인정보와 일부 PII, 인증 비밀번호, DB 연결 문자열, 암호화 키 및 주요 비밀값, 은행 계좌/카드 정보 등이 여기에 해당합니다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
다음은 원문 로그 금지 다.
|
|
|
|
- 비밀번호
|
|
- access token / refresh token / bearer token
|
|
- session id / cookie session value / JWT raw token
|
|
- DB connection string
|
|
- encryption key / signing key / secret key / API secret
|
|
- 카드번호 / 계좌번호 / 결제 식별정보 원문
|
|
- 주민등록번호/여권번호/정부 식별번호류
|
|
- 건강정보, 법적으로 민감한 개인정보
|
|
- 외부 시스템 인증 헤더 원문
|
|
- source code, stack dump 속 비밀 설정값
|
|
|
|
### 4.2 기본적으로 직접 기록하지 않는 데이터
|
|
|
|
OWASP는 민감한 개인정보 외에도 personal names, telephone numbers, email addresses, internal network names/addresses, file paths 등은 특별한 취급이 필요할 수 있다고 설명합니다. 이 프로젝트에서는 다음 데이터도 원문 기록을 기본값으로 두지 않는다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
다음은 원문 비권장 이며, 필요 시 축약/부분 마스킹/내부 식별자 대체를 우선한다.
|
|
|
|
- 이메일 전체값
|
|
- 전화번호 전체값
|
|
- 개인 이름 전체값
|
|
- 내부 IP/호스트명/내부 네트워크 이름
|
|
- 로컬 파일 경로
|
|
- 상세 주소
|
|
- 주민등록번호 일부를 유추할 수 있는 조합값
|
|
|
|
### 4.3 운영에 필요한 식별자는 내부 식별자를 우선한다
|
|
|
|
OWASP는 direct/indirect identifier에 대해 de-identification을 검토하라고 권고합니다. 이 프로젝트에서는 사람이 직접 식별되는 값보다 내부 식별자를 우선 남기는 방향을 기본으로 한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- email 대신 userId
|
|
- accountNumber 대신 accountId
|
|
- phoneNumber 대신 customerId
|
|
- 꼭 외부 식별자가 필요하면 일부만 남긴다
|
|
|
|
## 5. 처리 방식 규칙
|
|
|
|
### 5.1 제거, 마스킹, 해시, 암호화의 기본 선택
|
|
|
|
OWASP는 민감값을 제거, 마스킹, 정제, 해시, 암호화 중 적절한 방식으로 처리하라고 설명합니다. 이 프로젝트는 다음 우선순위를 권장한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 가장 먼저 검토: 아예 기록하지 않기
|
|
- 운영 식별이 필요: 부분 마스킹
|
|
- 동일 값 상관관계만 필요: 해시/토큰화
|
|
- 정말 복구 가능한 보관이 필요: 별도 보호 저장소를 검토하고 일반 애플리케이션 로그에는 두지 않는다
|
|
|
|
### 5.2 부분 마스킹 규칙
|
|
|
|
프로젝트 권장 예:
|
|
|
|
- 이메일: do***@example.com
|
|
- 전화번호: 010-****-1234
|
|
- 카드번호: ************1234
|
|
- 계좌번호: ******7890
|
|
- 주민번호류: 기본 로그 금지, 부분 마스킹도 최소화
|
|
- 토큰/세션 ID: 원문 금지, 필요하면 앞/뒤 일부 + 해시 일부
|
|
|
|
### 5.3 해시 사용 규칙
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 같은 값의 반복 여부만 추적하면 될 때 해시 사용 가능
|
|
- salt/secret이 필요한 경우 보안 정책을 따른다
|
|
- 해시값도 장기 식별자로 과도하게 남용하지 않는다
|
|
- 원문 복구가 필요한 요구를 해시로 해결하려 하지 않는다
|
|
|
|
## 6. 위치별 규칙
|
|
|
|
### 6.1 request logging
|
|
|
|
OWASP는 HTTP request body, response body, headers 같은 확장 상세 정보는 민감할 수 있으므로 특별한 주의가 필요하다고 설명합니다. 이 프로젝트에서는 request logging에서 다음을 기본 금지한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- request body 전문 로그 금지
|
|
- Authorization 헤더 원문 금지
|
|
- Cookie 헤더 원문 금지
|
|
- query string 전체 로그 금지
|
|
- multipart 파일명/본문 원문 금지
|
|
|
|
허용 가능한 예:
|
|
|
|
- requestPath
|
|
- method
|
|
- contentType
|
|
- payloadBytes
|
|
- allowlist된 소수의 비민감 query field
|
|
|
|
### 6.2 response logging
|
|
|
|
프로젝트 규칙:
|
|
|
|
- response body 전문 로그 금지
|
|
- token 발급 응답, 인증 응답, 결제 응답 원문 금지
|
|
- 상태코드, duration, 외부 시스템 상태, 응답 크기 같은 메타데이터만 우선 기록한다
|
|
|
|
### 6.3 exception logging
|
|
|
|
OWASP는 stack trace, system error messages, debug information, request/response body 등이 민감해질 수 있다고 설명합니다. 따라서 예외 로그는 stack trace를 남기더라도 민감 데이터를 포함한 message/context를 같이 남기지 않도록 조심해야 한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 예외 메시지에 포함된 민감정보 원문을 그대로 로그 제목에 사용하지 않는다
|
|
- log.error(ex.getMessage(), ex)를 기본값으로 두지 않는다
|
|
- 사건 설명 + 안전한 식별자 + 예외 객체 순으로 기록한다
|
|
- stack trace에 비밀값이 포함될 위험이 있는 경로는 별도 검토한다
|
|
|
|
### 6.4 external API / integration logging
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 외부 요청/응답 payload 전문 로그 금지
|
|
- 외부 API key, bearer token, cookie 원문 금지
|
|
- provider 이름, endpoint path, status, duration, request id 같은 메타데이터만 우선 기록
|
|
- third-party error body도 민감정보를 포함할 수 있으므로 원문 그대로 남기지 않는다
|
|
|
|
### 6.5 audit/security logging
|
|
|
|
OWASP는 보안/감사 로그도 중요하지만, 그렇다고 민감값을 그대로 기록하라는 뜻은 아니라고 설명합니다. “무엇이 일어났는지”는 남기되, 값 원문은 보호해야 한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- “비밀번호 변경 시도”, “토큰 재발급 요청”, “민감 데이터 조회” 같은 사건 자체는 기록
|
|
- 하지만 실제 비밀번호, 토큰, 데이터 원문은 기록하지 않는다
|
|
- audit log가 필요하면 일반 운영 로그와 목적을 구분한다
|
|
|
|
## 7. structured logging / MDC 규칙
|
|
|
|
### 7.1 MDC에 넣는 값도 같은 기준으로 마스킹한다
|
|
|
|
Spring Boot는 MDC 값을 로그 패턴과 structured JSON에 포함할 수 있고, ECS/GELF/Logstash 포맷에서도 MDC key-value가 JSON에 들어갑니다. 따라서 MDC는 안전한 공통 필드만 넣는 용도로 써야 한다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- MDC에는 traceId, requestPath, actorId, operation, clientIp(필요 시) 정도의 안전한 메타데이터만 둔다
|
|
- MDC에 token, email 전체값, session id, raw principal object를 넣지 않는다
|
|
- “MDC니까 괜찮다”는 예외를 두지 않는다
|
|
|
|
### 7.2 structured logging JSON 필드도 마스킹 정책 대상이다
|
|
|
|
Spring Boot는 structured JSON에서 include/exclude/rename/add, customizer를 지원합니다. 이는 JSON 로그가 plain text보다 안전하다는 뜻이 아니라, 같은 보호 규칙을 중앙에서 적용할 수 있다는 뜻에 가깝다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- structured logging을 쓰면 JSON field 수준 마스킹/제외 규칙을 검토한다
|
|
- 수집 시스템에 맞춘 필드 rename은 허용하지만, 민감 필드 유입 자체를 방지하는 것이 우선이다
|
|
- ingestion 단계에서 추가 마스킹이 가능해도 애플리케이션 단계의 원문 출력 금지를 대체하지 않는다
|
|
|
|
## 8. 로그 인젝션 방지 규칙
|
|
|
|
### 8.1 외부 입력은 로깅 전에 sanitization을 고려한다
|
|
|
|
OWASP는 다른 trust zone에서 들어오는 이벤트 데이터는 형식 검증을 하고, CR/LF 및 delimiter 같은 문자를 정제해 로그 인젝션을 막으라고 권고합니다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 사용자 입력, 외부 시스템 응답, 헤더, query parameter를 로그에 넣기 전 길이/형식 검토
|
|
- CR/LF, 탭, 구분자, 제어문자 정제
|
|
- multi-line injection이 가능한 원문을 그대로 로그 메시지에 넣지 않는다
|
|
|
|
### 8.2 예외 메시지와 외부 오류 메시지도 신뢰하지 않는다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 외부 시스템의 에러 메시지를 그대로 로그 제목에 사용하지 않는다
|
|
- 예외 메시지를 한 줄 요약/정제 후 보조 정보로만 사용한다
|
|
- 로그 제목은 애플리케이션이 통제하는 문장으로 쓴다
|
|
|
|
## 9. 구현 규칙
|
|
|
|
### 9.1 공통 마스킹 유틸/컴포넌트를 둔다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 이메일, 전화번호, 토큰, 계좌/카드 마스킹은 공통 유틸이나 formatter로 제공한다
|
|
- 서비스마다 제각각 다른 마스킹 패턴을 쓰지 않는다
|
|
- 로그 메시지 안에서 직접 substring으로 잘라 쓰는 임시 구현을 줄인다
|
|
|
|
### 9.2 logger 호출 전에 안전한 값으로 변환한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- log.info("...", rawToken) 금지
|
|
- log.info("...", maskedToken(rawToken)) 형태로만 허용
|
|
- 가능하면 값을 마스킹한 뒤 변수에 담아 의미 있는 이름으로 사용한다
|
|
|
|
### 9.3 가능한 경우 중앙 로깅 구성에서 2차 필터링을 둔다
|
|
|
|
Spring Boot는 structured logging JSON customizer와 MDC 기반 필드 구성을 지원합니다. 이를 이용해 민감 필드가 특정 이름으로 유입될 경우 제거/대체하는 2차 방어선을 둘 수 있다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- authorization, accessToken, password, sessionId 같은 공통 금지 키는 중앙 필터링을 검토한다
|
|
- 다만 중앙 필터링이 있으니 코드에서 원문을 찍어도 된다는 뜻은 아니다
|
|
|
|
## 10. 테스트/검증 규칙
|
|
|
|
### 10.1 로그에 금지 데이터가 실제로 남지 않는지 검증한다
|
|
|
|
OWASP는 로깅 메커니즘의 설계/구현/검증을 강조합니다. 이 프로젝트도 마스킹 정책을 문서만 두지 않고 테스트/리뷰 대상으로 본다.
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 주요 인증/결제/개인정보 흐름은 로그 검증 테스트를 둘 수 있다
|
|
- 보안 리뷰 체크리스트에 “민감정보 로그 노출 여부”를 포함한다
|
|
- 샘플 로그/운영 로그 점검으로 정책 위반을 찾아낸다
|
|
|
|
### 10.2 규칙 위반은 기능 버그가 아니라 보안 버그로 취급한다
|
|
|
|
프로젝트 규칙:
|
|
|
|
- 토큰/비밀번호/세션 ID/PII 원문 노출은 보안 결함으로 분류
|
|
- “로그일 뿐”이라고 축소하지 않는다
|
|
- 수정 우선순위를 높게 둔다
|
|
|
|
## 11. 금지 규칙
|
|
|
|
다음은 기본 금지다.
|
|
|
|
- 비밀번호 원문 로그
|
|
- access token / refresh token / session id / cookie 값 원문 로그
|
|
- Authorization 헤더 원문 로그
|
|
- request/response body 전문 로그
|
|
- 이메일/전화번호/이름 등 개인식별자 전체값 무비판적 로그
|
|
- 외부 API secret, DB connection string, key material 로그
|
|
- DEBUG/TRACE라는 이유로 민감정보 예외 허용
|
|
- MDC/structured JSON에 민감정보 적재
|
|
- CR/LF 등 제어문자 포함 원문을 그대로 로그에 기록
|
|
|
|
## 12. 체크리스트
|
|
|
|
다음 질문에 “예”로 답할 수 있어야 한다.
|
|
|
|
- 이 값은 정말 로그에 남겨야 하는가?
|
|
- 원문 대신 내부 식별자/마스킹/해시로 충분하지 않은가?
|
|
- 토큰, 세션 ID, 비밀번호, key material, 결제정보가 원문으로 남지 않는가?
|
|
- request/response 전문을 기본 로그에 넣고 있지 않은가?
|
|
- MDC와 structured logging 필드에도 같은 보호 규칙이 적용되는가?
|
|
- 외부 입력을 로그에 넣기 전에 sanitization을 검토했는가?
|
|
- 공통 마스킹 유틸/구성과 코드 레벨 금지 규칙이 함께 적용되는가?
|