Reporting API를 사용하여 웹 애플리케이션 모니터링

Reporting API를 사용하여 보안 위반, 지원 중단된 API 호출 등을 모니터링합니다.

Maud Nalpas

주의사항:

Reporting-Endpoints 헤더를 사용하는 Reporting API (v1)의 자세한 사용 예가 포함된 API 가이드입니다.

기존 Reporting API (Report-To 헤더)를 사용하는 경우 API 이전에 대해 알아보세요.

네트워크 오류 로깅 문서를 찾고 계신가요? 대신 네트워크 오류 로깅으로 이동하세요.

일부 오류는 프로덕션에서만 발생합니다. 실제 사용자, 실제 네트워크, 실제 기기가 게임을 변경하므로 로컬이나 개발 중에는 표시되지 않습니다. Reporting API는 보안 위반이나 지원 중단되었으며 곧 지원이 중단될 API 호출과 같은 이러한 오류를 포착하고 지정한 엔드포인트로 전송하는 데 도움이 됩니다.

HTTP 헤더를 사용하여 모니터링할 항목을 선언할 수 있으며 브라우저에서 작동합니다.

Reporting API를 설정하면 사용자가 이러한 유형의 오류를 경험할 때 이를 알 수 있으므로 문제를 해결할 수 있습니다.

이 게시물에서는 이 API의 기능과 사용 방법을 설명합니다. 그럼 시작하겠습니다.

개요

보고서가 생성되고 전송되는 방식

사이트(site.example)에 콘텐츠 보안 정책과 문서 정책이 있다고 가정해 보겠습니다. 이러한 기능이 무엇인지 잘 모르시겠다고요? 이 예시를 이해하는 데는 문제가 없습니다.

이러한 정책이 위반되는 시점을 파악하기 위해 사이트를 모니터링할 뿐만 아니라 코드베이스에서 사용 중일 수 있는 지원 중단되었거나 곧 지원 중단될 API를 주시하기 위해 사이트를 모니터링합니다.

이렇게 하려면 Reporting-Endpoints 헤더를 구성하고 필요한 경우 정책에서 report-to 지시문을 사용하여 이러한 엔드포인트 이름을 매핑합니다.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

예상치 못한 일이 발생하여 일부 사용자가 이러한 정책을 위반하게 됩니다.

위반 사례

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, index.html에 의해 로드됨

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

브라우저는 이러한 문제를 포착하는 CSP 위반 보고서, 문서 정책 위반 보고서, 지원 중단 보고서를 생성합니다.

최대 1분 정도의 짧은 지연 후 브라우저는 이 위반 유형에 대해 구성된 엔드포인트로 보고서를 전송합니다. 보고서는 브라우저 자체에서 대역 외로 전송됩니다 (서버나 사이트에서 전송하는 것이 아님).

엔드포인트가 이러한 보고서를 수신합니다.

이제 이러한 엔드포인트의 보고서에 액세스하여 문제가 발생한 부분을 모니터링할 수 있습니다. 이제 사용자에게 영향을 미치는 문제 해결을 시작할 수 있습니다.

예시 보고서

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

사용 사례 및 보고서 유형

Reporting API는 사이트 전체에서 발생하는 다양한 유형의 흥미로운 경고나 문제를 모니터링할 수 있도록 구성할 수 있습니다.

주의: 네트워크 오류 로깅은 새 버전의 API에서 지원되지 않으므로 목록에 표시되지 않습니다. 자세한 내용은 이전 가이드를 참고하세요.

보고서 유형	보고서가 생성되는 상황의 예
CSP 위반 (수준 3만 해당)	페이지 중 하나에 Content-Security-Policy (CSP)를 설정했지만 페이지에서 CSP에서 허용하지 않는 스크립트를 로드하려고 합니다.
COOP 위반	페이지에 Cross-Origin-Opener-Policy를 설정했지만 교차 출처 창에서 문서와 직접 상호작용하려고 합니다.
COEP 위반	페이지에 Cross-Origin-Embedder-Policy를 설정했지만 문서에 교차 출처 문서에 의해 로드되도록 선택하지 않은 교차 출처 iframe이 포함되어 있습니다.
문서 정책 위반	페이지에 document.write 사용을 방지하는 문서 정책이 있지만 스크립트가 document.write를 호출하려고 합니다.
권한 정책 위반	이 페이지에는 마이크 사용을 방지하는 권한 정책과 오디오 입력을 요청하는 스크립트가 있습니다.
지원 중단 경고	페이지에서 지원 중단되었거나 지원 중단될 API를 사용하고 있습니다. API를 직접 호출하거나 최상위 서드 파티 스크립트를 사용하여 호출합니다.
개입	페이지에서 보안, 성능 또는 사용자 경험상의 이유로 브라우저가 따르지 않기로 결정한 작업을 시도하고 있습니다. Chrome의 예: 페이지에서 느린 네트워크에서 document.write를 사용하거나 사용자가 아직 상호작용하지 않은 교차 출처 프레임에서 navigator.vibrate를 호출합니다.
교통사고	사이트가 열려 있는 동안 브라우저가 비정상 종료됩니다.

보고서

보고서는 어떤 형태로 제공되나요?

브라우저가 구성된 엔드포인트로 보고서를 전송합니다. 다음과 같은 요청을 전송합니다.

POST
Content-Type: application/reports+json

이러한 요청의 페이로드는 보고서 목록입니다.

보고서 목록 예

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

각 보고서에서 확인할 수 있는 데이터는 다음과 같습니다.

필드	설명
age	보고서의 타임스탬프와 현재 시간 사이의 시간(밀리초)입니다.
body	실제 보고서 데이터로, JSON 문자열로 직렬화됩니다. 보고서의 body에 포함된 필드는 보고서의 type에 따라 결정됩니다. ⚠️ 유형이 다른 신고에는 본문이 다릅니다.
type	보고서 유형입니다(예: csp-violation 또는 coep).
url	보고서가 생성된 문서 또는 작업자의 주소입니다. 사용자 이름, 비밀번호, 프래그먼트와 같은 민감한 데이터는 이 URL에서 삭제됩니다.
user_agent	보고서가 생성된 요청의 User-Agent 헤더입니다.

사용자 인증 정보가 있는 보고서

보고서를 생성하는 페이지와 출처가 동일한 보고 엔드포인트는 보고서가 포함된 요청에서 사용자 인증 정보 (쿠키)를 수신합니다.

사용자 인증 정보는 신고에 관한 유용한 추가 컨텍스트를 제공할 수 있습니다. 예를 들어 특정 사용자의 계정에서 지속적으로 오류가 트리거되는지 또는 다른 페이지에서 취한 특정 작업 시퀀스가 이 페이지에서 신고를 트리거하는지 등을 알 수 있습니다.

참고: 크로스 오리진 엔드포인트는 사용자 인증 정보를 수신하지 않습니다. 이는 보안 조치이며 변경할 수 없습니다.

브라우저는 언제 어떻게 보고서를 전송하나요?

보고서는 사이트에서 대역 외로 전송됩니다. 브라우저가 구성된 엔드포인트로 전송되는 시점을 제어합니다. 브라우저가 보고서를 전송하는 시점을 제어할 방법도 없습니다. 브라우저는 적절한 시간에 보고서를 자동으로 캡처하고 대기열에 추가하고 전송합니다.

즉, Reporting API를 사용할 때는 성능 문제가 거의 없습니다.

보고서는 최대 1분까지 지연되어 전송되므로 보고서를 일괄적으로 전송할 가능성이 높아집니다. 이렇게 하면 사용자의 네트워크 연결을 고려하여 대역폭이 절약됩니다. 이는 특히 모바일에서 중요합니다. 브라우저가 우선순위가 높은 작업을 처리하느라 바쁘거나 사용자가 당시 느리거나 혼잡한 네트워크에 있는 경우에도 전송이 지연될 수 있습니다.

참고: 로컬에서 디버깅할 때는 편의를 위해 이 지연을 사용 중지할 수 있습니다. 방법 보기

서드 파티 및 퍼스트 파티 문제

페이지에서 발생하는 위반 또는 지원 중단으로 인해 생성된 보고서는 구성된 엔드포인트로 전송됩니다. 여기에는 페이지에서 실행되는 서드 파티 스크립트로 인해 발생하는 위반이 포함됩니다.

페이지에 삽입된 교차 출처 iframe에서 발생한 위반 또는 지원 중단은 엔드포인트에 보고되지 않습니다(기본적으로는). iframe은 자체 보고를 설정하고 사이트(즉, 퍼스트 파티)의 보고 서비스에 보고할 수도 있지만 이는 프레임된 사이트에 달려 있습니다. 또한 대부분의 보고서는 페이지의 정책이 위반된 경우에만 생성되며 페이지의 정책과 iframe의 정책은 다릅니다.

핵심 사항: Chrome DevTools에서 서드 파티 스크립트 및 교차 출처 iframe에 의해 발생한 위반에 대한 콘솔 오류 또는 경고가 표시됩니다. 이러한 이벤트가 모두 엔드포인트로 전송되는 보고서로 변환되는 것은 아닙니다. 전자는 변환되지만 후자는 변환되지 않습니다.

지원 중단이 포함된 예

페이지에 Reporting-Endpoints 헤더가 설정된 경우 페이지에서 실행되는 서드 파티 스크립트에 의해 호출되는 지원 중단된 API가 엔드포인트에 보고됩니다. 페이지에 삽입된 iframe에서 호출된 지원 중단된 API는 엔드포인트에 보고되지 않습니다. 지원 중단 보고서는 iframe 서버에서 Reporting-Endpoints를 설정한 경우에만 생성되며, 이 보고서는 iframe의 서버에서 설정한 엔드포인트로 전송됩니다.

브라우저 지원

다음 표에는 Reporting API v1(Reporting-Endpoints 헤더 사용)에 대한 브라우저 지원이 요약되어 있습니다. 보고 API v0 (Report-To 헤더)의 브라우저 지원은 한 가지 보고 유형을 제외하고 동일합니다. 네트워크 오류 로깅은 새로운 보고 API에서 지원되지 않습니다. 자세한 내용은 이전 가이드를 참고하세요.

보고서 유형	Chrome	Chrome iOS	Safari	Firefox	에지
CSP 위반 (레벨 3만 해당)*	✔ 예	✔ 예	✔ 예	✘ 아니요	✔ 예
네트워크 오류 로깅	✘ 아니요	✘ 아니요	✘ 아니요	✘ 아니요	✘ 아니요
COOP/COEP 위반	✔ 예	✘ 아니요	✔ 예	✘ 아니요	✔ 예
기타 유형: 문서 정책 위반, 지원 중단, 개입, 비정상 종료	✔ 예	✘ 아니요	✘ 아니요	✘ 아니요	✔ 예

주의사항:

CSP는 출시된 지 꽤 되었기 때문에 CSP 보고에 대한 브라우저 지원은 다른 보고 유형과 다릅니다. CSP 보고서는 다음을 사용하여 생성할 수 있습니다.

• Reporting API를 사용하지 않는 기존 report-uri 지시어
• Reporting API (및 Reporting-To 또는 최신 Reporting-Endpoints 헤더)를 사용하는 최신 report-to 지시문

이 표에는 새 Reporting-Endpoints 헤더를 사용하는 report-to 지원만 요약되어 있습니다. Reporting-Endpoints로 이전하려는 경우 CSP 보고 마이그레이션 도움말을 참고하세요.

Reporting API 사용

보고서를 보낼 위치 결정

다음과 같은 두 가지 옵션이 있습니다.

• 기존 보고서 수집기 서비스에 보고서를 전송합니다.
• 직접 빌드하고 운영하는 보고 수집기로 보고서를 전송합니다.

옵션 1: 기존 보고서 수집기 서비스 사용

보고서 수집기 서비스의 예는 다음과 같습니다.

• report-uri
• uriports

다른 해결 방법을 알고 있다면 문제를 신고하여 알려주세요. 이 게시물을 업데이트하겠습니다.

보고서 수집기를 선택할 때 가격 외에도 다음 사항을 고려하세요. 🧐

• 이 수집기는 모든 보고서 유형을 지원하나요? 예를 들어 일부 보고 엔드포인트 솔루션은 COOP/COEP 보고서를 지원하지 않습니다.
• 애플리케이션의 URL을 서드 파티 보고서 수집기와 공유해도 되나요? 브라우저가 이러한 URL에서 민감한 정보를 삭제하더라도 이러한 방식으로 민감한 정보가 유출될 수 있습니다. 애플리케이션에 너무 위험하다고 생각되면 자체 보고 엔드포인트를 운영하세요.

옵션 2: 자체 보고서 수집기 빌드 및 운영

보고서를 수신하는 자체 서버를 구축하는 것은 간단하지 않습니다. 시작하려면 경량 보일러플레이트를 포크하면 됩니다. Express로 빌드되며 보고서를 수신하고 표시할 수 있습니다.

자체 보고서 수집기를 빌드하는 경우 다음 사항을 고려하세요.

• 브라우저에서 엔드포인트로 전송된 보고서 요청을 인식하려면 application/reports+json의 Content-Type이 있는 POST 요청을 확인하세요.
• 엔드포인트가 사이트와 다른 출처에 있는 경우 CORS 실행 전 요청을 지원하는지 확인하세요.

핵심사항: 엔드포인트가 CORS 실행 전 요청을 지원하는지 확인하세요.

옵션 3: 옵션 1과 2 결합

특정 제공업체에서 일부 유형의 보고서를 처리하도록 하고 다른 유형의 보고서는 자체 솔루션을 사용하고 싶을 수 있습니다.

이 경우 다음과 같이 여러 엔드포인트를 설정합니다.

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

Reporting-Endpoints 헤더 구성

Reporting-Endpoints 응답 헤더를 설정합니다. 값은 쉼표로 구분된 키-값 쌍 하나 또는 여러 개여야 합니다.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

기존 Reporting API에서 새 Reporting API로 이전하는 경우 Reporting-Endpoints와 Report-To를 모두 설정하는 것이 좋습니다. 자세한 내용은 이전 가이드를 참고하세요. 특히 report-uri 지시어만 사용하여 Content-Security-Policy 위반에 대한 보고를 사용하는 경우 CSP 보고를 위한 이전 단계를 확인하세요.

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...

키 (엔드포인트 이름)

각 키는 main-endpoint 또는 endpoint-1과 같이 원하는 이름일 수 있습니다. my-coop-endpoint, my-csp-endpoint과 같이 보고서 유형별로 다른 이름의 엔드포인트를 설정할 수 있습니다. 이를 통해 유형에 따라 보고서를 다른 엔드포인트로 라우팅할 수 있습니다.

개입, 지원 중단, 비정상 종료 보고서 또는 이들의 조합을 수신하려면 default라는 엔드포인트를 설정하세요.

Reporting-Endpoints 헤더에 default 엔드포인트가 정의되어 있지 않으면 이 유형의 보고서는 생성되지만 전송되지는 않습니다.

핵심 사항: 이름과 달리 default은 대체 엔드포인트가 아닙니다. 예를 들어 Document-Policy에 대해 report-to my-endpoint를 설정하고 Reporting-Endpoints에서 my-endpoint를 정의하지 않으면 Document-Policy 위반 보고서가 생성되지만 브라우저에서 보고서를 전송할 위치를 알지 못하므로 전송되지 않습니다.

값 (URL)

각 값은 보고서가 전송될 URL입니다. 여기에서 설정할 URL은 1단계에서 결정한 내용에 따라 달라집니다.

엔드포인트 URL:

• 슬래시 (/)로 시작해야 합니다. 상대 경로는 지원되지 않습니다.
• 크로스 오리진일 수 있지만 이 경우 사용자 인증 정보는 보고서와 함께 전송되지 않습니다.

예

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

그런 다음 적절한 정책에서 각 명명된 엔드포인트를 사용하거나 모든 정책에서 하나의 단일 엔드포인트를 사용할 수 있습니다.

헤더를 설정할 위치

이 게시물에서 다루는 새로운 Reporting API에서 보고서는 문서로 범위가 지정됩니다. 즉, 하나의 출처에 대해 site.example/page1, site.example/page2과 같은 서로 다른 문서가 서로 다른 엔드포인트로 보고서를 전송할 수 있습니다.

사이트의 모든 페이지에서 발생하는 위반 또는 지원 중단에 관한 보고서를 받으려면 모든 응답에서 헤더를 미들웨어로 설정하세요.

다음은 Express의 예입니다.

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

참고: 이는 한 페이지의 '앰비언트' 엔드포인트를 설정하고 동일한 출처의 모든 페이지에 대한 보고서를 자동으로 가져올 수 있는 기존 Reporting API (Report-To 헤더)와 다릅니다. 기존 Reporting API에서 새 Reporting API로 이전하는 경우 이전 가이드를 확인하세요.

정책 수정

이제 Reporting-Endpoints 헤더가 구성되었으므로 위반 보고서를 수신하려는 각 정책 헤더에 report-to 지시어를 추가합니다. report-to 값은 구성한 명명된 엔드포인트 중 하나여야 합니다.

여러 정책에 여러 엔드포인트를 사용하거나 정책 간에 서로 다른 엔드포인트를 사용할 수 있습니다.

report-to는 지원 중단, 개입, 비정상 종료 보고서에는 필요하지 않습니다. 이러한 보고서는 어떤 정책에도 바인딩되지 않습니다. default 엔드포인트가 설정되어 있는 한 생성되며 이 default 엔드포인트로 전송됩니다.

예

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

경고: 모든 정책이 동일한 헤더 구조를 사용하는 것은 아니므로 report-to 문법을 올바르게 사용하는 것이 어려울 수 있습니다. 정책에 따라 올바른 문법은 report-to=main-endpoint 또는 report-to main-endpoint일 수 있습니다.

보고 설정 디버그

의도적으로 보고서 생성

Reporting API를 설정할 때 보고서가 예상대로 생성되고 전송되는지 확인하기 위해 의도적으로 정책을 위반해야 할 수 있습니다.

시간 절약

보고서가 약 1분 정도 지연되어 전송될 수 있습니다. 디버깅 시에는 긴 시간입니다. 😴 다행히 Chrome에서 디버깅할 때 --short-reporting-delay 플래그를 사용하여 보고서가 생성되는 즉시 보고서를 받을 수 있습니다.

터미널에서 다음 명령어를 실행하여 이 플래그를 사용 설정합니다.

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

핵심사항: 이 플래그는 Chrome UI를 사용하여 사용할 수 없으며 명령줄 플래그로만 사용할 수 있습니다. 플래그를 사용하여 Chromium을 실행하는 방법을 알아보세요.

DevTools 사용

Chrome에서 DevTools를 사용하여 전송되었거나 전송될 보고서를 확인합니다.

2021년 10월 현재 이 기능은 실험적 기능입니다. 이 기능을 사용하려면 다음 단계를 따르세요.

1. Chrome 버전 96 이상 사용 (브라우저에 chrome://version를 입력하여 확인)
2. Chrome의 주소 표시줄에 chrome://flags/#enable-experimental-web-platform-features을 입력하거나 붙여넣습니다.
3. 사용 설정됨을 클릭합니다.
4. 브라우저를 다시 시작합니다.
5. Chrome DevTools를 엽니다.
6. Chrome DevTools에서 설정을 엽니다. 실험에서 애플리케이션 패널에 Reporting API 패널 사용 설정을 클릭합니다.
7. DevTools를 새로고침합니다.
8. 페이지를 새로고침합니다. 페이지 DevTools가 열려 있는 페이지에서 생성된 보고서는 Chrome DevTools의 Application 패널의 Reporting API 아래에 나열됩니다.

Chrome DevTools는 페이지에서 생성된 보고서와 상태를 표시합니다.

보고서 상태

상태 열은 신고가 전송되었는지 여부를 알려줍니다.

상태	설명
Success	브라우저가 보고서를 전송했고 엔드포인트가 성공 코드 (200 또는 다른 성공 응답 코드 2xx)로 응답했습니다.
Pending	브라우저에서 보고서를 전송하려고 시도하고 있습니다.
Queued	보고서가 생성되었으며 브라우저에서 보고서를 전송하려고 하지 않습니다. 다음 두 가지 경우 중 하나에서 보고서가 Queued로 표시됩니다. 보고서가 새로 생성되었으며 브라우저가 보고서를 전송하기 전에 추가 보고서가 도착하는지 기다리고 있습니다. 보고서가 새 보고서가 아닙니다. 브라우저에서 이미 이 보고서를 전송하려고 시도했지만 실패했으며 다시 시도하기 전에 기다리고 있습니다.
MarkedForRemoval	한동안 (Queued) 다시 시도한 후 브라우저가 보고서 전송 시도를 중단했으며 곧 전송할 보고서 목록에서 삭제할 예정입니다.

보고서는 전송 성공 여부와 관계없이 일정 시간이 지나면 삭제됩니다.

핵심 사항: Queued 상태는 전송이 실패했는지 아직 시도하지 않았는지 정확하게 나타내지 않으므로 항상 유용한 것은 아닙니다. 짧은 보고 지연을 사용하면 다음과 같은 이점이 있습니다. 이 경우 Queued로 유지되는 보고서는 전송이 실패했음을 나타낼 수 있습니다.

문제 해결

보고서가 생성되지 않거나 엔드포인트로 전송되지 않나요? 이 문제를 해결하기 위한 몇 가지 팁을 소개합니다.

보고서가 생성되지 않음

DevTools에 표시되는 보고서가 올바르게 생성되었습니다. 예상한 보고서가 이 목록에 표시되지 않는 경우 다음 단계를 따르세요.

• 정책에서 report-to를 확인하세요. 이 값이 잘못 구성되면 보고서가 생성되지 않습니다. 정책 수정으로 이동하여 이 문제를 해결하세요. 이 문제를 해결하는 또 다른 방법은 Chrome에서 DevTools 콘솔을 확인하는 것입니다. 예상한 위반에 대한 오류가 콘솔에 표시되면 정책이 올바르게 구성된 것일 수 있습니다.
• DevTools가 열려 있는 문서에 대해 생성된 보고서만 이 목록에 표시됩니다. 한 가지 예로, 사이트 site1.example에 정책을 위반하는 iframe site2.example이 삽입되어 보고서가 생성되는 경우 이 보고서는 iframe을 자체 창에서 열고 해당 창의 DevTools를 열어야만 DevTools에 표시됩니다.

보고서가 생성되었지만 전송되지 않거나 수신되지 않음

DevTools에서 보고서를 볼 수 있지만 엔드포인트에서 보고서를 수신하지 못하는 경우 어떻게 해야 하나요?

핵심사항: 보고서는 특정 사이트가 아닌 브라우저 자체에서 대역 외로 전송되므로 보고서가 포함된 POST 요청은 개발자 도구의 네트워크 패널에 표시되지 않습니다.

• 짧은 지연 시간을 사용해야 합니다. 아직 보고서가 전송되지 않아 표시되지 않을 수도 있습니다.

• Reporting-Endpoints 헤더 구성을 확인합니다. 문제가 있으면 올바르게 생성된 보고서가 전송되지 않습니다. 이 경우 DevTools에서 보고서의 상태는 Queued로 유지됩니다 (전송 시도가 이루어지면 Pending로 전환되었다가 다시 Queued로 빠르게 돌아갈 수 있음). 이 문제가 발생할 수 있는 일반적인 실수는 다음과 같습니다.

• 엔드포인트가 사용되었지만 구성되지 않았습니다. 예:

실수가 있는 코드

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

Document-Policy 위반 보고서는 endpoint-1로 전송해야 하지만 이 엔드포인트 이름은 Reporting-Endpoints에 구성되어 있지 않습니다.

• default 엔드포인트가 누락되었습니다. 지원 중단 및 개입 보고서와 같은 일부 보고서 유형은 default라는 엔드포인트로만 전송됩니다. Reporting-Endpoints 헤더 구성에서 자세히 알아보세요.

• 따옴표 누락과 같은 정책 헤더 문법의 문제를 찾습니다. 자세히 보기

• 엔드포인트가 수신 요청을 처리할 수 있는지 확인합니다.

  • 엔드포인트가 CORS 프리플라이트 요청을 지원하는지 확인합니다. 그렇지 않으면 보고서를 수신할 수 없습니다.

  • 엔드포인트의 동작을 테스트합니다. 이렇게 하려면 보고서를 수동으로 생성하는 대신 브라우저가 전송하는 것과 유사한 요청을 엔드포인트에 전송하여 브라우저를 에뮬레이션하면 됩니다. 다음을 실행합니다.

  curl --header "Content-Type: application/reports+json" \
    --request POST \
    --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
    YOUR_ENDPOINT
  

  엔드포인트는 성공 코드 (200 또는 다른 성공 응답 코드 2xx)로 응답해야 합니다. 그렇지 않으면 구성에 문제가 있는 것입니다.

관련 신고 메커니즘

보고서 전용

-Report-Only 정책 헤더와 Reporting-Endpoints가 함께 작동합니다.

Reporting-Endpoints에 구성되고 Content-Security-Policy, Cross-Origin-Embedder-Policy, Cross-Origin-Opener-Policy의 report-to 필드에 지정된 엔드포인트는 이러한 정책이 위반될 때 보고서를 수신합니다.

Reporting-Endpoints에 구성된 엔드포인트는 Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only, Cross-Origin-Opener-Policy-Report-Only의 report-to 필드에도 지정할 수 있습니다. 또한 이러한 정책이 위반되면 보고서도 받게 됩니다.

두 경우 모두 보고서가 전송되지만 -Report-Only 헤더는 정책을 적용하지 않습니다. 중단되거나 실제로 차단되는 것은 없지만 중단되거나 차단되었을 수 있는 항목에 관한 보고서를 받게 됩니다.

참고: -Report-Only 헤더를 사용하고 기존 헤더 Report-To를 사용하여 보고 엔드포인트를 구성한 경우 가능하다면 Reporting-Endpoints로 이전하세요. 자세한 내용은 이전 가이드를 참고하세요.

ReportingObserver

ReportingObserver JavaScript API를 사용하면 클라이언트 측 경고를 관찰할 수 있습니다.

ReportingObserver 및 Reporting-Endpoints 헤더는 동일한 보고서를 생성하지만 약간 다른 사용 사례를 지원합니다.

다음과 같은 경우 ReportingObserver를 사용하세요.

• 지원 중단 또는 브라우저 개입만 모니터링하려는 경우 ReportingObserver는 지원 중단 및 브라우저 개입과 같은 클라이언트 측 경고를 표시하지만 Reporting-Endpoints와 달리 CSP 또는 COOP/COEP 위반과 같은 다른 유형의 보고서는 캡처하지 않습니다.
• 이러한 위반에 실시간으로 대응해야 합니다. ReportingObserver를 사용하면 위반 이벤트에 콜백을 연결할 수 있습니다.
• 맞춤 콜백을 사용하여 디버깅에 도움이 되는 추가 정보를 보고서에 첨부하려고 합니다.

또 다른 차이점은 ReportingObserver는 클라이언트 측에서만 구성된다는 것입니다. 서버 측 헤더를 제어할 수 없고 Reporting-Endpoints을 설정할 수 없는 경우에도 사용할 수 있습니다.

추가 자료

• Reporting API v0에서 v1로의 이전 가이드
• ReportingObserver
• 사양: 기존 Reporting API (v0)
• 사양: 새로운 Reporting API (v1)

나인 코에프퍼 / @enka80(Unsplash 제공)의 히어로 이미지를 수정했습니다. 이 문서에 대한 검토와 제안을 제공해 주신 이언 클랜드, 에이지 기타무라, 밀리카 미하일리아에게 감사드립니다.