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

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

Maud Nalpas

일부 오류는 프로덕션에서만 발생합니다. 실제 사용자, 실제 네트워크, 실제 기기는 게임을 변경하기 때문에 로컬 또는 개발 중에는 표시되지 않습니다. Reporting API를 사용하면 사이트 전체에서 보안 위반이나 지원 중단되어 곧 지원 중단될 API 호출과 같은 오류를 포착하고 지정된 엔드포인트로 전송할 수 있습니다.

HTTP 헤더를 통해 모니터링하려는 항목을 선언할 수 있으며, 브라우저에 의해 작동합니다.

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

이 게시물에서는 이 API의 기능과 사용 방법을 다룹니다. 시작해 볼까요?

데모 및 코드

Chrome 96 이상 (2021년 10월 기준 Chrome 베타 또는 Canary) 이상의 Reporting 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를 구성하여 사이트 전체에서 발생하는 여러 유형의 흥미로운 경고 또는 문제를 모니터링할 수 있습니다.

보고서

보고서는 어떻게 표시되나요?

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

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"
  }
]

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

사용자 인증 정보 보고서

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

사용자 인증 정보는 특정 사용자 계정에서 지속적으로 오류를 트리거하거나 다른 페이지에서 실행한 작업의 특정 순서로 이 페이지에서 보고서가 트리거되는지 등 보고서에 관한 유용한 추가 컨텍스트를 제공할 수 있습니다.

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

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

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

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

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

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

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

지원 중단 예시

브라우저 지원

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

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

Reporting API 사용

보고서를 전송할 위치 결정

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

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

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

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

• report-uri
• 리포트

다른 해결 방법을 알고 계시다면 문제를 열어 알려 주시면 이 게시물을 업데이트하도록 하겠습니다.

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

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

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

보고서를 수신하는 자체 서버를 구축하는 것은 간단한 작업이 아닙니다. 시작하려면 경량의 상용구를 포크하면 됩니다. 익스프레스로 구축되며 보고서를 수신하고 표시할 수 있습니다.

1. 표준 보고서 수집기로 이동합니다.

2. 리믹스하여 수정을 클릭하여 프로젝트를 수정할 수 있도록 합니다.

3. 이제 클론이 만들어졌습니다. 자신의 목적에 맞게 맞춤설정할 수 있습니다.

상용구를 사용하지 않고 처음부터 자체 서버를 빌드하는 경우:

• Content-Type가 application/reports+json인 POST 요청을 확인하여 브라우저에서 엔드포인트로 보낸 보고서 요청을 인식합니다.
• 엔드포인트가 사이트와 다른 출처에 있는 경우 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 엔드포인트를 정의하지 않는 경우 이 유형의 보고서는 생성되지 않습니다.

값 (URL)

각 값은 선택한 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-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

예시 코드

이 모든 것을 컨텍스트에서 살펴보기 위해 아래는 Express를 사용하고 이 문서에서 설명하는 모든 요소를 종합한 노드 서버의 예시입니다. 여러 보고서 유형에 관한 보고를 구성하는 방법을 보여주고 그 결과를 표시합니다.

보고서 설정 디버깅

의도적으로 보고서 생성

Reporting API를 설정할 때 보고서가 예상대로 생성되고 전송되는지 확인하려면 정책을 의도적으로 위반해야 할 수 있습니다. 정책을 위반하고 모든 유형의 보고서를 생성하는 기타 잘못된 작업을 실행하는 코드의 예를 보려면 데모를 확인하세요.

시간을 절약하세요

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

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

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

DevTools 사용

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

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

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

보고서 상태

상태 열에 보고서가 전송되었는지 여부가 표시됩니다.

보고서는 전송 성공 여부와 관계없이 잠시 후 삭제됩니다.

문제 해결

보고서가 생성되지 않았거나, 예상대로 엔드포인트로 전송되지 않습니까? 다음은 이 문제를 해결하기 위한 몇 가지 도움말입니다.

보고서가 생성되지 않음

DevTools에 표시되는 보고서는 올바르게 생성된 것입니다. 예상한 보고서가 이 목록에 표시되지 않는 경우:

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

보고서가 생성되지만 전송 또는 수신되지 않음

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

• 짧은 지연을 이용하세요. 보고서가 표시되지 않는 이유는 아직 전송되지 않은 경우일 수 있습니다.

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

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

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

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

• 정책 헤더 구문에서 따옴표 누락과 같은 문제가 있는지 확인합니다. 세부정보 보기

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

  • 엔드포인트가 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 헤더는 정책을 시행하지 않습니다. 즉, 오류가 발생하거나 실제로 차단되지는 않지만 오류 또는 차단된 항목에 관한 보고서를 받게 됩니다.

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)

Unsplash에 있는 Nine Koepfer / @enka80의 히어로 이미지 수정됨. 이 기사에 대한 리뷰와 제안을 제공해 주신 이안 클레랜드, 에이지 키타무라, 밀리카 미하즐리자님께 감사드립니다.