CSP unsafe-inline 오류를 nonce와 hash로 해결하는 방법
인라인 스크립트를 허용해야 한다면 script-src에 'unsafe-inline'을 추가하기보다 동적 스크립트에는 예측할 수 없는 nonce를, 내용이 고정된 스크립트에는 정확한 본문으로 계산한 hash를 사용하세요. 헤더의 nonce 또는 hash와 HTML의 값이 한 글자라도 다르면 실행되지 않습니다.
CSP 오류는 정책이 고장 난 것이 아니라 브라우저가 허용 근거 없는 인라인 코드를 막았다는 신호입니다. 스크립트의 생성 방식부터 구분하면 보안 수준을 낮추지 않고도 필요한 코드만 좁게 실행할 수 있습니다.
먼저 보는 핵심 요약
- 서버가 매 요청마다 HTML을 만들면 응답별로 새 nonce를 생성해 CSP 헤더와 script 요소에 같은 값을 넣습니다.
- 내용이 바뀌지 않는 짧은 인라인 스크립트는 원문 바이트를 기준으로 계산한 SHA 계열 hash를 정책에 등록할 수 있습니다.
- 연결 도구는 허용 출처를 바탕으로 기본 헤더를 만들며 nonce·hash 생성과 HTML 주입은 애플리케이션에서 따로 구현합니다.
unsafe-inline 오류가 발생하는 정확한 이유
script-src가 선언된 페이지에서 nonce나 hash가 없는 인라인 script, 문자열 형태의 이벤트 처리기 등은 기본적으로 허용되지 않습니다. 콘솔 메시지에는 실제로 위반한 지시어와 차단된 코드 유형이 표시됩니다. 먼저 script-src인지 style-src인지 구분해야 잘못된 정책을 넓히는 일을 피할 수 있습니다.
nonce와 hash를 선택하는 기준
서버 렌더링 결과처럼 요청마다 내용이 달라지는 코드는 nonce가 적합합니다. nonce는 충분히 예측하기 어렵게 새로 만들고 같은 응답의 CSP 헤더와 허용할 요소에만 공유합니다. 빌드 결과가 고정된 부트스트랩 코드라면 hash가 배포 구조에 단순하지만, 공백이나 줄바꿈까지 바뀌면 다시 계산해야 합니다.
헤더와 HTML 값을 일치시키는 방법
nonce 방식은 응답 헤더의 'nonce-값'과 script 요소의 nonce 속성이 동일해야 합니다. hash 방식은 브라우저가 검사하는 인라인 코드 본문을 그대로 입력해 digest를 계산하고 'sha256-...' 같은 source expression으로 등록합니다. 따옴표, 줄바꿈, 자동 포매팅이 hash 입력을 바꾸지 않았는지 확인하세요.
차단을 재현하고 정책을 좁혀 가는 순서
개발자 도구 Network 탭에서 최종 응답의 Content-Security-Policy 값을 보고, Console의 위반 메시지와 대조합니다. 보고 전용 정책으로 먼저 관찰할 수 있지만 실제 차단 정책과 혼동해서는 안 됩니다. 허용 대상을 하나씩 추가한 뒤 새로고침해 불필요한 출처나 unsafe-inline 없이 기능이 동작하는지 확인합니다.
단계별로 확인하는 방법
- 차단된 코드 분류하기
콘솔에서 위반 지시어와 파일 위치를 확인하고 인라인 script, 이벤트 속성, 인라인 style 중 무엇인지 구분합니다.
- nonce 또는 hash 선택하기
요청마다 변하는 코드는 nonce, 빌드 후 본문이 고정되는 코드는 hash 방식으로 정합니다.
- 정책과 마크업 맞추기
CSP 헤더의 source expression과 HTML 요소의 nonce 또는 실제 코드 hash를 정확히 일치시킵니다.
- 배포 응답 다시 검증하기
최종 응답 헤더와 콘솔을 확인하고 기능 테스트 후 unsafe-inline과 사용하지 않는 허용 출처를 제거합니다.
판단 기준을 한눈에 비교하기
| 확인 항목 | 판단 기준 |
|---|---|
| 동적 서버 렌더링 코드 | 응답마다 새 값을 만들 수 있으므로 nonce 방식이 자연스럽습니다. |
| 고정 인라인 부트스트랩 | 본문이 변하지 않는다면 hash를 정책에 등록할 수 있습니다. |
| onclick 같은 이벤트 속성 | 외부 스크립트의 addEventListener로 옮기는 편이 유지보수와 정책 관리에 유리합니다. |
| 외부 CDN 스크립트 | nonce나 hash와 별도로 허용 출처, SRI, 로딩 경로를 함께 점검합니다. |
실행 전 체크리스트
- 콘솔에서 실제로 위반한 지시어를 확인했나요?
- nonce를 요청마다 새로 생성하고 재사용하지 않나요?
- hash 입력에 공백과 줄바꿈까지 포함했나요?
- 배포 응답에서 unsafe-inline이 제거됐는지 확인했나요?
주의할 점
연결된 CSP 생성기는 출처 기반 기본 정책 초안만 만듭니다. nonce나 hash 값을 생성하거나 HTML에 주입하지 않으며 기본 style-src에는 unsafe-inline이 포함될 수 있으므로, 실제 서비스에서는 프레임워크와 서버에 맞게 정책을 좁혀야 합니다. nonce를 소스 코드에 고정하거나 여러 응답에서 반복하지 마세요.
함께 보면 좋은 글
자주 묻는 질문
nonce는 페이지를 새로고침할 때마다 바뀌어야 하나요?
네. CSP nonce는 각 HTTP 응답에 대해 새롭고 예측하기 어려운 값을 사용하는 것이 기본입니다. 같은 응답 안에서는 헤더와 허용할 요소가 같은 값을 사용합니다.
hash는 파일 전체로 계산하나요?
인라인 script를 허용하는 hash라면 태그 자체가 아니라 브라우저가 검사하는 script 본문을 정확히 기준으로 계산합니다. 외부 파일의 SRI hash와 용도가 다릅니다.
style-src 오류에도 같은 원리를 쓸 수 있나요?
nonce와 hash source는 style-src에도 사용할 수 있지만 적용 대상과 브라우저 동작을 해당 정책 기준으로 확인해야 합니다. script-src 오류와 한꺼번에 처리하지 마세요.
Content-Security-Policy-Report-Only만 설정하면 보호되나요?
아닙니다. 보고 전용 헤더는 위반을 관찰하지만 차단하지 않습니다. 검증을 마친 정책은 실제 Content-Security-Policy 헤더로 적용해야 합니다.
근거와 출처
- W3C Content Security Policy Level 3 — 1차 출처, 조회일 2026-08-30
- MDN Content Security Policy 안내 — 보조 출처, 조회일 2026-08-30
도구에서 직접 확인하기
설명한 기준을 실제 값에 적용하려면 CSP 기본 헤더 생성기에서 작은 샘플부터 확인하세요. 원본과 결과를 나란히 비교한 뒤 실제 사용 환경에 적용하는 순서가 가장 안전합니다.
이 글은 알파카랩스 Utils의 개발 도구 도구와 함께 보는 정보성 가이드입니다. 규격과 외부 서비스 정책은 바뀔 수 있으므로 중요한 결정 전에는 연결된 공식 출처의 최신 내용을 다시 확인하세요.