openapi: 3.0.0
info:
  title: Enforcement API
  version: v1.0.0
  description: Umbrella Enforcement API
  contact:
    name: Cloud Security Developer Community
servers:
  - url: https://s-platform.api.opendns.com/{basePath}
    variables:
      basePath:
        default: "1.0"
tags:
 - name: Register domain information
 - name: List blocked domains
 - name: Delete a domain
paths:
  '/events':
    post:
      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:
      - $ref: '#/components/parameters/customerKeyParam'
      requestBody:
        description: A list of domain information in the generic event format.
        content:
          application/json:
            schema:
              type: array
              items:
                $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':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  '/domains':
    get:
      operationId: getDomains
      tags:
      - List blocked domains
      summary: List blocked domains
      description: |-
        Get the unordered list of blocked domains.
        An initial query lists a page of the first 200 records from the collection.
        The limit for any query for this endpoint is 200.
      parameters:
      - $ref: '#/components/parameters/customerKeyParam'
      - name: limit
        in: query
        required: false
        description: The maximum number of records to return in the collection.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Used to paginate the additional domains in a list.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      page:
                        type: number
                        example: 1
                      limit:
                        type: number
                        example: 2
                      prev:
                        type: string
                        example: "false"
                      next:
                        type: string
                        example: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=2"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        name:
                          type: string
                        lastSeenAt:
                          type: number
                    example:
                      - id: 2388
                        name: 'maliciousdomain.com'
                        lastSeenAt: 1596104261
                      - id: 7527
                        name: 'phishingsite.com'
                        lastSeenAt: 1596104261
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  '/domains/{id}':
    delete:
      operationId: deleteDomainByIdentifier
      tags:
        - Delete a domain
      summary: Delete a domain
      description: |-
        Delete a domain. Provide the numerical domain ID or domain name.
        The domain name must be URL-encoded or use percent encoding.
        UTF-8 characters and Unicode encoding are not accepted formats.
      parameters:
      - $ref: '#/components/parameters/customerKeyParam'
      - name: id
        in: path
        required: true
        description: The domain ID or domain name.
        schema:
          type: string
      responses:
        '204':
          description: "No Content"
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
components:
  parameters:
    customerKeyParam:
      name: customerKey
      in: query
      required: true
      description: "A customer key assigned to the integration."
      schema:
        type: string
  schemas:
    GenericEventFormat:
      type: object
      required:
      - alertTime
      - deviceId
      - deviceVersion
      - dstDomain
      - dstUrl
      - eventTime
      - protocolVersion
      - providerName
      properties:
        alertTime:
          type: string
          description: |-
            The time the event was sent to Umbrella.
            Must 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.
            Provide 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.
            example: "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.
            A value of 'true' bypasses validations normally performed against submitted events before adding domains to the domain lists in Umbrella.
            This safety check 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.
            When disableSafeguards is set to true, the following parts of the acceptance process are skipped:
            Ensures that the domain is not in a list of known good domains (which is generally a list of the internet's most popular domains).
            Checks against the Cisco Umbrella Investigate API to see if domain is either not safe, unknown, or known good.
            If a domain is a known safe domain, Umbrella does not investigate the domain
            or URL and the domain does not appear in your domain list.
            Setting 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
  responses:
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    401Error:
      description: Unauthorized request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    500Error:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
