{"type":"api","title":"Register list of domain information","meta":{"id":"/apps/pubhub/media/legacy-umbrella-api/bf58de618cbb72dda8f39b0414ce94c0a15cd467/86312610-23fe-3095-b9df-8fd01f7f8e0d","info":{"title":"Enforcement API","version":"v1.0.0","description":"Umbrella Enforcement API","contact":{"name":"Cloud Security Developer Community"}},"tags":[{"name":"Register domain information"},{"name":"List blocked domains"},{"name":"Delete a domain"}],"x-parser-conf":{"overview":{"markdownPath":"legacy/enforcement/enforcement-overview-api-reference.md"},"meta":{"useProxy":true}},"openapi":"3.0.0","servers":[{"url":"https://s-platform.api.opendns.com/{basePath}","variables":{"basePath":{"default":"1.0"}}}]},"spec":{"operationId":"postEvents","tags":["Register domain information"],"summary":"Register list of domain information","description":"Register a list of domain information. Domains may be added to the customer's domain block lists.","parameters":[{"name":"customerKey","in":"query","required":true,"description":"A customer key assigned to the integration.","schema":{"type":"string"},"$$ref":"#/components/parameters/customerKeyParam"}],"requestBody":{"description":"A list of domain information in the generic event format.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["alertTime","deviceId","deviceVersion","dstDomain","dstUrl","eventTime","protocolVersion","providerName"],"properties":{"alertTime":{"type":"string","description":"The time the event was sent to Umbrella.\nMust match the following format: 2013-02-08T09:30:26Z.","example":"2013-02-08T09:30:26Z"},"deviceId":{"type":"string","description":"The ID of the device sending the event.","example":"device ID"},"deviceVersion":{"type":"string","description":"The version of the device sending the event.","example":"version of device"},"dstDomain":{"type":"string","description":"The destination domain specified following RFC 3986 encoding guidelines.\nProvide a string without the protocol.","example":"www.internetbadguys.com"},"dstUrl":{"type":"string","description":"The destination URL specified following RFC 3986 encoding guidelines.","example":"http://internetbadguys.com/security?foo=there%20are%20spaces%20here"},"eventTime":{"type":"string","description":"The time the event was detected. Must match the following date and time format: 2013-02-08T09:30:26Z.\nexample: \"2013-02-08T09:30:26Z\""},"protocolVersion":{"type":"string","description":"The version of the protocol for the API. Valid value 1.0a.","example":"1.0a"},"providerName":{"type":"string","description":"The provider name for the API. Value should always be 'Security Platform'."},"disableDstSafeguards":{"type":"boolean","description":"Valid values: true or false. If left undefined, the value is false.\nA value of 'true' bypasses validations normally performed against submitted events before adding domains to the domain lists in Umbrella.\nThis safety check is known as the Domain Acceptance Process and is present to protect against third party automated systems accidentally\nsubmitting events with highly popular or known safe sites like google.com and potentially causing interruptions in service for your users.\nWhen disableSafeguards is set to true, the following parts of the acceptance process are skipped:\nEnsures that the domain is not in a list of known good domains (which is generally a list of the internet's most popular domains).\nChecks against the Cisco Umbrella Investigate API to see if domain is either not safe, unknown, or known good.\nIf a domain is a known safe domain, Umbrella does not investigate the domain\nor URL and the domain does not appear in your domain list.\nSetting this value to true increases the likelihood of a false positive or an outage in service tied to popular domains being blocked."},"dstIP":{"type":"string","description":"The destination IP of the domain, specified in IPv4 dotted-decimal notation.","example":"8.8.8.8"},"eventSeverity":{"type":"string","description":"The partner threat level or rating. For example: severe, bad, high.","example":"high"},"eventType":{"type":"string","description":"Common name or classification of threat.","example":"classification of threat"},"eventDescription":{"type":"string","description":"Variant or other descriptor of event type.","example":"description of event type"},"eventHash":{"type":"string","description":"A unique hash of the event.","example":"unique hash of event"},"fileName":{"type":"string","description":"Path to file exhibiting malicious behavior.","example":"path to file"},"fileHash":{"type":"string","description":"SHA-1 of file reported by appliance.","example":"SHA-1 of file"},"externalURL":{"type":"string","description":"External page containing additional information about event.","example":"external page"},"src":{"type":"string","description":"The first IP or hostname associated with the infected device.","example":"IP address of first host"}},"$$ref":"#/components/schemas/GenericEventFormat"}},"example":[{"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"}]}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}},"example":{"id":"ba6a59f4-e692-4724-ba36-c28132c761de"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"$$ref":"#/components/responses/400Error"},"401":{"description":"Unauthorized request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"$$ref":"#/components/responses/401Error"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"$$ref":"#/components/responses/403Error"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"$$ref":"#/components/responses/404Error"},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"$$ref":"#/components/responses/500Error"}},"__originalOperationId":"postEvents","method":"post","path":"/events"}}