개요
Update API를 사용하면 클라이언트 애플리케이션에서 세이프 브라우징 목록의 해시 버전을 다운로드하여 로컬 데이터베이스에 저장할 수 있습니다. 그런 다음 로컬에서 URL을 확인할 수 있습니다. 로컬 데이터베이스에서 일치하는 항목이 발견된 경우에만 클라이언트는 세이프 브라우징 서버에 요청을 전송하여 URL이 세이프 브라우징 목록에 포함되어 있는지 확인해야 합니다.
Update API를 사용하기 전에 로컬 데이터베이스를 설정해야 합니다. 세이프 브라우징은 시작하는 데 사용할 수 있는 Go 패키지를 제공합니다. 자세한 내용은 로컬 데이터베이스의 데이터베이스 설정 섹션을 참조하세요.
로컬 데이터베이스 업데이트
최신 상태를 유지하기 위해 클라이언트는 로컬 데이터베이스의 세이프 브라우징 목록을 주기적으로 업데이트해야 합니다. 대역폭을 절약하기 위해 클라이언트는 원시 URL 대신 URL의 해시 접두사를 다운로드합니다. 예를 들어 'www.badurl.com/'이 세이프 브라우징 목록에 있는 경우 클라이언트는 URL 자체가 아닌 해당 URL의 SHA256 해시 접두사를 다운로드합니다. 대부분의 경우 해시 프리픽스는 4바이트 길이입니다. 즉, 단일 목록 항목을 다운로드하는 데 드는 평균 대역폭 비용은 압축 전 4바이트입니다.
로컬 데이터베이스의 세이프 브라우징 목록을 업데이트하려면 다음과 같이 HTTP POST 요청을 threatListUpdates.fetch 메서드에 보냅니다.
- HTTP
POST요청에는 메모리 및 대역폭 제한을 고려하여 다양한 클라이언트 제약조건과 함께 업데이트할 목록 이름이 포함됩니다. - HTTP
POST응답은 전체 업데이트 또는 부분 업데이트를 반환합니다. 응답은 최소 대기 시간을 반환할 수도 있습니다.
예: threatListUpdates.fetch
HTTP POST 요청
다음 예에서는 단일 세이프 브라우징 목록의 업데이트가 요청됩니다.
요청 헤더
요청 헤더에는 요청 URL과 콘텐츠 유형이 포함됩니다. URL의 API_KEY를 API 키로 대체해야 합니다.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
요청 본문
요청 본문에는 클라이언트 정보 (ID 및 버전)와 업데이트 정보 (목록 이름, 목록 상태, 클라이언트 제약조건)가 포함됩니다. 자세한 내용은 threatListUpdates.fetch 요청 본문과 코드 예시 뒤에 나오는 설명을 참조하세요.
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"listUpdateRequests": [{
"threatType": "MALWARE",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"state": "Gg4IBBADIgYQgBAiAQEoAQ==",
"constraints": {
"maxUpdateEntries": 2048,
"maxDatabaseEntries": 4096,
"region": "US",
"supportedCompressions": ["RAW"]
}
}]
}
클라이언트 정보
clientID 및 clientVersion 필드는 개별 사용자가 아닌 클라이언트 구현을 고유하게 식별해야 합니다. (클라이언트 정보는 서버 측 로깅에 사용됩니다. 클라이언트 ID로 원하는 이름을 선택할 수 있지만 모두 소문자로 표시된 회사 이름과 같이 클라이언트의 실제 ID를 나타내는 이름을 선택하는 것이 좋습니다.
세이프 브라우징 목록
threatType, platformType, threatEntryType 필드가 결합되어 세이프 브라우징 목록을 식별 (이름)합니다. 이 예에서는 멀웨어/WINDOWS/URL 목록이 식별됩니다. 요청을 전송하기 전에 지정한 유형 조합이 유효한지 확인합니다(세이프 브라우징 목록 참고).
클라이언트 상태
state 필드에는 세이프 브라우징 목록의 현재 클라이언트 상태가 저장됩니다.
클라이언트 상태는 threatListUpdates.fetch 응답의 newClientState 필드에 반환됩니다.
초기 업데이트의 경우 state 필드를 비워둡니다.
크기 제한
maxUpdateEntries 필드는 클라이언트가 관리할 수 있는 총 업데이트 수를 지정합니다 (예: 2048). maxDatabaseEntries 필드는 로컬 데이터베이스가 관리할 수 있는 총 항목 수를 지정합니다 (이 예에서는 4096). 클라이언트는 메모리 및 대역폭 제한을 보호하고 목록 증가를 방지하려면 크기 제약 조건을 설정해야 합니다. 자세한 내용은 제약조건 업데이트를 참고하세요.
지원되는 압축
supportedCompressions 필드는 클라이언트에서 지원하는 압축 유형을 나열합니다. 이 예에서 클라이언트는 압축되지 않은 원시 데이터만 지원합니다. 하지만 세이프 브라우징은 추가 압축 유형을 지원합니다 (압축 참고).
HTTP POST 응답
이 예에서 응답은 요청된 압축 유형을 사용하여 세이프 브라우징 목록의 부분 업데이트를 반환합니다.
응답 헤더
응답 헤더에는 HTTP 상태 코드와 콘텐츠 유형이 포함됩니다. HTTP/200 이외의 상태 코드를 수신하는 클라이언트는 백오프 모드로 전환해야 합니다(요청 빈도 참고).
HTTP/1.1 200 OK Content-Type: application/json
응답 본문
응답 본문에는 업데이트 정보 (목록 이름, 응답 유형, 로컬 데이터베이스에 적용할 추가 및 삭제, 새 클라이언트 상태, 체크섬)가 포함됩니다. 이 예시에서 응답에 최소 대기 시간도 포함됩니다. 자세한 내용은 threatListUpdates.fetch 응답 본문과 코드 예시 뒤에 나오는 설명을 참조하세요.
{
"listUpdateResponses": [{
"threatType": "MALWARE",
"threatEntryType": "URL",
"platformType": "WINDOWS",
"responseType" : "PARTIAL_UPDATE",
"additions": [{
"compressionType": "RAW",
"rawHashes": {
"prefixSize": 4,
"rawHashes": "rnGLoQ=="
}
}],
"removals": [{
"compressionType": "RAW",
"rawIndices": {
"indices": [0, 2, 4]
}
}],
"newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
"checksum": {
"sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
}
}],
"minimumWaitDuration": "593.440s"
}
데이터베이스 업데이트
responseType 필드는 부분 또는 전체 업데이트를 나타냅니다. 이 예에서는 부분 업데이트가 반환되므로 응답에 추가와 삭제가 모두 포함됩니다. 추가 집합은 여러 개 있을 수 있지만 삭제 집합은 하나만 있을 수 있습니다(데이터베이스 업데이트 참조).
새 클라이언트 상태
newClientState 필드에는 새로 업데이트된 세이프 브라우징 목록의 새로운 클라이언트 상태가 포함됩니다.
클라이언트는 후속 업데이트 요청 (threatListUpdates.fetch 요청의 state 필드 또는 fullHashes.find 요청의 clientStates 필드)을 위해 새 클라이언트 상태를 저장해야 합니다.
검사합
체크섬을 사용하면 클라이언트가 로컬 데이터베이스가 손상되지 않았는지 확인할 수 있습니다. 체크섬이 일치하지 않으면 클라이언트는 데이터베이스를 지우고 빈 state 필드를 사용하여 업데이트를 다시 실행해야 합니다. 그러나 이 상황에서 클라이언트는 여전히 업데이트 시간 간격을 따라야 합니다(요청 빈도 참고).
최소 대기 시간
minimumWaitDuration 필드는 클라이언트가 다른 업데이트 요청을 보내기 전에 593.44초 (9.89분)를 기다려야 함을 나타냅니다. 대기 기간은 응답에 포함될 수도 있고 포함되지 않을 수도 있습니다 (요청 빈도 참고).
URL 확인
URL이 세이프 브라우징 목록에 포함되어 있는지 확인하려면 먼저 URL의 해시 및 해시 접두사 (URL 및 해싱 참고)를 계산해야 합니다. 그런 다음 클라이언트는 로컬 데이터베이스를 쿼리하여 일치하는 항목이 있는지 확인합니다. 로컬 데이터베이스에 해시 접두사가 없는 경우 URL은 안전한 것으로 간주됩니다 (세이프 브라우징 목록에는 포함되지 않음).
로컬 데이터베이스에 해시 접두사가 있는 경우 (해시 접두사 충돌) 클라이언트는 확인을 위해 해시 접두사를 세이프 브라우징 서버로 전송해야 합니다. 서버에서 지정된 해시 접두사가 포함된 모든 전체 길이 SHA 256 해시를 반환합니다. 이러한 전체 길이 해시 중 하나가 문제가 되는 URL의 전체 길이 해시와 일치하면 해당 URL은 안전하지 않은 것으로 간주됩니다. 전체 길이 해시가 문제가 되는 URL의 전체 길이 해시와 일치하지 않으면 URL이 안전한 것으로 간주됩니다.
Google은 검토 중인 URL에 대해 학습하지 않습니다. Google은 URL의 해시 접두사를 파악하지만 해시 접두사는 실제 URL에 관한 많은 정보를 제공하지 않습니다.
URL이 세이프 브라우징 목록에 있는지 확인하려면 fullHashes.find 메서드에 HTTP POST 요청을 보냅니다.
- HTTP
POST요청에는 최대 500개의 위협 항목이 포함될 수 있습니다. - HTTP
POST요청에는 확인할 URL의 해시 프리픽스가 포함됩니다. 대역폭 사용량을 줄이기 위해 클라이언트는 여러 위협 항목을 단일 요청으로 일괄 처리하는 것이 좋습니다. - HTTP
POST응답은 양수 및 음수 캐시 기간과 함께 일치하는 전체 길이 해시를 반환합니다. 응답은 최소 대기 시간을 반환할 수도 있습니다.
예: fullHashes.find
HTTP POST 요청
다음 예에서는 비교 및 확인을 위해 세이프 브라우징 목록 2개와 해시 프리픽스 3개의 이름이 전송됩니다.
요청 헤더
요청 헤더에는 요청 URL과 콘텐츠 유형이 포함됩니다. URL의 API_KEY를 API 키로 대체해야 합니다.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
요청 본문
요청 본문에는 클라이언트 정보 (ID 및 버전), 클라이언트 상태, 위협 정보 (목록 이름 및 해시 프리픽스)가 포함됩니다. JSON 요청의 경우 해시 프리픽스를 base64로 인코딩된 형식으로 전송해야 합니다. 자세한 내용은 fullHashes.find 요청 본문과 코드 예 다음에 나오는 설명을 참조하세요.
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"clientStates": [
"ChAIARABGAEiAzAwMSiAEDABEAE=",
"ChAIAhABGAEiAzAwMSiAEDABEOgH"
],
"threatInfo": {
"threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
"platformTypes": ["WINDOWS"],
"threatEntryTypes": ["URL"],
"threatEntries": [
{"hash": "WwuJdQ=="},
{"hash": "771MOg=="},
{"hash": "5eOrwQ=="}
]
}
}
클라이언트 정보
clientID 및 clientVersion 필드는 개별 사용자가 아닌 클라이언트 구현을 고유하게 식별해야 합니다. (클라이언트 정보는 서버 측 로깅에 사용됩니다. 클라이언트 ID로 원하는 이름을 선택할 수 있지만 모두 소문자로 표시된 회사 이름과 같이 클라이언트의 실제 ID를 나타내는 이름을 선택하는 것이 좋습니다.
모든 클라이언트 상태
clientStates 필드에는 클라이언트의 로컬 데이터베이스에 있는 모든 세이프 브라우징 목록의 클라이언트 상태가 포함됩니다. 클라이언트 상태는 threatListUpdates.fetch 응답의 newClientState 필드에 반환됩니다.
세이프 브라우징 목록
threatTypes, platformTypes, threatEntryTypes 필드가 결합되어 세이프 브라우징 목록을 식별 (이름)합니다. 이 예에서는 두 개의 목록, 즉 MALWARE/WINDOWS/URL과 SOCIAL_ENGINEERING/WINDOWS/URL이 식별됩니다. 요청을 전송하기 전에 지정한 유형 조합이 유효한지 확인하세요 (세이프 브라우징 목록 참고).
위협 해시 프리픽스
threatEntries 배열에는 확인하려는 URL의 해시 접두사가 포함됩니다.
hash 필드에는 로컬 데이터베이스에 있는 정확한 해시 접두사가 포함되어야 합니다. 예를 들어 로컬 해시 프리픽스의 길이가 4바이트인 경우 위협 항목의 길이는 4바이트여야 합니다. 로컬 해시 프리픽스가 7바이트로 연장된 경우 위협 항목의 길이는 7바이트여야 합니다.
이 예시에서는 요청에 해시 프리픽스 3개가 포함되어 있습니다. 세 가지 프리픽스를 각 세이프 브라우징 목록과 비교하여 일치하는 전체 길이 해시가 있는지 확인합니다.
참고: Update API 및 fullHashes.find 메서드는 항상 URL 필드가 아닌 hash 필드를 사용해야 합니다 (ThreatEntry 참고).
HTTP POST 응답
다음 예에서 응답은 캐시 및 대기 시간과 함께 세이프 브라우징 목록으로 구성된 일치하는 데이터를 반환합니다.
응답 헤더
응답 헤더에는 HTTP 상태 코드와 콘텐츠 유형이 포함됩니다. HTTP/200 이외의 상태 코드를 수신하는 클라이언트는 백오프해야 합니다 (요청 빈도 참조).
HTTP/1.1 200 OK Content-Type: application/json
응답 본문
응답 본문에는 일치 정보(목록 이름 및 전체 길이 해시, 메타데이터(있는 경우), 캐시 기간)가 포함됩니다. 이 예시에서는 응답 본문에 최소 대기 시간도 포함되어 있습니다. 자세한 내용은 fullHashes.find 응답 본문 및 코드 예 다음에 나오는 설명을 참고하세요.
{
"matches": [{
"threatType": "MALWARE",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"threat": {
"hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
},
"threatEntryMetadata": {
"entries": [{
"key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type"
"value": "TEFORElORw==" // base64-encoded "LANDING"
}]
},
"cacheDuration": "300.000s"
}, {
"threatType": "SOCIAL_ENGINEERING",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"threat": {
"hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
},
"threatEntryMetadata": {
"entries": []
},
"cacheDuration": "300.000s"
}],
"minimumWaitDuration": "300.000s",
"negativeCacheDuration": "300.000s"
}
일치 동영상
Match 객체는 두 해시 접두사에 대해 일치하는 전체 길이 해시를 반환합니다. 이러한 해시에 상응하는 URL은 안전하지 않은 것으로 간주됩니다. 세 번째 해시 프리픽스와 일치하는 항목이 없으므로 아무것도 반환되지 않습니다. 이 해시 프리픽스에 해당하는 URL은 안전한 것으로 간주됩니다.
이 예에서는 하나의 전체 길이 해시를 하나의 해시 접두사와 일치시킵니다. 그러나 동일한 해시 접두사에 매핑되는 전체 해시가 여러 개 있을 수 있습니다.
메타데이터
threatEntryMetadata 필드는 선택사항이며 위협 일치에 대한 추가 정보를 제공합니다. 현재 메타데이터는 멀웨어/WINDOWS/URL 세이프 브라우징 목록에 사용할 수 있습니다(메타데이터 참고).
캐시 기간
cacheDuration 및 negativeCacheDuration 필드는 해시가 안전하지 않거나 안전한 것으로 간주되어야 하는 시간을 나타냅니다 (캐싱 참고).
최소 대기 시간
minimumWaitDuration 필드는 클라이언트가 다른 fullHashes 요청을 보내기 전에 300초 (5분)를 기다려야 함을 나타냅니다. 대기 기간은 응답에 포함될 수도 있고 포함되지 않을 수도 있습니다(요청 빈도 참고).