DOMPurify v3.4.13

보안

### 축소되고 테스트된 프로덕션 버전 사용하기 (source-map 제공)```html
<script type="text/javascript" src="dist/purify.min.js"></script>

아니면 Angular이나 비슷한 프레임워크를 좋아한다면 이렇게 해도 됩니다:```js
import DOMPurify from 'dompurify';

const clean = DOMPurify.sanitize('<b>hello there</b>');

### 함정이 될 만한 요소가 있나요?

주의하세요. HTML을 _먼저_ 살균한 뒤 _이후에_ 수정하면 살균 효과를 쉽게 **무효화**할 수 있습니다. 살균된 마크업을 다른 라이브러리에 전달할 때는, 그 라이브러리가 HTML을 자체적으로 건드리지 않는지 반드시 확인하세요. 안전한 사용법과 신중히 검토해야 할 태그·속성 목록은 [보안 목표 및 위협 모델](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model)을, 후처리와 마크업 컨텍스트 변경이 살균을 무력화하는 이유는 [공격 클래스 및 우회 기록](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History)을 참고하세요.

### 알겠습니다. 이해했으니 넘어가죠

마크업을 살균한 뒤에는 `DOMPurify.removed` 속성을 살펴보고 어떤 요소와 속성이 제거되었는지 확인할 수도 있습니다. 다만 이 속성을 보안상 중요한 결정을 내리는 데 **사용하지 마세요**. 이는 단지 궁금한 사람들을 위한 작은 도우미일 뿐입니다.

### 서버에서 DOMPurify 실행하기

DOMPurify는 기술적으로 Node.js 서버 측에서도 작동합니다. 저희의 지원은 [Node.js 릴리스 주기](https://nodejs.org/en/about/previous-releases)를 따르려고 합니다.

서버에서 DOMPurify를 실행하려면 DOM이 필요하다는 점은 놀랍지 않을 것입니다. 일반적으로 [jsdom](https://github.com/jsdom/jsdom)이 선택 도구이며, 저희는 최신 버전의 _jsdom_ 사용을 **강력히 권장**합니다.

왜일까요? 이전 버전의 _jsdom_은 DOMPurify가 100% 올바르게 작동하더라도 XSS로 이어지는 방식의 버그가 있는 것으로 알려져 있기 때문입니다. 예를 들어 _jsdom v19.0.0_에는 _jsdom v20.0.0_에서 수정된 **알려진 공격 벡터**가 있으며, 그 때문에 _jsdom_을 최신 상태로 유지하는 것을 정말 권장합니다.

또한 [happy-dom](https://github.com/capricorn86/happy-dom) 같은 도구도 존재하지만 현재로서는 **안전한 것으로 간주되지 않는다**는 점도 알아두세요. DOMPurify를 _happy-dom_과 결합하는 것은 현재 권장되지 않으며 XSS로 이어질 가능성이 높습니다. 선택한 서버 측 DOM이 신뢰 컴퓨팅 기반의 일부인 이유에 대한 배경은 [공격 클래스 및 우회 기록](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History)을 참고하세요.

그 외에는 서버에서 DOMPurify를 사용해도 괜찮습니다. 아마도요. 이는 실제로 _jsdom_ 또는 서버 측에서 사용하는 DOM에 달려 있습니다. 그 점을 감수할 수 있다면, 다음과 같이 작동시킬 수 있습니다:```bash
npm install dompurify
npm install jsdom

또는 import를 사용하여 작업하는 것을 선호한다면 이렇게 할 수도 있습니다:```js
import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const window = new JSDOM('').window;
const purify = DOMPurify(window);
const clean = purify.sanitize('<b>hello there</b>');

I need the input content to translate. Please provide the chunk of Markdown content you'd like me to translate from English to Korean.```js
import DOMPurify from 'isomorphic-dompurify';

const clean = DOMPurify.sanitize('<s>hello</s>');

이것들은 그저 맛보기에 불과합니다. 이러한 샘플이 비롯된 공격 클래스의 전체 분류(변이 XSS, 네임스페이스 혼동, DOM 클로버링, rawtext 탈출 등)에 대해서는 [Attack Classes & Bypass History](https://github.com/cure53/DOMPurify/wiki/Attack-Classes-&-Bypass-History)를 참조하세요.

## 무엇이 지원되나요?

DOMPurify는 현재 HTML5, SVG 및 MathML을 지원합니다. DOMPurify는 기본적으로 CSS와 HTML 사용자 정의 데이터 속성을 허용합니다. DOMPurify는 또한 Shadow DOM을 지원하며 DOM 템플릿을 재귀적으로 살균합니다. DOMPurify를 사용하면 jQuery `$()` 및 `elm.html()` API와 함께 사용하기 위한 HTML을 알려진 문제 없이 살균할 수도 있습니다. 기본적으로 허용되는 정확한 요소 및 속성 집합은 [Default TAGs & ATTRIBUTEs allow-list & blocklist](https://github.com/cure53/DOMPurify/wiki/Default-TAGs-ATTRIBUTEs-allow-list-&-blocklist) 위키 페이지를 참조하세요.

## Internet Explorer 같은 레거시 브라우저는 어떨까요?

DOMPurify는 아무것도 하지 않습니다. 단순히 입력한 문자열을 그대로 반환할 뿐입니다. DOMPurify는 `isSupported`라는 속성을 노출하는데, 이 속성은 DOMPurify가 제 역할을 수행할 수 있는지 여부를 알려주므로 자체 백업 계획을 세울 수 있습니다.

## DOMPurify와 Trusted Types는 어떨까요?

버전 1.0.9에서 [Trusted Types API](https://github.com/w3c/webappsec-trusted-types)([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API))에 대한 지원이 DOMPurify에 추가되었습니다.
버전 2.0.0에서는 이와 관련된 DOMPurify의 동작을 제어하는 구성 플래그가 추가되었습니다.

`DOMPurify.sanitize`가 Trusted Types API를 사용할 수 있는 환경에서 사용되고 `RETURN_TRUSTED_TYPE`이 `true`로 설정된 경우, 문자열 대신 `TrustedHTML` 값을 반환하려고 시도합니다(`RETURN_DOM` 및 `RETURN_DOM_FRAGMENT` 구성 옵션의 동작은 변경되지 않습니다).

DOMPurify를 사용하여 `trustedTypes`에서 정책을 생성하려면 `RETURN_TRUSTED_TYPE: false`가 필요합니다. `createHTML`은 `TrustedHTML`이 아닌 일반 문자열을 기대하기 때문입니다. 아래 예시에서 이를 확인할 수 있습니다.```js
window.trustedTypes.createPolicy('default', {
  createHTML: (to_escape) =>
    DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});

자체 래핑 정책을 DOMPurify의 `TRUSTED_TYPES_POLICY`로 다시 전달하지 마십시오(예: `DOMPurify.setConfig({ TRUSTED_TYPES_POLICY: myPolicy })`를 통해). 해당 정책의 `createHTML`이 이미 `DOMPurify.sanitize`를 호출하는 경우입니다. 이는 정의상 순환적입니다. 정화(sanitize)가 정책을 호출하고, 정책은 다시 DOMPurify를 호출하여 정화하므로, DOMPurify는 무한 재귀를 방지하기 위해 설명적인 `TypeError`를 발생시킵니다. 자체 정책은 DOMPurify를 호출해야 하며, DOMPurify가 정책을 호출하도록 구성해서는 안 됩니다.

이 `default` 정책 패턴을 전체 페이지에 자동으로 적용하려면 - 레거시 코드, 타사 위젯, 그리고 쉽게 찾거나 다시 작성할 수 없는 수천 개의 `innerHTML` 할당을 포함한 모든 HTML 싱크가 정화되도록 - [DOMFortify](https://github.com/cure53/DOMFortify)를 살펴보십시오. 이 프로젝트는 DOMPurify를 기반으로 하는 정확히 그러한 Trusted Types `default` 정책을 설치하고, 스크립트 싱크(`eval`, `script.src`, ...)를 완전히 거부합니다. 이는 의도적으로 분리된 프로젝트입니다. DOMPurify는 집중된 정화기로 유지되고, DOMFortify는 의도적으로 DOMPurify의 범위를 벗어난 문서 전체 적용 계층을 처리합니다.

## DOMPurify를 구성할 수 있나요?

네. 포함된 기본 구성 값은 이미 꽤 좋습니다. 물론 이를 재정의할 수도 있습니다. [`/demos`](https://github.com/cure53/DOMPurify/tree/main/demos) 폴더에서 [DOMPurify를 사용자 정의](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this)하는 방법에 대한 다양한 예제를 확인하십시오.

허용 목록(`ADD_TAGS`, `ADD_ATTR`, `CUSTOM_ELEMENT_HANDLING`, ...)을 넓히거나 기본값을 완화하기 전에 [다시 생각해 볼 태그와 속성](https://github.com/cure53/DOMPurify/wiki/Security-Goals-&-Threat-Model#dangerous-tags-and-attributes-think-twice-before-allow-listing)을 훑어보는 것이 좋습니다. 일부는 명확하지 않은 방식으로 위험합니다.

### 일반 설정```js
// strip {{ ... }}, ${ ... } and <% ... %> to make output safe for template systems
// be careful please, this mode is not recommended for production usage.
// allowing template parsing in user-controlled HTML is not advised at all.
// only use this mode if there is really no alternative.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_TEMPLATES: true });

// change how e.g. comments containing risky HTML characters are treated.
// be very careful, this setting should only be set to `false` if you really only handle
// HTML and nothing else, no SVG, MathML or the like.
// Otherwise, changing from `true` to `false` will lead to XSS in this or some other way.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_XML: false });

### 커스텀 엘리먼트와 관련된 제어 동작```js
// DOMPurify allows to define rules for Custom Elements. When using the CUSTOM_ELEMENT_HANDLING
// literal, it is possible to define exactly what elements you wish to allow (by default, none are allowed).
//
// The same goes for their attributes. By default, the built-in or configured allow.list is used.
//
// You can use a RegExp literal to specify what is allowed or a predicate, examples for both can be seen below.
// When using a predicate function for attributeNameCheck, it can optionally receive the tagName as a second parameter
// for more granular control over which attributes are allowed for specific elements.
// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: null, // no custom elements are allowed
      attributeNameCheck: null, // default / standard attribute allow-list is used
      allowCustomizedBuiltInElements: false, // no customized built-ins allowed
    },
  }
); // <div is=""></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: /^foo-/, // allow all tags starting with "foo-"
      attributeNameCheck: /baz/, // allow all attributes containing "baz"
      allowCustomizedBuiltInElements: true, // customized built-ins are allowed
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

const clean = DOMPurify.sanitize(
  '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^foo-/), // allow all tags starting with "foo-"
      attributeNameCheck: (attr) => attr.match(/baz/), // allow all containing "baz"
      allowCustomizedBuiltInElements: true, // allow customized built-ins
    },
  }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

// Example with attributeNameCheck receiving tagName as a second parameter
const clean = DOMPurify.sanitize(
  '<element-one attribute-one="1" attribute-two="2"></element-one><element-two attribute-one="1" attribute-two="2"></element-two>',
  {
    CUSTOM_ELEMENT_HANDLING: {
      tagNameCheck: (tagName) => tagName.match(/^element-(one|two)$/),
      attributeNameCheck: (attr, tagName) => {
        if (tagName === 'element-one') {
          return ['attribute-one'].includes(attr);
        } else if (tagName === 'element-two') {
          return ['attribute-two'].includes(attr);
        } else {
          return false;
        }
      },
      allowCustomizedBuiltInElements: false,
    },
  }
); // <element-one attribute-one="1"></element-one><element-two attribute-two="2"></element-two>

### 허용된 속성 값 제어```js
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
const clean = DOMPurify.sanitize(dirty, { ALLOW_UNKNOWN_PROTOCOLS: true });

// allow specific protocol handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only (protocol-)relative URLs, http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
const clean = DOMPurify.sanitize(dirty, {
  ALLOWED_URI_REGEXP:
    /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i,
});

### 영향력 있는 방식으로 살균 처리 방법을 조정하세요```js
// return entire document including <html> tags (default is false)
const clean = DOMPurify.sanitize(dirty, { WHOLE_DOCUMENT: true });

// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)
const clean = DOMPurify.sanitize(dirty, { SANITIZE_DOM: false });

// enforce strict DOM Clobbering protection via namespace isolation (default is false)
// when enabled, isolates the namespace of named properties (i.e., `id` and `name` attributes)
// from JS variables by prefixing them with the string `user-content-`
const clean = DOMPurify.sanitize(dirty, { SANITIZE_NAMED_PROPS: true });

// keep an element's content when the element is removed (default is true)
const clean = DOMPurify.sanitize(dirty, { KEEP_CONTENT: false });

// glue elements like style, script or others to document.body and prevent unintuitive browser behavior in several edge-cases (default is false)
const clean = DOMPurify.sanitize(dirty, { FORCE_BODY: true });

// remove all <a> elements under <p> elements that are removed
const clean = DOMPurify.sanitize(dirty, {
  FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// extend the default FORBID_CONTENTS list to also remove <a> elements under <p> elements
const clean = DOMPurify.sanitize(dirty, {
  ADD_FORBID_CONTENTS: ['a'],
  FORBID_TAGS: ['p'],
});

// change the parser type so sanitized data is treated as XML and not as HTML, which is the default
const clean = DOMPurify.sanitize(dirty, {
  PARSER_MEDIA_TYPE: 'application/xhtml+xml',
});

[더 많은 예시는 여기](https://github.com/cure53/DOMPurify/tree/main/demos#what-is-this)에서 확인할 수 있으며, DOMPurify를 실행하고 사용자 정의하고 구성하는 방법을 보여줍니다.

## 영구 구성

`DOMPurify.sanitize`에 동일한 구성을 반복해서 전달하는 대신 `DOMPurify.setConfig` 메서드를 사용할 수 있습니다. 구성은 다음 `DOMPurify.setConfig` 호출까지, 또는 `DOMPurify.clearConfig`를 호출하여 재설정할 때까지 유지됩니다. 활성 구성은 하나만 있다는 점을 기억하세요. 즉, 설정된 후에는 `DOMPurify.sanitize`에 전달되는 추가 구성 매개변수는 모두 무시됩니다.

## 훅

DOMPurify를 사용하면 `DOMPurify.addHook` 메서드를 사용하여 다음 훅 중 하나에 하나 이상의 함수를 연결하여 기능을 확장할 수 있습니다:

- `beforeSanitizeElements`
- `uponSanitizeElement` ('s' 없음 - 모든 요소에 대해 호출됨)
- `afterSanitizeElements`
- `beforeSanitizeAttributes`
- `uponSanitizeAttribute`
- `afterSanitizeAttributes`
- `beforeSanitizeShadowDOM`
- `uponSanitizeShadowNode`
- `afterSanitizeShadowDOM`

현재 처리 중인 DOM 노드, 필요한 경우 검증된 노드 및 속성 데이터가 포함된 리터럴, 그리고 DOMPurify 구성을 콜백에 전달합니다. API가 어떻게 유용하게 사용될 수 있는지 확인하려면 [MentalJS 훅 데모](https://github.com/cure53/DOMPurify/blob/main/demos/hooks-mentaljs-demo.html)를 확인하세요.

_예시_:```js
DOMPurify.addHook(
  'uponSanitizeAttribute',
  function (currentNode, hookEvent, config) {
    // Do something with the current node
    // You can also mutate hookEvent for current node (i.e. set hookEvent.forceKeepAttr = true)
    // For other than 'uponSanitizeAttribute' hook types hookEvent equals to null
  }
);

DOMPurify v3.4.13

DOMPurify

목차

무엇을 하나요?

어떻게 사용하나요?

축소되지 않은 버전 사용 (소스 맵 제공)```html

데모가 있나요?

보안 버그를 발견하면 어떻게 하나요?

정화 샘플 몇 가지를 보여주실 수 있나요?

허용 목록 및 차단 목록 제어```js

URI 값과 관련된 제어 동작```js

반환 유형에 영향 주기```js

영향력을 행사하는 곳에서 삭제 처리```js

훅에서 sanitize() 호출에 관한 참고 사항

제거된 구성

지속적 통합

개발 및 기여

설치 (npm i)

스크립트

보안 메일링 리스트

누가 기여했나요?

카테고리

훅에서 `sanitize()` 호출에 관한 참고 사항

설치 (`npm i`)