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

 

The Cisco Umbrella Enforcement 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 Umbrella 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.

To successfully integrate, you must format your events to meet the public format. 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.

Authentication and Versioning

 

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

Versioning in the API is handled through the URL. All API endpoint URLs include a version including the major and minor version, following the pattern of Twitter's API. For example, https://s-platform.api.opendns.com/1.0/events

Umbrella 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 handled by a fixed UUID-v4 Customer key. Keys must be supplied with each request to the API. For example, https://s-platform.api.opendns.com/1.0/events?&customerKey=1111-2222-3333-4444

To retrieve your key:

  1. Navigate to Policies > Policy Components > Integrations.
  2. Expand the appropriate integration or click Add to generate a custom Integration.

For more information, see Cisco Umbrella: The Umbrella Enforcement API for Custom Integrations.

Limits, Responses and Error Handling

 

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 1 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 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 OpenDNS'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.

Next: API Endpoints

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.

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 not 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 \
     -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'

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: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
  }
    

Generic Event Format Field Descriptions

 

The fields in bold are mandatory and must be supplied. The non-bolded fields are optional; however, 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 domain 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 OpenDNS, must match the following style 2013-02-08T09:30:26Z

"dstDomain"

The destination domain, specified following RFC3986 encoding guidelines and without the protocol included. For example,
www.internetbadguys.com.

"dstURL"

The destination URL encoded using standard percent-encoding following RFC3986 encoding guidelines. For example, 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 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.
For more information, see Domain Acceptance Process.
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 OpenDNS Security Graph 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, and so on.

"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.

  1. An external source identifies malicious activity occurring when a user visits a particular URL. This source could be a 3rd 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 OpenDNS 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 OpenDNS customer’s block list, the following checks are performed:

    • Does the domain already exist in the OpenDNS Security global block list under one of the Security Categories? Even if the domain does exist in the OpenDNS 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 OpenDNS Investigate API, which returns a score of -1 if the domain is malicious.

  • Is the domain considered benign, or safe, under the OpenDNS 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 OpenDNS 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 OpenDNS Investigate API returns a score of 0. If a domain is uncategorized, it is added to the OpenDNS 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 OpenDNS-owned blocklist.

  1. 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.

Creating Custom Integrations

 

Why Would I Use the Umbrella Enforcement API?

You might already process, manage, and curate your own threat intelligence system and processes that result in the desire to take actions on domains identified as malicious or suspicious. In that case, once a decision has been made that an event needs to be actioned on (for example, converted into protection), rather than manually adding protection to Umbrella for enforcement purposes, you can use the Enforcement API to automate this process and instantly enforce protection based on domains associated with the event.

This allows your security team to focus their time and effort on investigation rather than the ongoing configuration of Umbrella. It allows your security team to stay within their tools and processes instead of having to jump into the Umbrella dashboard to update destination lists. In essence, you are able to create a destination list in Umbrella from an external source that you manage directly through the API, then choose to block those destinations for identities within Umbrella.

See related information.

How Would I Use the Umbrella Enforcement API?

In the following example, an organization is using both Umbrella and Investigate alongside their own SIEM/TIP, and are leveraging a few of our APIs to create a full feedback loop.

This example organization has existing security tools and processes (for example, SIEM, TIP, and custom scripts) to provide visibility and response capabilities for their security teams. They can also optionally leverage Cisco Investigate to enrich those systems.Using the Enforcement API docs, the organization writes custom scripts that can inject events and list or delete domains added to the custom integration’s security category as a result of previous events.

はじめに

 

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要求は、最大合計要求サイズ1 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 ポリシーのセキュリティ設定に従って、そのリストのドメインはブロックされます。

});