The OpenDNS Umbrella Enforcement API Developer Hub

Welcome to the OpenDNS Umbrella Enforcement API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Umbrella Enforcement API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Introduction

 

Welcome to the Umbrella Enforcement API. The API is designed to give technology partners the ability to send security events from their platform/service/appliance within a mutual customer’s environment to the Cisco security cloud for enforcement. You may also list the domains and delete individual domains from the list. All received events will be segmented by the mutual customer and used for future enforcement.

In order to successfully integrate you will need to format your events to meet the public format included in this document. This API is a REST API and follows RESTful principles in implementation.

All responses are served as JSON and authentication is required for all requests. The API makes extensive use of query strings to retrieve and filter resources.

Note: The Enforcement API is only available for customers with the Platform Umbrella package, or partnering software companies that have entered into a business agreement with Cisco. For more information on packages, see Umbrella Package Comparison.


Authentication and Versioning

 

The API will be restricted to HTTPS and is hosted and available to make requests at: https://s-platform.api.opendns.com

Versioning in the API is handled via the url. All API endpoint urls will include a version including the major and minor version, following the pattern of Twitter's API.
Example: https://s-platform.api.opendns.com/1.0/events

Cisco reserves the right to add fields to the API endpoints and methods listed below. However, we will not remove any of the endpoints listed below in future versions of the API.

Customer authentication to the API is currently handled by a fixed UUID-v4 Customer key to be provided via the Integrations interface in the Umbrella dashboard. These keys must be supplied with each request to the API.

Example: https://s-platform.api.opendns.com/1.0/events?&customerKey=1111-2222-3333-4444


Limits, Responses, and Errors

 

All responses will follow RESTful practices including the correct HTTP response codes for successful and error states as well as returning arrays of resources and single resource for collection and read operations, respectively.

The following limits are in place on the API:

  • HTTP requests, including single or multiple event requests, are limited to a maximum total request size of 20 MB. This includes the request body, HTTP headers, and URI.
  • The API can handle both a single domain event being added or multiple events being added.
  • The maximum length of a domain is 255 characters as established by our data schema and RFC1034
  • Exceeding any of these limits will result in an HTTP 400 Bad Request being returned to the client.
  • The /domains endpoint is limited to 100 API calls per minute, per customer. HTTP 429 is returned if this limit is exceeded.

The API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with Cisco's servers.

HTTP Responses:

  • 202 Accepted—Everything worked as expected.
  • 400 Bad Request—Likely missing a required parameter or malformed JSON. Please check the syntax on your query.
  • 403 Unauthorized—Request had Authorization header but token was missing or invalid. Please ensure your API token is valid.
  • 404 Not Found—The requested item doesn't exist, check the syntax of your query or ensure the IP and/or domain are valid. If deleting a domain, ensure the id is correct.
  • 500, 502, 503, 504 Server errors—Something went wrong on our end.

API Endpoints

 

This section outlines three endpoints:

POST /events to add a domain to a domain list
GET /domains to gather a list of domains already added
DELETE /domain to delete a domain from the list.


POST /Events

 

Posts a Malware event to the API for processing and optionally adding to a customer's domain lists.

The POSTed event must conform to our Generic Event Format, which is outlined below.

Note

Requests to this endpoint must be sent with the Content-Type: application/json header

Example request for a single event

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}'

Example request for multiple events

In order to post multiple events to the endpoint, simply add the events following the generic event format in a JSON array as shown below.

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '[{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
},{
    "alertTime": "2015-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "moarinternetbadguys.com",
    "dstUrl": "http://moarinternetbadguys.com/a-bad-url-again",
    "eventTime": "2015-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}]'

GET /Domains

 

To gather the lists of domains already added to the shared customer’s domain list, run a GET request against the domains endpoint of the API.

An initial query will list a page of the first 200 results from the list, which are not ordered in any specific way. The limit for any query for this endpoint is 200.

Example request to get the Domain List

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \ 
-v -X GET

Domain List Query Results

Results are displayed in two arrays: meta and data

The meta array shows which page of results is available, the number of results and next and previous available pages to query. If ‘prev’ is false, this is the first available page of results. If ‘next’ is false, this is the last available page of results. Otherwise, ‘next’ and ‘prev’ will provide a query formatted to show the next set of results.

The data array contains the domains in the domain list, along with a unique ID number for each domain.

{
meta: {
	page: 1,
	limit: 200,
	prev: false,
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=200"
	},
data: [
		{
			id: 2388,
			name: "maliciousdomain.com"
	},
	{
			id: 7527,
			name: "phishingsite.com"
	},
	{
			id: 57769,
			name: "nastymalware.ru"
	},
	{
			id: 60758,
			name: "hackingsiteforkids.co.uk"
	},
	]
}

Pagination for /LIST Domains

In order to paginate the additional domains in a list, simply append “page=#” and “limit=###” to the query. The meta results from the initial query will show an example of this. In this example, we will show page three where the limit is 50 queries per page:

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=3&limit=50' \ 
-v -X GET

Example result for additional pagination

{
meta: {
	page: 3,
	limit: 50,
	prev: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=50",
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=4&limit=50"

	},
data: [
		{
			id: 9911797,
			name: "moremalware.com"
	},
	{
			id: 9911799,
			name: "russianhackers.com"
	},
	{
			id: 9939981,
			name: "mysteriousmalware.se"
	},
	]
}

DELETE /Domain

 

To delete a domain from the shared customer’s domain list, run a DELETE request against the domains endpoint of the API. The DELETE should include the numerical identifier (id) as specified in the LIST endpoint or the actual domain name you’d like to delete. Examples of both are provided below.

If successful, this endpoint will return HTTP 204 - No Content. Any other return besides 204 is unsuccessful.

IMPORTANT NOTE: The domain is contained in the URL for the Delete function and as such, must be URL-encoded or percent encoding. UTF-8 and Unicode encoding will not work and should be used.

Example query to delete by id:

curl -v \
     -i \
     -X DELETE \
     -H 'Content-Type: application/json' \
     'https://s-platform.api.opendns.com/1.0/domains/xxxxx?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Example query to delete by domain name:

curl -v \
		 -H 'Content-Type: application/json' \
		 -X DELETE 'https://s-platform.api.opendns.com/1.0/domains/domaintodelete.com?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' -v -X DELETE

Generic Event Format

 

The following is an example of how to arrange the public event format.

POST https://s-platform.api.opendns.com/1.0/events/
REQUEST
{
    "deviceId":"ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion":"13.7a",
    "eventTime":"2013-02-08T09:30:26Z",
    "alertTime":"2013-02-08T09:30:26Z",
    "dstDomain":"groogle.com",
    "dstUrl":"https://www.groogle.com/finance?q=NASDAQ:AAPL",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
    From here down is optional
    "disableDstSafeguards":true
    "dstIp":"8.8.8.8",
    "eventSeverity":"Severe",
    "eventType":"Cryptolocker",
    "eventDescription":"Win32/Crilock.A",
    "eventHash":"d41d8cd98f00b204e9800998ecf8427e",
    "fileName":"%AppData%RoamingMicrosoftWindowsTemplatesrandom.exe"
    "fileHash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "externalUrl":http://groogle.com/malware.html,
    "src":192.168.100.101
  }
    

Generic Event Format Field Descriptions

 

Note

The fields in bold are mandatory and must be supplied. The non-bolded fields are optional but best practice is to pass in as much information as possible. It's important to note that although this information must be provided when using the API, not all of it is utilized in the destination lists within Umbrella.

Field
Description

"deviceId"

The ID of the device sending the event.

"deviceVersion"

Version of device sending the event.

"eventTime"

Time event was detected, must match the following style 2013-02-08T09:30:26Z

"alertTime"

Time event was sent to Umbrella must match the following style 2013-02-08T09:30:26Z

"dstDomain"

The destination domain, specified following RFC3986 encoding guidelines and without the protocol included. An example would be 'www.internetbadguys.com'

"dstURL"

The destination URL encoded using standard percent-encoding following RFC3986](http://www.ietf.org/rfc/rfc3986.txt) encoding guidelines. An example would be 'http://internetbadguys.com/security?foo=there%20are%20spaces%20here'

"protocolVersion"

The version of the protocol for the API. Value should always be "1.0a"

"providerName"

The provider name for the API. Value should always be "Security Platform".

"disableDstSafeguards"

Boolean value, either 'true' or 'false'. 'false' is the same as not providing this field at all. A value of 'true' will will bypass validations normally performed against submitted events before adding them to any of the domain lists in Umbrella. This safety checking is known as the Domain Acceptance Process and is present to protect against third party automated systems accidentally submitting events with highly popular or known safe sites like google.com and potentially causing interruptions in service for your users.
The Domain Acceptance Process is described in detail in this section of the documentation: https://docs.umbrella.com/developer/enforcement-api/domain-acceptance-process2/
When disableSafeguards is set to true, the following parts of the acceptance process are skipped:
Ensuring that the domain is not in an list of known good domains (which is generally a list of the internet's most popular domains)
A check against the Cisco Umbrella Investigate API to see if domain is either not safe, unknown, or known good.
Normally, if a domain is known good on either of the checks listed above, the Security Platform will not submit the domain or URL and will not be present in your domain list or possibly blocked. Setting this value to true will increase the likelihood of a false positive or an outage in service tied to popular domains being blocked.

"dstIP"

The destination IP of the domain, specified in IPv4 dotted-decimal notation. An example would be '8.8.8.8'

"eventSeverity"

The parter threat level or rating, eg: severe, bad, high, etc.

"eventType"

Common name or classification of threat.

"eventDescription"

Variant or other descriptor of event type.

"eventHash"

A unique hash of the event.

"fileName"

Path to file exhibiting malicious behavior.

"fileHash"

SHA-1 of file reported by appliance.

"externalURL"

External page containing additional information about event.

"src"

IP/Host of the infected computer/device that was patient 0 for the event.


Domain Acceptance Process

 

When posting data to the Security Platform API, the following steps are taken before the domain appears in a customer's block list. The optional parameter "disableDstSafeguards" can be used to bypass parts of this process as outlined in the Generic Event Format Field Descriptions. The domain acceptance process is outlined from start to finish here:

  1. An external source identifies malicious activity occurring when a user visits a particular URL. This source could be a third party vendor’s data feed, an entry in one of your security logs or something identified as malicious on a security related website

  2. The event is sent to the Umbrella Security Platform API via a POST request, following the steps and syntax outlined earlier in this documentation.

  3. Before the domain included API POST event is added to the specified Umbrella customer’s block list, the following checks are performed:

    • Does the domain already exist in the Umbrella Security global block list under one of the Security Categories? Even if the domain does exist in the Umbrella global block list, it is still added to the customer’s block list.

    NOTE: In order to do the check against our global block list, the domain is submitted to the Cisco Umbrella Investigate API, which returns a score of -1 if the domain is malicious.

    • Is the domain considered benign, or safe, under the Cisco Umbrella Investigate? A domain is considered safe when a score of +1 is returned from the Investigate API. Domains that are considered safe are not added to the block list.

    The sorts of domains that are typically safe include ones that the Cisco security labs team has marked as safe or any domain found in the Alexa Top 1000.

    • Is the status of the domain uncategorized? A domain is considered uncategorized when the Umbrella Investigate API returns a score of 0. If a domain is uncategorized, it is added to the Umbrella customer’s block list.

    • Is the domain already present on the customer’s allow list within the organization? If so, the domain will still be added to the customer’s block list, however, please note that entries on a customer allow list will trump any customer-owned or Umbrella-owned block list.

  4. If the domain is then added to the customer’s domain list, then any domains in that list will be blocked in accordance with that customer’s Umbrella policy security settings.


はじめに

 

Cisco Umbrella Enforcement API へようこそ。この API は、共通のお客様の環境内にあるプラットフォーム/サービス/アプライアンスからセキュリティ イベントを Umbrella クラウドに送信して適用する機能をテクノロジー パートナーに提供します。また、ドメインをリストしたり、リストから個々のドメインを削除したりできます。受信したすべてのイベントは、共通のお客様によってセグメント化され、将来の適用のために使用されます。

正常に統合するには、イベントを書式設定して、以下の公開形式に適合させる必要があります。この API は REST API であり、実装の RESTful 原則に従います。

すべての応答は JSON として機能し、すべてのリクエストに対して認証が必要です。API は、リソースを取得およびフィルタするためにクエリ文字列をフル活用します。

次のセクション:認証とバージョン管理

認証とバージョン管理

 

API は HTTPS に制限されるほか、https://s-platform.api.opendns.com でホストされ、リクエストの実行に使用することができます。

API のバージョン管理は、URL を介して処理されます。すべての API エンドポイント URL には、Twitter の API のパターンに従い、メジャーおよびマイナー バージョンなどのバージョンが含まれます。例:https://s-platform.api.opendns.com/1.0/events

OpenDNS は、以下にリストされた API エンドポイントとメソッドにフィールドを追加する権限を保持しています。ただし、将来のバージョンの API では、以下にリストされたエンドポイントが削除されることはありません。
現在、API へのカスタマー認証は、Dashboard2 の統合インターフェイスを介して提供される UUID-v4 固定カスタマー キーによって処理されます。これらのキーは、API への各リクエストとともに提供する必要があります。

例:https://s-platform.api.opendns.com/1.0/events?&customerKey=1111-2222-3333-4444

次のセクション:制限、応答、およびエラーの処理

制限、応答、およびエラーの処理

 

すべての応答は、正常な状態およびエラー状態の正しい HTTP 応答コードや、収集および読み取り操作のためにリソースの配列や単一のリソースを返すことなど、RESTful プラクティスに準拠しています。

API では、次の制限が適用されます。

  • 単一または複数のイベント リクエストなどの HTTP リクエストは、20 MB の最大合計リクエスト サイズに制限されます。このサイズには、リクエスト本文、HTTP ヘッダー、URI が含まれます。
  • API は、追加される単一のドメイン イベントまたは追加される複数のイベントを処理できます。
  • シスコのデータ スキーマおよび RFC1034 で確立されているように、ドメインの最大長は 255 文字です。
  • これらの制限を超えると、HTTP 400 Bad Request がクライアントに返されます。

API では、従来の HTTP 応答コードを使用して、API リクエストの成功または失敗を示します。通常、2xx の範囲のコードは成功を、4xx の範囲のコードは提供された情報に起因するエラーを、5xx の範囲のコードは OpenDNS サーバのエラーを示します。

HTTP 応答:

  • 202 Accepted:すべてが想定どおりに機能しました。
  • 400 Bad Request:必要なパラメータがないか、JSON が無効である可能性があります。クエリの構文を確認してください。
  • 403 Unauthorized:リクエストには Authorization ヘッダーがあったが、トークンが存在しないか無効でした。API トークンが有効であることを確認してください。
  • 404 Not Found:リクエストしたアイテムが存在しません。クエリの構文を確認するか、IP またはドメインが有効であることを確認してください。ドメインを削除する場合、ID が正しいことを確認してください。
  • 500, 502, 503, 504 Server errors:サーバ側で何らかの問題が発生しました。

次のセクション: API エンドポイント

API エンドポイント

 

このセクションでは、次の 3 つのエンドポイントの概要を説明します。

POST /events:ドメインをドメイン リストに追加します。
GET /domains:すでに追加されているドメインのリストを収集します。
DELETE /domain:リストからドメインを削除します。

POST /Events

 

マルウェア イベントを API にポストし、処理したり、オプションでお客様のドメイン リストに追加したりします。

ポストされたイベントは、以下に説明する汎用イベント形式に準拠している必要があります。

(注)

このエンドポイントへのリクエストは、Content-Type: application/json ヘッダーで送信する必要があります。

単一のイベントのリクエストの例

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}'

複数のイベントのリクエストの例

エンドポイントに複数のイベントをポストするには、以下に示すように、JSON 配列の汎用イベント形式に従って、イベントを追加します。

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '[{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
},{
    "alertTime": "2015-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "moarinternetbadguys.com",
    "dstUrl": "http://moarinternetbadguys.com/a-bad-url-again",
    "eventTime": "2015-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}]'

GET /Domains

 

お客様の共有ドメイン リストにすでに追加されているドメインのリストを収集するには、API のドメイン エンドポイントに対してGET リクエストを実行します。

最初のクエリでは、リストの最初の 200 個の結果が記載されたページが表示され、その結果を特定の順番に並べることはできません。このエンドポイントに対するクエリの制限は 200 です。

ドメイン リストを取得するリクエストの例

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \ 
-v -X GET

ドメイン リストのクエリの結果

結果は、メタとデータの 2 つの配列で表示されます。

メタ配列には、利用可能な結果のページ、結果の数、クエリできる次または前のページが表示されます。「prev」が false の場合、このページが結果の利用可能な最初のページになります。「next」が false の場合、このページが結果の利用可能な最後のページになります。そうでない場合、「next」と「prev」により、結果の次のセットを表示するように書式設定されたクエリが提供されます。

データ配列には、ドメイン リストのドメインのほか、各ドメインの一意の ID 番号が含まれます。

{
meta: {
	page: 1,
	limit: 200,
	prev: false,
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=200"
	},
data: [
		{
			id: 2388,
			name: "maliciousdomain.com"
	},
	{
			id: 7527,
			name: "phishingsite.com"
	},
	{
			id: 57769,
			name: "nastymalware.ru"
	},
	{
			id: 60758,
			name: "hackingsiteforkids.co.uk"
	},
	]
}

/LIST Domains のページネーション

リストの追加ドメインをページネーションするには、クエリに「page=#」と「limit=###」を追加します。最初のクエリのメタ結果で、この例が示されます。この例では、ページあたり 50 個のクエリに制限されているページ 3 が表示されます。

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=3&limit=50' \ 
-v -X GET

追加ページネーションの結果の例

{
meta: {
	page: 3,
	limit: 50,
	prev: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=50",
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=4&limit=50"

	},
data: [
		{
			id: 9911797,
			name: "moremalware.com"
	},
	{
			id: 9911799,
			name: "russianhackers.com"
	},
	{
			id: 9939981,
			name: "mysteriousmalware.se"
	},
	]
}

DELETE /Domain

 

お客様の共有ドメイン リストからドメインを削除するには、API のドメイン エンドポイントに対して DELETE リクエストを実行します。DELETE には、LIST エンドポイントで指定されている数値 ID または削除するドメインの実際の名前を含める必要があります。以下に、両方の例を示します。

成功すると、このエンドポイントは、HTTP 204 - No Content を返します。204 以外が返された場合は失敗です。

要注意:ドメインは、Delete 関数の URL に含まれるため、URL にエンコードされるか、パーセント エンコーディングであることが必要です。 UTF-8 および Unicode エンコーディングは機能しないため、使用できません。

ID で削除するクエリの例:

curl -v \
     -i \
     -X DELETE \
     -H 'Content-Type: application/json' \
     'https://s-platform.api.opendns.com/1.0/domains/xxxxx?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

ドメイン名で削除するクエリの例:

curl -v \
     -i \
     -g \
     -X DELETE \
     -H 'Content-Type: application/json' \
     'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&where[name]=domaintodelete.com'

次のセクション:汎用イベント形式

汎用イベント形式

 

公開イベント形式を配置する方法の例を次に示します。

POST https://s-platform.api.opendns.com/1.0/events/
REQUEST
{
    "deviceId":"ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion":"13.7a",
    "eventTime":"2013-02-08T09:30:26.0Z",
    "alertTime":"2013-02-08T09:30:26.0Z",
    "dstDomain":"groogle.com",
    "dstUrl":"https://www.groogle.com/finance?q=NASDAQ:AAPL",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
    From here down is optional
    "disableDstSafeguards":true
    "dstIp":"8.8.8.8",
    "eventSeverity":"Severe",
    "eventType":"Cryptolocker",
    "eventDescription":"Win32/Crilock.A",
    "eventHash":"d41d8cd98f00b204e9800998ecf8427e",
    "fileName":"%AppData%RoamingMicrosoftWindowsTemplatesrandom.exe"
    "fileHash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "externalUrl":http://groogle.com/malware.html,
    "src":192.168.100.101
  }
    

汎用イベント形式フィールドの説明

 

(注)

太字のフィールドは必須であり、入力されている必要があります。太字ではないフィールドはオプションですが、ベスト プラクティスは、可能な限り多くの情報を提供することです。 API を使用するときに、この情報を提供する必要がありますが、OpenDNS 内のドメイン リストでは、すべての情報が利用されるわけではないことに注意してください。

フィールド
説明

"deviceID"

イベントを送信するデバイスの ID。

"deviceVersion"

イベントを送信するデバイスのバージョン。

"eventTime"

タイム イベントが検出されました。2013-02-08T09:30:26Z の形式に一致する必要があります。

"alertTime"

タイム イベントが OpenDNS に送信されました。2013-02-08T09:30:26Z の形式に一致する必要があります。

"dstDomain"

RFC3986 エンコーディング ガイドラインに従って指定され、含まれるプロトコルがない宛先ドメイン。たとえば、
www.internetbadguys.com。

"dstURL"

RFC3986 エンコーディング ガイドラインに従って標準のパーセント エンコーディングを使用してエンコードされた宛先 URL。たとえば、http://internetbadguys.com/security?foo=there%20are%20spaces%20here。

"protocolVersion"

API のプロトコルのバージョン。値は常に である必要があります。"1.0a"

"providerName"

API のプロバイダー名。値は常に である必要があります。"Security Platform"

"disableDstSafeguards"

「true」または「false」のブール値。「false」の場合、このフィールドを提供しないことと同じです。値が「true」の場合、Umbrella のドメイン リストにイベントを追加する前に、送信するイベント対して通常実行される検証がバイパスされます。この安全チェックはドメインの承認プロセスと呼ばれ、サードパーティの自動システムが google.com などの非常に人気のあるサイトまたは既知の安全なサイトで誤ってイベントを送信し、ユーザのサービスを中断することを防止します。
詳細については、「ドメインの承認プロセス」を参照してください。
disableSafeguards が true に設定されている場合、承認プロセスの次の部分がスキップされます。
ドメインが既知の正常なドメインのリスト(通常、インターネットで最も人気の高いドメインのリスト)に含まれていないことを確認します。
ドメインが安全ではない、未知である、または既知の正常な状態であるかどうかを確認するために、OpenDNS セキュリティ グラフと照合します。
通常、上記のいずれかのチェックでドメインが既知の正常な状態である場合、Security Platform は、ドメインまたは URL を送信しないことに加えて、ドメイン リストに存在しないか、ブロックされる可能性があります。この値を true に設定すると、ブロックされている人気のあるドメインに関連付けられているサービスで誤検出または停止が発生する可能性が高くなります。

"dstIP"

Ipv4 ドット形式 10 進表記法で指定されているドメインの宛先 IP。例は「8.8.8.8」です。

"eventSeverity"

パートナー脅威レベルまたは評価。例:重大、不良、高など。

"eventType"

脅威の一般的な名前または分類。

"eventDescription"

イベント タイプのバリアントまたはその他の説明。

"eventHash"

イベントの一意のハッシュ。

"fileName"

悪意のある動作を示しているファイルへのパス。

"fileHash"

アプライアンスからレポートされたファイルの SHA-1。

"externalURL"

イベントに関する追加情報が含まれている外部ページ。

"src"

イベントに対して「patient 0」であった感染したコンピュータまたはデバイスの IP/ホスト。

次のセクション: ドメインの承認プロセス

ドメインの承認プロセス

 

Security Platform API にデータをポストすると、お客様のブロック リストにドメインが表示される前に、次のステップが実行されます。「汎用イベント形式フィールドの説明」で示されているように、オプションのパラメータ「disableDstSafeguards」を使用して、このプロセスの一部をバイパスすることができます。

1.外部ソースにより、ユーザが特定の URL にアクセスしたときに発生する悪意のあるアクティビティが特定されます。このソースは、サードパーティのデータ フィード、いずれかのセキュリティ ログのエントリ、またはセキュリティ関連の Web サイトで悪意があると特定された何かである可能性があります。

2.イベントは、本ドキュメントで前述したステップと構文に従って、POST リクエストを介して OpenDNS Security Platform API に送信されます。

3.API POST イベントに含まれるドメインが OpenDNS のお客様の指定されたブロック リストに追加される前に、次の確認が実行されます。

  • いずれかのセキュリティ カテゴリの OpenDNS セキュリティ グローバル ブロック リストにドメインがすでに存在しているか。OpenDNS グローバル ブロック リストにドメインが存在している場合でも、ドメインはお客様のブロック リストに引き続き追加されます。

    注:グローバル ブロック リストと照合するために、ドメインは OpenDNS Investigate API に送信されます。ドメインに悪意がある場合、この API は -1 のスコアを返します。

  • OpenDNS Investigate で、ドメインは良性または安全であると判断されるか。Investigate API から +1 のスコアが返された場合、ドメインは安全であると見なされます。安全であると見なされるドメインはブロック リストに追加されません。

    一般に安全なドメインの種類は、OpenDNS Security Labs チームが安全であるとマークしたドメインや Alexa Top 1000 で見つかったドメインなどです。

  • ドメインのステータスは未分類か。OpenDNS Investigate API が 0 のスコアを返した場合、ドメインは未分類であると見なされます。ドメインが未分類である場合、ドメインは OpenDNS のお客様のブロック リストに追加されます。

  • ドメインは、組織内のお客様の許可リストにすでに存在しているか。許可リストに存在している場合、ドメインは、お客様のブロック リストに引き続き追加されますが、お客様の許可リストのエントリは、お客様または OpenDNS が所有するブロック リストよりも優先されることに注意してください。

4.ドメインがお客様のドメイン リストに追加された場合、お客様の Umbrella ポリシーのセキュリティ設定に従って、そのリストのドメインはブロックされます。

});