Laravel Csp
spatie/laravel-csp
Laravel 앱의 응답에 CSP 헤더를 추가합니다
기본적으로 웹 페이지의 모든 스크립트는 원하는 어떤 사이트로든 데이터를 보내고 가져올 수 있습니다. 이는 보안 문제가 될 수 있습니다. 예를 들어 사용 중인 JavaScript 의존성 하나가 비밀번호를 포함한 모든 키 입력을 제3자 웹사이트로 몰래 전송한다고 상상해 보세요.
이런 악의적인 동작은 숨기기가 매우 쉬워서, 사이트의 JavaScript 코드를 직접 모두 읽어 보지 않는 이상 발견하기가 거의 불가능합니다. 콘텐츠 보안 정책(Content Security Policy) 헤더가 왜 꼭 필요한지 더 잘 이해하려면 David Gilbertson이 쓴 이 훌륭한 블로그 글을 읽어 보세요.
Content Security Policy 헤더를 설정하면 이 문제를 줄일 수 있습니다. 이 헤더는 여러분의 사이트가 어떤 사이트와 통신할 수 있는지를 브라우저에 알려 줍니다. 이 패키지를 사용하면 알맞은 헤더를 손쉽게 설정할 수 있습니다.
이 문서는 CSP와 각 디렉티브(directive)의 모든 사용법을 자세히 설명하는 것을 목표로 하지 않습니다. 패키지를 사용하기 전에 Mozilla의 Content Security Policy 문서를 먼저 읽어 보시기를 강력히 권장합니다. CSP를 배우기에 좋은 또 다른 자료로 Stephen Rees-Carter의 Larasec 뉴스레터 중 이 호도 있습니다.
후원하기
저희는 최고 수준의 오픈 소스 패키지를 만드는 데 많은 자원을 쏟고 있습니다. 유료 제품 중 하나를 구매해 주시면 저희를 후원하실 수 있습니다.
또한 여러분의 고향에서 보낸 엽서를 받을 수 있다면 정말 감사하겠습니다. 어떤 패키지를 사용하고 계신지 함께 적어 주세요. 주소는 문의 페이지에서 확인하실 수 있습니다. 받은 엽서는 모두 온라인 엽서 벽에 게시하고 있습니다.
설치
이 패키지는 PHP 8.3 이상, Laravel 12 또는 13이 필요합니다.
Composer로 패키지를 설치할 수 있습니다.
composer require spatie/laravel-csp다음 명령으로 설정 파일을 퍼블리시할 수 있습니다.
php artisan vendor:publish --tag=csp-configconfig/csp.php에 퍼블리시되는 파일의 내용은 다음과 같습니다.
return [
/*
* Presets will determine which CSP headers will be set. A valid CSP preset is
* any class that implements `Spatie\\Csp\\Preset`
*/
'presets' => [
Spatie\\Csp\\Presets\\Basic::class,
],
/**
* Register additional global CSP directives here.
*/
'directives' => [
// [Directive::SCRIPT, [Keyword::UNSAFE_EVAL, Keyword::UNSAFE_INLINE]],
],
/*
* These presets which will be put in a report-only policy. This is great for testing out
* a new policy or changes to existing CSP policy without breaking anything.
*/
'report_only_presets' => [
//
],
/**
* Register additional global report-only CSP directives here.
*/
'report_only_directives' => [
// [Directive::SCRIPT, [Keyword::UNSAFE_EVAL, Keyword::UNSAFE_INLINE]],
],
/*
* All violations against a policy will be reported to this url.
* A great service you could use for this is https://report-uri.com/
*/
'report_uri' => env('CSP_REPORT_URI', ''),
/*
* Optional separate report url for the report-only policy. When empty,
* the report-only policy falls back to `report_uri` above.
*/
'report_only_uri' => env('CSP_REPORT_ONLY_URI', ''),
/*
* The name of the reporting endpoint that violations should be sent to.
* The endpoint itself must be defined in `reporting_endpoints` below.
*/
'report_to' => env('CSP_REPORT_TO', ''),
/*
* Optional separate reporting endpoint name for the report-only policy.
* When empty, the report-only policy falls back to `report_to` above.
*/
'report_only_to' => env('CSP_REPORT_ONLY_TO', ''),
/*
* Reporting endpoints that will be sent in the `Reporting-Endpoints` HTTP
* header. The keys are the endpoint names that can be referenced from
* `report_to` above.
*/
'reporting_endpoints' => [
// 'default' => 'https://example.com/csp-reports',
],
/*
* Headers will only be added if this setting is set to true.
*/
'enabled' => env('CSP_ENABLED', true),
/**
* Headers will be added when Vite is hot reloading.
*/
'enabled_while_hot_reloading' => env('CSP_ENABLED_WHILE_HOT_RELOADING', false),
/*
* The class responsible for generating the nonces used in inline tags and headers.
*/
'nonce_generator' => Spatie\\Csp\\Nonce\\RandomString::class,
/*
* Set false to disable automatic nonce generation and handling.
* This is useful when you want to use 'unsafe-inline' for scripts/styles
* and cannot add inline nonces.
* Note that this will make your CSP policy less secure.
*/
'nonce_enabled' => env('CSP_NONCE_ENABLED', true),
];bootstrap/app.php에서 Spatie\Csp\AddCspHeaders::class를 글로벌 미들웨어로 등록하면 앱의 모든 응답에 CSP 헤더를 추가할 수 있습니다.
use Spatie\\Csp\\AddCspHeaders;
->withMiddleware(function (Middleware $middleware) {
$middleware->append(AddCspHeaders::class);
})또는 라우트나 라우트 그룹 단위로 미들웨어를 적용할 수도 있습니다.
// In your routes file
Route::get('my-page', 'MyController')
->middleware(AddCspHeaders::class);미들웨어에 프리셋 클래스를 파라미터로 넘길 수도 있습니다.
// In your routes file
Route::get('my-page', 'MyController')
->middleware(AddCspHeaders::class . ':' . MyPreset::class);이렇게 지정한 프리셋은 해당 라우트(또는 라우트 그룹)에 한해 config/csp.php 설정 파일에 지정된 프리셋을 덮어씁니다.
이 밖에 Blade 디렉티브를 사용해 CSP 정책을 메타 태그로 등록하는 방법도 있습니다.
{{-- app/layout.blade.php --}}
<head>
@cspMetaTag
</head>사용법
이 패키지는 시작하기 편하도록 자주 쓰이는 프리셋 몇 가지를 기본으로 제공합니다. 더 많은 서비스에 대한 PR은 언제든 환영합니다!
| 정책 | 서비스 |
|---|---|
Basic | 애플리케이션 내부의 스크립트, 이미지 등에 대한 요청을 허용합니다 |
AdobeFonts | fonts.adobe.com (이전 typekit.com) |
Alchemer Survey | alchemer.com |
Algolia | algolia.com |
Bootstrap | getbootstrap.com |
Bunny Fonts | fonts.bunny.net |
Chargebee | chargebee.com |
Cloudflare Cdn | cloudflare.com |
Cloudflare Turnstile | cloudflare.com |
Cloudflare Web Analytics | cloudflare.com |
Cookiebot | cookiebot.com (동의 배너) |
Fathom | usefathom.com |
Featurebase | featurebase.app (피드백, 변경 이력, 메신저 위젯) |
Firebase | firebase.google.com |
Google TLD's | 'connect'와 'image'에 대해 모든 Google 최상위 도메인을 허용합니다 |
Google | Google Analytics 및 Tag Manager |
GoogleAds | ads.google.com |
GoogleFonts | fonts.google.com |
GoogleLookerStudio | lookerstudio.google.com |
GoogleMaps | maps.google.com |
GoogleRecaptcha | developers.google.com |
Hcaptcha | hcaptcha.com |
Heap Analytics | heap.io |
Hireroad | hireroad.com |
Hotjar | hotjar.com |
HubSpot | hubspot.com (전체 제품군) |
Intercom | intercom.com |
JsDelivr | jsdelivr.com |
JQuery | jquery.com |
Maze | maze.co |
Meta Pixel | facebook.com |
Microsoft Clarity | clarity.microsoft.com |
Plain | plain.com |
Plausible Analytics | plausible.io |
Posthog | posthog.com |
Rollbar | posthog.com |
Sentry | sentry.io |
Stripe | stripe.com |
SurveyMonkey | surveymonkey.com |
ThereThere | there-there.app (고객 지원 버블 위젯) |
TicketTailor | tickettailor.com |
Tolt | tolt.io |
TrackJS | trackjs.com |
Vimeo | vimeo.com |
Visual Website Optimizer | vwo.com |
Whereby | whereby.com |
애플리케이션에서 사용할 프리셋은 config/csp.php의 presets 또는 report_only_presets 키에 등록합니다.
앱에 특화된 요구 사항이 있거나 연동하려는 서비스가 이 패키지에 포함되어 있지 않다면, 아래에서 설명하는 방법으로 직접 프리셋을 만들 수 있습니다. 설정 파일에서 튜플 표기법으로 글로벌 디렉티브를 등록할 수도 있습니다.
'directives' => [
[Directive::SCRIPT, Keyword::UNSAFE_EVAL],
],
'report_only_directives' => [
[Directive::SCRIPT, Keyword::UNSAFE_INLINE],
],튜플에 여러 값을 넘기면 여러 디렉티브와 값의 조합을 한 번에 만들 수도 있습니다.
'directives' => [
[[Directive::SCRIPT, Directive::STYLE], [Keyword::UNSAFE_EVAL, Keyword::UNSAFE_INLINE]],
],프리셋 만들기
CSP 디렉티브의 예로 script-src가 있습니다. 이 값이 'self' www.google.com이면 사이트는 자기 도메인 또는 www.google.com에서만 스크립트를 불러올 수 있습니다. 모든 CSP 디렉티브 목록은 Mozilla 개발자 사이트의 디렉티브 목록에서 확인할 수 있습니다.
명세에 따르면 일부 디렉티브 값은 따옴표로 감싸야 합니다. 'self', 'none', 'unsafe-inline' 등이 여기에 해당합니다. add 함수를 사용할 때는 값을 직접 따옴표로 감쌀 필요가 없으며, 패키지가 자동으로 따옴표를 붙여 줍니다. 스크립트/스타일 해시도 자동으로 감지해서 따옴표로 감쌉니다.
public function configure(Policy $policy): void
{
$policy
// Will output `'self'` when outputting headers
->add(Directive::SCRIPT, Keyword::SELF)
// Will output `'sha256-hash'` when outputting headers
->add(Directive::STYLE, 'sha256-hash');
}디렉티브를 배열로 넘기면 같은 키워드를 여러 디렉티브에 한꺼번에 적용할 수 있습니다.
public function configure(Policy $policy): void
{
$policy->add([Directive::SCRIPT, DIRECTIVE::STYLE], 'www.google.com');
}하나 이상의 디렉티브에 여러 키워드를 한 번에 지정하는 것도 가능합니다.
public function configure(Policy $policy): void
{
$policy
->add(Directive::SCRIPT, [Keyword::UNSAFE_EVAL, Keyword::UNSAFE_INLINE])
->add([Directive::SCRIPT, DIRECTIVE::STYLE], ['www.google.com', 'analytics.google.com']);
}upgrade-insecure-requests처럼 값을 지정하지 않거나 지정할 필요가 없는 디렉티브도 있습니다. 이럴 때는 다음 값을 사용하세요.
public function configure(Policy $policy): void
{
$policy
->add(Directive::UPGRADE_INSECURE_REQUESTS, Value::NO_VALUE);
}이렇게 하면 다음과 같은 CSP 헤더가 출력됩니다.
Content-Security-Policy: upgrade-insecure-requests
csp 설정 파일의 presets 키는 기본값으로 [\Spatie\Csp\Presets\Basic::class]가 지정되어 있습니다. 이 클래스는 이미지, 스크립트, 폼 액션을 자기 사이트의 것으로만 제한합니다.
namespace Spatie\Csp\Presets;
use Spatie\Csp\Directive;
use Spatie\Csp\Keyword;
use Spatie\Csp\Policy;
use Spatie\Csp\Preset;
class Basic implements Preset
{
public function configure(Policy $policy): void
{
$policy
->add(Directive::BASE, Keyword::SELF)
->add(Directive::CONNECT, Keyword::SELF)
->add(Directive::DEFAULT, Keyword::SELF)
->add(Directive::FORM_ACTION, Keyword::SELF)
->add(Directive::IMG, Keyword::SELF)
->add(Directive::MEDIA, Keyword::SELF)
->add(Directive::OBJECT, Keyword::NONE)
->add(Directive::SCRIPT, Keyword::SELF)
->add(Directive::STYLE, Keyword::SELF)
->addNonce(Directive::SCRIPT)
->addNonce(Directive::STYLE);
}
}커스텀 프리셋을 작성하면 www.google.com에서 스크립트를 불러오도록 허용할 수 있습니다.
namespace App\Support;
use Spatie\Csp\Directive;
use Spatie\Csp\Keyword;
use Spatie\Csp\Policy;
use Spatie\Csp\Preset;
class MyCspPreset implements Preset
{
public function configure(Policy $policy): void
{
$policy->add(Directive::SCRIPT, 'www.google.com');
}
}csp 설정 파일의 presets 키에 직접 만든 프리셋의 클래스명을 추가하는 것을 잊지 마세요.
'presets' => [
Spatie\Csp\Presets\Basic::class,
App\Support\MyCspPreset::class,
],Trusted Types
특정 Trusted Types 정책 이름을 허용하려면 Directive::TRUSTED_TYPES를 사용하세요. 스크립트 주입 싱크(sink)에 Trusted Types를 필수로 요구하려면 Directive::REQUIRE_TRUSTED_TYPES_FOR와 함께 사용합니다.
public function configure(Policy $policy): void
{
$policy
->add(Directive::TRUSTED_TYPES, ['default', 'my-policy'])
->add(Directive::REQUIRE_TRUSTED_TYPES_FOR, Keyword::SCRIPT);
}정책 이름에는 따옴표를 붙이지 않습니다. 같은 이름의 정책을 둘 이상 만들 수 있게 하려면 정책 이름과 함께 Keyword::ALLOW_DUPLICATES를 사용하세요. 정책 생성을 아예 금지하려면 Keyword::NONE만 단독으로 사용하고, 어떤 정책 이름이든 허용하려면 '*'를 사용합니다.
인라인 스크립트와 스타일 사용하기
CSP를 사용할 때는 인라인 스크립트나 스타일의 사용을 명시적으로 허용해야 합니다. 이 패키지에서 권장하는 방법은 nonce를 사용하는 것입니다. nonce는 요청마다 고유한 값입니다. nonce는 CSP 헤더와 HTML 태그의 속성에 모두 지정해야 하며, 이렇게 하면 공격자가 악성 스크립트나 스타일을 주입할 방법이 없어집니다.
먼저 정책의 알맞은 디렉티브에 nonce를 추가합니다.
public function configure(Policy $policy): void
{
$policy
// alternatively use Keyword::STRICT_DYNAMIC on Livewire or Inertia.js
->add(Directive::SCRIPT, Keyword::SELF)
->add(Directive::STYLE, Keyword::SELF)
->addNonce(Directive::SCRIPT)
->addNonce(Directive::STYLE);
}그다음 style과 script 태그에 nonce를 추가합니다.
<style @cspNonce>
...
</style>
<script @cspNonce>
...
</script>스크립트를 동적으로 생성하는 디렉티브에 nonce를 전달하거나 가져와야 할 때는 app('csp-nonce')를 사용하세요.
@googlefonts(['nonce' => app('csp-nonce')])인라인 스타일과 스크립트를 사용하는 방법은 이 외에도 몇 가지 더 있습니다. 자세한 내용은 Mozilla 개발자 사이트의 CSP 문서를 참고하세요.
Vite와 함께 사용하기
에셋을 빌드할 때 Laravel Vite 플러그인이 nonce를 처리할 수 있습니다. nonce는 Vite::useCspNonce()로 생성하고 Vite::cspNonce()로 가져올 수 있습니다.
namespace App\Support;
use Illuminate\Support\Facades\Vite;
use Spatie\Csp\Nonce\NonceGenerator;
class LaravelViteNonceGenerator implements NonceGenerator
{
public function generate(): string
{
return Vite::useCspNonce();
}
}또는 Vite가 특정 nonce 값을 사용하도록 지정할 수도 있습니다.
namespace App\Support;
use Illuminate\Support\Str;
use Illuminate\Support\Facades\Vite;
use Spatie\Csp\Nonce\NonceGenerator;
class LaravelViteNonceGenerator implements NonceGenerator
{
public function generate(): string
{
// Determine the value for `$myNonce` however you want
$myNonce = '';
return Vite::useCspNonce($myNonce);
}
}생성하는 nonce는 최소 16바이트의 안전한 난수 데이터에서 만든 base64 값이어야 합니다. 이렇게 하면 HTML 속성과 HTTP 헤더에서 안전하게 쓸 수 있는 문자만 사용하게 됩니다. 자세한 내용은 W3C Content Security Policy Level 3 명세를 참고하세요.
config/csp.php 설정 파일의 기본 nonce_generator 키를 Vite nonce 생성기로 바꿉니다.
/*
* The class responsible for generating the nonces used in inline tags and headers.
*/
'nonce_generator' => App\Support\LaravelViteNonceGenerator::class,이제 app('csp-nonce') 또는 Vite::cspNonce()를 호출할 때 Vite의 nonce 값이 사용됩니다.
CSP 정책을 메타 태그로 출력하기
아주 드물게, 외부 연결이 많은 대규모 사이트에서는 CSP 헤더가 최대 헤더 크기를 넘길 수 있습니다. 또는 Laravel로 정적 페이지를 생성하고 있어서 응답을 보낼 때 헤더를 제어할 수 없는 경우도 있습니다. 다행히 CSP 명세는 웹 페이지의 head에 메타 태그로 정책을 출력하는 방법을 허용합니다.
이 패키지는 사이트의 <head>에 넣을 수 있는 @cspMetaTag Blade 디렉티브를 제공합니다. 이 디렉티브는 설정된 모든 프리셋(기본 프리셋과 report-only 프리셋 모두)에 대한 헤더를 렌더링합니다.
<head>
@cspMetaTag
</head>특정 프리셋만 렌더링하는 데도 이 태그를 사용할 수 있습니다.
<head>
@cspMetaTag(App\Support\MyCustomPreset::class)
</head>특정 프리셋을 report-only 모드로 렌더링하려면 @cspMetaTagReportOnly 태그를 사용하세요.
<head>
@cspMetaTagReportOnly(App\Support\MyCustomPreset::class)
</head>CSP 오류 보고하기
브라우저에서
모든 위반을 그대로 차단하는 대신, report_only_presets 설정 옵션에 프리셋을 등록해 CSP 정책을 report-only 모드로 구성할 수 있습니다. 이 경우 모든 요청은 정상적으로 처리되며, 위반 사항은 사용 중인 브라우저의 콘솔에 표시됩니다.
외부 URL로
정책 위반 사항을 지정한 URL로 보고하도록 할 수 있습니다. 이를 위한 CSP 디렉티브는 두 가지입니다.
report-uri: 원래부터 있던 디렉티브입니다. 사용이 권장되지 않지만(deprecated) 대부분의 브라우저에서 여전히 지원됩니다.csp설정 파일의report_uri키에 URL을 지정합니다.report-to: 최신 대체 디렉티브입니다.Reporting-EndpointsHTTP 헤더에 정의된 이름 있는 엔드포인트를 가리킵니다.report_to키에 엔드포인트 이름을 지정하고, 엔드포인트 URL은reporting_endpoints배열에 정의합니다.
새 디렉티브가 브라우저 전반에 확산되는 중이므로 두 가지를 동시에 설정할 수 있습니다. 오래된 브라우저는 report-uri를, 최신 브라우저는 report-to를 사용합니다.
// config/csp.php
'report_uri' => env('CSP_REPORT_URI', 'https://example.com/csp-reports'),
'report_to' => env('CSP_REPORT_TO', 'default'),
'reporting_endpoints' => [
'default' => 'https://example.com/csp-reports',
],이런 위반 보고서를 처리하기 위해 특별히 만들어진 훌륭한 서비스로 http://report-uri.io/가 있습니다.
enforce 정책과 report-only 정책을 나란히 운영하면서 각각 다른 엔드포인트로 보고해야 한다면(예: report-uri.com은 Content-Security-Policy에 /enforce, Content-Security-Policy-Report-Only에 /reportOnly를 요구합니다) report_only_uri 및/또는 report_only_to를 설정하세요.
// config/csp.php
'report_uri' => env('CSP_REPORT_URI', 'https://example.report-uri.com/r/d/csp/enforce'),
'report_only_uri' => env('CSP_REPORT_ONLY_URI', 'https://example.report-uri.com/r/d/csp/reportOnly'),report_only_uri(또는 report_only_to)가 비어 있으면 report-only 정책은 report_uri(또는 report_to)를 그대로 사용합니다.
테스트
다음 명령으로 모든 테스트를 실행할 수 있습니다.
composer test변경 내역
최근 변경 사항은 CHANGELOG를 참고하세요.
기여하기
자세한 내용은 CONTRIBUTING을 참고하세요.
보안
보안과 관련된 버그를 발견했다면 이슈 트래커 대신 security@spatie.be로 메일을 보내 주세요.
크레딧
라이선스
MIT 라이선스(MIT)를 따릅니다. 자세한 내용은 라이선스 파일을 참고하세요.
