실험적 콘텐츠 보안 정책 (CSP)

타입: boolean | object
기본값: false

추가된 버전: astro@5.9.0

콘텐츠 보안 정책 (CSP) 지원을 활성화하여 문서가 로드할 수 있는 리소스를 제어함으로써 특정 유형의 보안 위협을 최소화합니다. 이는 교차 사이트 스크립팅 (XSS) 공격에 대한 추가적인 보호를 제공합니다.

이 기능을 활성화하면 기본적으로 Astro에 의해 처리되고 번들링된 스크립트 및 스타일에 추가 보안이 적용되며, 이러한 콘텐츠 유형과 추가적인 콘텐츠 유형을 더욱 세밀하게 구성할 수 있습니다.

이 실험적인 CSP 기능에는 몇 가지 제한 사항이 있습니다. 인라인 스크립트는 기본적으로 지원되지 않지만, 외부 및 인라인 스크립트에 자체 해시를 제공할 수 있습니다. <ClientRouter />를 사용하는 Astro의 뷰 전환은 지원되지 않습니다. 하지만 Astro를 사용하여 네이티브 뷰 전환 및 탐색 API를 향상시키지 않는 경우, 브라우저의 네이티브 뷰 전환 API로 마이그레이션하는 것을 고려할 수 있습니다.

이 기능을 사용하려면 Astro 구성에서 실험적 플래그를 추가하세요.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: true
  }
});

이 기능을 활성화하면 Astro는 각 페이지의 <head> 요소에 <meta> 요소를 추가합니다.

이 요소에는 http-equiv="content-security-policy" 속성이 있으며, content 속성은 페이지에 사용된 스크립트 및 스타일을 기반으로 script-src 및 style-src 지시어에 대한 값을 제공합니다.

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src 'self' 'sha256-somehash';
      style-src 'self' 'sha256-somehash';
    "
  >
</head>

구성

추가 옵션이 포함된 구성 객체로 이 기능을 활성화하여 <meta> 요소를 추가로 사용자 정의할 수 있습니다.

`algorithm`

타입: 'SHA-256' | 'SHA-512' | 'SHA-384'
기본값: 'SHA-256'

추가된 버전: astro@5.9.0

Astro에서 내보낸 스타일 및 스크립트의 해시를 생성할 때 사용할 해시 함수입니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      algorithm: 'SHA-512'
    }
  }
});

`directives`

타입: CspDirective[]
기본값: []

추가된 버전: astro@5.9.0

특정 콘텐츠 유형에 대해 유효한 소스를 정의하는 CSP 지시어 목록입니다.

Astro는 script-src 및 style-src 지시어를 제어해야 하지만, csp.directives 필드를 사용하면 다른 CSP 지시어를 제어할 수도 있습니다. 이 지시어들은 모든 페이지에 추가됩니다. 타입 안전 지시어 목록을 전달받습니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      directives: [
        "default-src 'self'",
        "img-src 'self' https://images.cdn.example.com"
      ]
    }
  }
});

빌드 후, <meta> 요소는 content 값에 Astro의 기본 지시어와 새로운 지시어를 추가합니다.

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' 'https://images.cdn.example.com';
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`styleDirective` 및 `scriptDirective`

타입: object
기본값: {}

추가된 버전: astro@5.9.0

style-src 및 script-src 지시어의 기본 소스를 resources 속성으로 재정의하거나 렌더링할 추가 해시를 제공하는 구성 객체입니다.

이러한 속성은 모든 페이지에 추가되는 것이 아니라 Astro의 기본 리소스를 완전히 재정의합니다. 따라서 포함할 기본값을 명시적으로 지정해야 합니다.

`resources`

타입: string[]
기본값: []

추가된 버전: astro@5.9.0

script-src 및 style-src 지시어에 유효한 소스 목록입니다.

기본적으로 script-src 및 style-src 지시어는 Astro에서 처리하며 'self' 리소스를 사용합니다. 즉, 스크립트와 스타일은 현재 호스트 (일반적으로 현재 웹사이트)에서만 다운로드할 수 있습니다.

기본 소스를 재정의하기 위해 리소스 목록을 제공할 수 있습니다. 이 목록에는 기본적으로 'self'가 포함되지 않으므로, 이를 유지하려면 이 목록에 포함시켜야 합니다. 이 리소스들은 모든 페이지에 추가됩니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        resources: [
          "'self'",
          "https://styles.cdn.example.com"
        ]
      },
      scriptDirective: {
        resources: [
          "https://cdn.example.com"
        ]
      }
    }
  }
});

빌드 후, <meta> 요소는 style-src 및 script-src 지시어에 소스를 적용합니다.

<head>
  <meta
    http-equiv="content-security-policy"
    content="
      script-src https://cdn.example.com 'sha256-somehash';
      style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
    "
  >
</head>

`hashes`

타입: CspHash[]
기본값: []

추가된 버전: astro@5.9.0

렌더링할 추가 해시 목록입니다.

Astro에서 생성되지 않은 외부 스크립트, 스타일, 인라인 스크립트를 사용하는 경우, 이 구성 옵션을 사용하여 렌더링할 추가 해시를 제공할 수 있습니다.

sha384-, sha512-, sha256-로 시작하는 해시를 제공해야 합니다. 다른 값을 제공하면 유효성 검사 오류가 발생합니다. 이 해시들은 모든 페이지에 추가됩니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      styleDirective: {
        hashes: [
          "sha384-styleHash",
          "sha512-styleHash",
          "sha256-styleHash"
        ]
      },
      scriptDirective: {
        hashes: [
          "sha384-scriptHash",
          "sha512-scriptHash",
          "sha256-scriptHash"
        ]
      }
    }
  }
});

빌드 후, <meta> 요소는 script-src 및 style-src 지시어에 추가 해시를 포함시킵니다.

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
    style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
  "
>

`strictDynamic`

타입: boolean
기본값: false

추가된 버전: astro@5.9.0

스크립트의 동적 삽입을 지원하기 위해 strict-dynamic 키워드를 활성화합니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: {
      scriptDirective: {
        strictDynamic: true
      }
    }
  }
});

런타임 API

.astro 컴포넌트의 런타임 API (Astro global을 통해 사용 가능) 또는 엔드포인트 및 미들웨어의 APIContext 타입을 통해 페이지별 <meta> 요소를 사용자 정의할 수 있습니다.

`insertDirective`

타입: (directive: CspDirective) => void

추가된 버전: astro@5.9.0

현재 페이지에 하나의 지시어를 추가합니다. 이 메서드를 여러 번 호출하여 여러 지시어를 추가할 수도 있습니다.

---
Astro.insertDirective("default-src 'self'");
Astro.insertDirective("img-src 'self' https://images.cdn.example.com");
---

빌드 후, 이 페이지의 <meta> 요소는 기존 script-src 및 style-src 지시어와 추가 지시어를 함께 배치합니다.

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' https://images.cdn.example.com;
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`insertStyleResource`

타입: (resource: string) => void

추가된 버전: astro@5.9.0

style-src 지시어에 사용할 새 리소스를 삽입합니다.

---
Astro.insertStyleResource("https://styles.cdn.example.com");
---

빌드 후, 이 페이지의 <meta> 요소는 기본 style-src 지시어에 소스를 추가합니다.

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src https://styles.cdn.example.com 'sha256-somehash';
  "
>

`insertStyleHash`

타입: (hash: CspHash) => void

추가된 버전: astro@5.9.0

style-src 지시어에 새 해시를 추가합니다.

---
Astro.insertStyleHash("sha512-styleHash");
---

빌드 후, 이 페이지의 <meta> 요소는 기본 style-src 지시어에 해시를 추가합니다.

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash' 'sha512-styleHash';
  "
>

`insertScriptResource`

타입: (resource: string) => void

추가된 버전: astro@5.9.0

script-src 지시어에 사용할 새 유효한 소스를 삽입합니다.

---
Astro.insertScriptResource("https://scripts.cdn.example.com");
---

빌드 후, 이 페이지의 <meta> 요소는 기본 script-src 지시어에 소스를 추가합니다.

<meta
  http-equiv="content-security-policy"
  content="
    script-src https://scripts.cdn.example.com 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

`insertScriptHash`

타입: (hash: CspHash) => void

추가된 버전: astro@5.9.0

script-src 지시어에 새 해시를 추가합니다.

---
Astro.insertScriptHash("sha512-scriptHash");
---

빌드 후, 이 페이지의 <meta> 요소는 기본 script-src 지시어에 해시를 추가합니다.

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha256-somehash' 'sha512-styleHash';
    style-src 'self' 'sha256-somehash';
  "
>

기여하기 커뮤니티 후원하기

실험적 콘텐츠 보안 정책 (CSP)

구성

algorithm

directives

styleDirective 및 scriptDirective

resources

hashes

strictDynamic

런타임 API

insertDirective

insertStyleResource

insertStyleHash

insertScriptResource

insertScriptHash

`algorithm`

`directives`

`styleDirective` 및 `scriptDirective`

`resources`

`hashes`

`strictDynamic`

`insertDirective`

`insertStyleResource`

`insertStyleHash`

`insertScriptResource`

`insertScriptHash`