Update API 사용

개요

Update API를 사용하면 클라이언트 애플리케이션에서 로컬 또는 인메모리 데이터베이스에 저장할 Web Risk 목록의 해싱된 버전을 다운로드할 수 있습니다. 그런 다음 로컬에서 URL을 확인할 수 있습니다. 로컬 데이터베이스에 일치하는 항목이 있으면 클라이언트는 Web Risk 서버에 요청을 보내 Web Risk 관리 목록에 URL이 포함되어 있는지 확인합니다.

로컬 데이터베이스 업데이트

최신 상태를 유지하려면 클라이언트가 로컬 데이터베이스의 Web Risk 목록을 주기적으로 업데이트해야 합니다. 대역폭을 절약하기 위해 클라이언트는 원시 URL이 아닌 URL의 해시 프리픽스를 다운로드합니다. 예를 들어 'www.badurl.com/'이 Web Risk 목록에 있는 경우 클라이언트는 URL 자체가 아닌 해당 URL의 SHA256 해시 프리픽스를 다운로드합니다. 대부분의 경우 해시 프리픽스는 4바이트입니다. 즉, 단일 목록 항목을 다운로드하는데 필요한 평균 대역폭 비용은 압축 전 4바이트입니다.

로컬 데이터베이스의 Web Risk 목록을 업데이트하려면 threatLists.computeDiff 메서드에 HTTP GET 요청을 보냅니다.

  • HTTP GET 요청에는 메모리 및 대역폭 제한을 고려하여 클라이언트 제약조건과 함께 업데이트할 목록의 이름이 포함됩니다.
  • HTTP GET 응답은 전체 업데이트 또는 부분 업데이트를 반환합니다. 또한 응답은 다음 컴퓨팅 비교 작업까지의 권장 대기 시간을 반환할 수 있습니다.

예: threatLists.computeDiff

HTTP GET 요청

다음 예시에서는 멀웨어 Web Risk 목록의 비교를 요청합니다. 자세한 내용은 threatLists.computeDiff 쿼리 매개변수 및 코드 예시 뒤에 나오는 설명을 참조하세요.

HTTP 메서드 및 URL:

GET "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

다음 명령어를 실행합니다.

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

PowerShell

다음 명령어를 실행합니다.

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri ""https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z",
  "responseType": "RESET",
  "additions": {
    "rawHashes": [
      {
        "prefixSize": 4,
        "rawHashes": "AArQMQAMoUgAPn8lAE..."
      }
    ]
  },
  "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL",
  "checksum": {
    "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI="
  }
}

Web Risk 목록

threatType 필드는 Web Risk 목록을 식별합니다. 이 예시에서는 멀웨어 Web Risk 목록의 비교를 요청합니다.

버전 토큰

versionToken 필드에는 Web Risk 목록의 현재 클라이언트 상태가 포함됩니다. 버전 토큰은 threatLists.computeDiff 응답newVersionToken 필드에 반환됩니다. 초기 업데이트의 경우 versionToken 필드를 비워둡니다.

크기 제한

maxDiffEntries 필드는 클라이언트가 관리할 수 있는 총 업데이트 수를 지정합니다(예: 2048). maxDatabaseEntries 필드는 로컬 데이터베이스가 관리할 수 있는 총 항목 수를 지정합니다(예: 4096). 클라이언트는 메모리 또는 대역폭 제한이 있는 경우에만 크기 제한을 설정해야 합니다. 자세한 내용은 업데이트 제약조건을 참조하세요.

지원되는 압축

supportedCompressions 필드에는 클라이언트가 지원하는 압축 유형이 나열됩니다. 이 예시에서 클라이언트는 압축되지 않은 원시 데이터만 지원합니다. 하지만 Web Risk 관리는 추가 압축 유형을 지원합니다. 자세한 내용은 압축을 참조하세요.

HTTP GET 응답

이 예시에서 응답은 요청된 압축 유형을 사용하여 Web Risk 목록의 부분 업데이트를 반환합니다.

응답 본문

응답 본문에는 차이점 정보(응답 유형, 로컬 데이터베이스에 적용할 추가 및 제거, 새 버전 토큰, 체크섬)가 포함됩니다. 이 예시에서는 권장되는 다음 차이 시간도 응답에 포함됩니다. 자세한 내용은 threatLists.computeDiff 응답 본문 및 코드 예시를 따르는 설명을 참조하세요.

{
  "responseType" :   "DIFF",
  "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z",
  "additions": {
    "compressionType": "RAW",
    "rawHashes": [{
      "prefixSize": 4,
      "rawHashes":  "rnGLoQ=="
    }]
  },
  "removals": {
    "rawIndices": {
      "indices": [0, 2, 4]
    }
  },
  "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
  "checksum": {
    "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
  },
  "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z"
}

데이터베이스 비교

responseType 필드는 부분(DIFF) 또는 전체 업데이트(RESET)를 나타냅니다. 이 예시에서는 부분 비교가 반환되므로 응답에 추가와 삭제가 모두 포함됩니다. 여러 개의 추가 항목이 있을 수 있지만 하나의 삭제 모음만 있을 수 있습니다. 자세한 내용은 데이터베이스 비교를 참조하세요.

새 버전 토큰

newVersionToken 필드에는 새로 업데이트된 Web Risk 목록의 새 버전 토큰이 포함되어 있습니다. 클라이언트는 후속 업데이트 요청을 위해 새 클라이언트 상태를 저장해야 합니다(threatLists.computeDiff 요청versionToken 필드).

검사합

체크섬을 사용하면 클라이언트가 로컬 데이터베이스가 손상되지 않았는지 확인할 수 있습니다. 체크섬이 일치하지 않으면 클라이언트는 데이터베이스를 지우고 빈 versionToken 필드로 업데이트를 다시 실행해야 합니다. 하지만 이 상황에서 클라이언트는 업데이트를 위한 시간 간격을 계속 준수해야 합니다. 자세한 내용은 요청 빈도를 참조하세요.

recommendedNextDiff 필드는 클라이언트가 또 다른 업데이트 요청을 보내기 전에 대기해야 하는 타임스탬프를 나타냅니다. 권장 대기 시간은 응답에 포함될 수도 포함되지 않을 수도 있습니다. 자세한 내용은 요청 빈도를 참조하세요.

URL 확인

URL이 Web Risk 목록에 있는지 확인하려면 먼저 클라이언트가 URL의 해시 및 해시 프리픽스를 계산해야 합니다. 자세한 내용은 URL 및 해싱을 참조하세요. 그런 다음 클라이언트는 로컬 데이터베이스에 쿼리하여 일치하는 항목이 있는지 확인합니다. 해시 프리픽스가 로컬 데이터베이스에 없는 경우 URL은 안전하다고 간주됩니다(즉, Web Risk 목록에 없음).

해시 프리픽스가 로컬 데이터베이스에 있는 경우(해시 프리픽스 충돌) 클라이언트는 확인을 위해 해시 프리픽스를 Web Risk 서버로 전송해야 합니다. 서버는 지정된 해시 프리픽스가 포함된 모든 전체 길이 SHA 256 해시를 반환합니다. 이러한 전체 길이 해시 중 하나가 문제의 URL의 전체 길이 해시와 일치하면 URL이 안전하지 않은 것으로 간주합니다. 문제가 되는 URL의 전체 길이 해시와 일치하는 전체 길이 해시가 없는 경우 해당 URL이 안전하다고 간주합니다.

Google에서는 어느 URL을 검사하는지 알지 못합니다. Google은 URL의 해시 프리픽스를 학습하지만 해시 프리픽스는 실제 URL에 대한 많은 정보를 제공하지 않습니다.

URL이 Web Risk 목록에 있는지 확인하려면 hashes.search 메서드에 HTTP GET 요청을 보냅니다.

  • HTTP GET 요청에는 확인할 URL의 해시 프리픽스가 포함됩니다.
  • HTTP GET 응답은 일치하는 전체 길이 해시를 양성 및 음성 만료 시간과 함께 반환합니다.

예: hashes.search

HTTP GET 요청

다음 예시에서는 비교 및 확인을 위해 두 개의 Web Risk 목록 이름과 해시 프리픽스가 전송됩니다. 자세한 내용은 hashes.search 쿼리 매개변수 및 코드 예시 뒤에 나오는 설명을 참조하세요.

curl \
  -H "Content-Type: application/json" \
  "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"

Web Risk 목록

threatTypes 필드는 Web Risk 목록을 식별합니다. 이 예시에서는 MALWARESOCIAL_ENGINEERING의 두 목록이 식별됩니다.

위협 해시 프리픽스

hashPrefix 필드에는 확인하려는 URL의 해시 프리픽스가 포함됩니다. 이 필드에는 로컬 데이터베이스에 있는 정확한 해시 프리픽스가 포함되어야 합니다. 예를 들어 로컬 해시 프리픽스가 4바이트인 경우 hashPrefix 필드는 4바이트여야 합니다. 로컬 해시 프리픽스가 7바이트로 늘어난 경우 hashPrefix 필드는 7바이트여야 합니다.

HTTP GET 응답

다음 예시에서는 응답에서 일치하는 Web Risk 목록과 만료 시간을 포함하는 일치 위협을 반환합니다.

응답 본문

응답 본문에는 일치 정보(목록 이름, 전체 길이 해시, 캐시 기간)가 포함됩니다. 자세한 내용은 hashes.search 응답 본문 및 코드 예시를 따르는 설명을 참조하세요.

{
  "threats": [{
      "threatTypes": ["MALWARE"],
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    }, {
      "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
      "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    },
  }],
  "negativeExpireTime": "2019-07-17T15:01:23.045123456Z"
}

일치

threats 필드는 해시 프리픽스와 일치하는 전체 길이 해시를 반환합니다. 해시에 해당하는 URL은 안전하지 않은 것으로 간주됩니다. 해시 프리픽스와 일치하는 항목이 없는 경우 아무것도 반환되지 않습니다. 해당 해시 프리픽스에 해당하는 URL이 안전한 것으로 간주됩니다.

만료 시간

expireTimenegativeExpireTime 필드는 해시가 각각 안전하지 않거나 안전한 것으로 간주되어야 하는 시점을 나타냅니다. 자세한 내용은 캐싱을 참조하세요.