Secret in Config Files

config.yaml, application.yml, .env, settings.json 같은 설정 파일에 Secret이 저장되면 코드 파일과 동일하게 유출 위험이 있습니다. 특히 설정 파일은 "코드가 아니니 괜찮다"는 오해로 인해 저장소에 커밋되는 경우가 많습니다.

이런 경우에 참고

config.yaml, application.yml, .env에 비밀번호나 토큰이 포함된 경우
config.yaml.example는 있는데 실제 config.yaml도 함께 커밋된 경우
설정 파일에서 운영 DB 비밀번호, API Key, OAuth Secret을 직접 들고 있는 경우

조치 원칙

Git에 포함되는 설정 파일에는 실제 Secret 값을 저장하지 않습니다.
저장소에는 예시 파일만 두고, 실제 값 파일은 커밋하지 않습니다.
애플리케이션은 환경 변수 또는 런타임에 공급되는 설정 파일을 통해 Secret을 읽도록 구성합니다.

어떤 세부 가이드를 봐야 하는가

환경 변수로 치환 가능한 경우: Secret 개요
config.yaml 같은 설정 파일 형식을 반드시 유지해야 하는 경우: 런타임 설정 파일 가이드
Kubernetes에서 설정 파일을 마운트해야 하는 경우: Kubernetes 가이드
Spring Boot에서 application.yml 또는 application-prod.yml을 사용하는 경우: Spring application.yml 사례
Go 서비스에서 config.yaml과 config.yaml.example를 함께 운영하는 경우: Go config.yaml 사례

최소 조치 원칙

저장소에 노출된 설정 파일의 Secret은 폐기 및 재발급합니다.
실제 운영 설정 파일은 Git에 포함하지 않습니다.
예시 파일과 실제 파일의 역할을 명확히 분리합니다.
로그, 에러 메시지, 디버그 출력에 Secret이 드러나지 않도록 합니다.

개발자 해야 할 일

설정 파일에 들어 있는 실제 Secret을 제거합니다.
예시 파일에는 형식만 남기고 실제 값은 제거합니다.
애플리케이션이 환경 변수 또는 런타임에 공급되는 설정 파일을 읽도록 수정합니다.
설정 dump, 에러 로그, 디버그 출력에 Secret 값이 포함되지 않도록 점검합니다.

인프라/플랫폼 해야 할 일

실제 설정 파일을 Git 대신 안전한 배포 경로로 공급합니다.
.gitignore와 배포 파이프라인에서 실제 설정 파일이 저장소로 역유입되지 않도록 관리합니다.
Kubernetes, Secret Manager, secure file delivery 중 운영 표준에 맞는 공급 방식을 선택합니다.
Secret 회전 절차와 재배포 또는 reload 절차를 정의합니다.

검증 방법

실제 운영 설정 파일이 저장소에 없는지 확인합니다.
예시 파일에 운영 Secret 값이 복사되어 있지 않은지 확인합니다.
로그와 에러 응답에 Secret 값이 노출되지 않는지 확인합니다.
배포 후 애플리케이션이 기대한 방식으로 Secret을 읽는지 확인합니다.

자주 하는 실수

config.yaml.example에 운영값을 그대로 복사
.gitignore는 했지만 이미 커밋된 파일을 그대로 방치
ConfigMap이나 Docker image에 설정 파일을 넣고도 안전하다고 판단
디버그 로그에 설정 객체 전체를 출력

담당자 조치 절차

노출된 자격 증명은 아래 파일 정리나 배포 변경을 기다리지 말고 먼저 폐기·비활성화하고 새 값으로 교체하세요.

설정 파일에 저장된 실제 Secret 값을 제거합니다.
실제 값 파일이 저장소에 올라갔다면 Git history 정리 여부를 검토합니다.
노출된 Secret은 폐기하고 새 값으로 재발급합니다.
.gitignore에 실제 설정 파일을 추가합니다.
설정 방식에 맞는 세부 가이드 문서로 이동해 수정 패턴을 적용합니다.

담당자에게 안내할 문구 예시

"설정 파일에 저장된 실제 Secret은 제거하고, 실제 운영값 파일은 Git에서 제외하세요."
"환경 변수로 바꿀 수 없다면 설정 파일 형식은 유지하되 실제 파일을 런타임에 안전하게 공급하세요."
"config.yaml.example에는 형식만 유지하고, 실제 config.yaml은 커밋 대상에서 제외하세요."

추가 확인 사항

.env 파일이 이미 커밋되었는가
예시 파일에 실제 운영값이 복사되어 있지 않은가
로그나 에러 메시지에 설정값이 출력되고 있지 않은가

관련 문서