openapi: 3.0.0
info:
  title: Investigate API
  description: Umbrella Investigate API
  version: 1.1.4
  contact:
    name: Cloud Security Developer Community
servers:
  - url: https://investigate.api.umbrella.com
tags:
- name: Domain Status and Categorization
- name: Domain Volume
- name: Co-occurrences for a Domain
- name: Passive DNS
- name: Tagging Timeline
- name: Subdomains for a Domain
- name: Related Domains for a Domain
- name: Security Information for a Domain
- name: AS Information for a Domain
- name: WHOIS Information for a Domain
- name: Umbrella Popularity List-Top Million Domains
- name: Search Domain
#- name: Threat Grid Integration—Cisco AMP Threat Grid
- name: Cisco Secure Malware Analytics Integration
security:
  - bearerAuth: []

paths:
  '/domains/categorization/{domain}':
    get:
      summary: Get Domain Status and Categorization
      operationId: getDomainsCategorization
      tags:
        - Domain Status and Categorization
      description: |
        Look up the status, and security and content category IDs for the domain.
        The domain status is a numerical value determined by the Cisco Security Labs team.
        Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status).
      parameters:
      - $ref: '#/components/parameters/domainParam'
      - name: showLabels
        in: query
        required: false
        description: |-
          Include the showLabels query parameter to display the human-readable
          or named category labels in the response.
          For example: https://investigate.api.umbrella.com/domains/categorization/umbrella.com?showLabels
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainCategorization'
              example:
                amazon.com:
                  status: 1
                  security_categories: []
                  content_categories:
                    - 8
        '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/categorization':
    post:
      summary: Check Status and Categorization of Domains
      operationId: postDomainsCategorization
      tags:
        - Domain Status and Categorization
      description: |
        Provide a list of domains and look up the status, and security and content category IDs for each domain.
        The domain status is a numerical value determined by the Cisco Security Labs team.
        Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status).
      parameters:
      - name: showLabels
        in: query
        required: false
        description: |-
          Include the showLabels query parameter to display the human-readable
          or named category labels in the response.
          For example: https://investigate.api.umbrella.com/domains/categorization/umbrella.com?showLabels
        schema:
          type: string
      requestBody:
        required: true
        description: |-
          In a single request, the payload must not exceed 100KB and contain no more
          than 1000 domains.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: The list of domains.
            example:
              - "google.com"
              - "yahoo.com"
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DomainCategorization'
              example:
                - google.com:
                  status: 1
                  security_categories: []
                  content_categories:
                    - 23
                    - 25
                    - 190
                - yahoo.com:
                  status: 1
                  security_categories: []
                  content_categories:
                    - 23
                    - 167
        '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/volume/{domain}':
    get:
      summary: Get Domain Volume
      operationId: getDomainVolume
      tags:
        - Domain Volume
      description: |
        List the query volume for a domain for the last 30 days.
        If there is no information about the domain, Umbrella Investigate returns an empty array.
        As the query takes time to generate, the last two hours may be blank.
      parameters:
      - $ref: '#/components/parameters/domainParam'
      - name: start
        in: query
        required: false
        description: |-
          Point in time in the past, expressed as a timestamp in milliseconds
          or relative time. Valid formats: start=-2days, start=-2hours start=1509332100000.
          The maximum time range is 30 days.
        schema:
          type: string
      - name: stop
        in: query
        required: false
        description: |-
          Point in time in the past expressed as a timestamp in milliseconds
          or relative time. Valid formats: stop=-1days, stop=now, stop=1509642000000.
          The maximum time range is 30 days.
        schema:
          type: string
      - name: match
        in: query
        required: false
        description: |-
          Valid options are: 'exact', 'component', or 'all' which is the default value.
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dates:
                    type: array
                    items:
                      type: string
                    description: Date and time recorded for this domain expressed in Unix epoch time.
                  queries:
                    type: array
                    items:
                      type: string
                    description: Number of DNS queries for the domain per hour, listed in ascending order.
              example:
                dates:
                  - "1510873200000"
                  - "1510959600000"
                queries:
                  - "1378426"
                  - "1361934"
                  - "1308188"
                  - "1238823"
                  - "1245126"
                  - "1215994"
                  - "1256917"
                  - "1200190"
                  - "1245963"
                  - "1355719"
                  - "1332685"
                  - "1319825"
                  - "1362464"
                  - "1457174"
                  - "1695448"
        '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'

  '/recommendations/name/{domain}.json':
    get:
      summary: Get Recommendations by Name
      operationId: getRecommendationsName
      tags:
        - Co-occurrences for a Domain
      description: |-
        List the co-occurences for the specified domain.
        A co-occurrence is when two or more domains are accessed by the same users within a small window of time.
        Co-occurring domains are not necessarily problematic; legitimate sites co-occur with each other as a part
        of normal web activity. However, unusual or suspicious co-occurences can provide additional information regarding attacks.
        To determine co-occurrences for a domain, a small time window of traffic across all of our datacenters is taken.
        Umbrella Investigate checks the sites that end users visited before and after the domain was requested in the API call.
      parameters:
      - $ref: '#/components/parameters/domainParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pfs2:
                    type: array
                    items:
                      type: string
                    description: Returns a list of domain names.
                  found:
                    type: boolean
                    items:
                      type: boolean
                    description: Returns true if results available.
              example:
                pfs2:
                  - "download.example.com"
                  - "query.example.com"
                found: true
        '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'

  '/pdns/name/{domain}':
    get:
      summary: Get Resource Records for Name
      operationId: getPassiveDNSName
      tags:
        - Passive DNS
      description:
        The Passive DNS endpoint provides historical data from the Umbrella resolvers for domains,
        IPs, and other resource records.
      parameters:
      - $ref: '#/components/parameters/domainParam'
      - $ref: '#/components/parameters/limitRecordsParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortorderParam'
      - $ref: '#/components/parameters/sortbyParam'
      - $ref: '#/components/parameters/recordTypeParam'
      - $ref: '#/components/parameters/includeFeaturesParam'
      - $ref: '#/components/parameters/minFirstSeenParam'
      - $ref: '#/components/parameters/maxFirstSeenParam'
      - $ref: '#/components/parameters/minLastSeenParam'
      - $ref: '#/components/parameters/maxLastSeenParam'
      - $ref: '#/components/parameters/sortCategoriesParam'
      - $ref: '#/components/parameters/requiredCategoriesParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Records'
              example:
                - minTtl: 86400
                  maxTtl: 86400
                  firstSeen: 1506630180
                  lastSeen: 1557133071
                  name: "coinhive.com"
                  type: "NS"
                  rr: "lara.ns.cloudflare.com."
                  securityCategories: []
                  contentCategories:
                    - "Software/Technology"
                    - "Business Services"
                  firstSeenISO: "2017-09-28T20:23Z"
                  lastSeenISO: "2019-05-06T08:57Z"
        '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'

  '/pdns/domain/{domain}':
    get:
      summary: Get Resource Records for Domain
      operationId: getPassiveDNSDomain
      tags:
        - Passive DNS
      description: Returns the Resource Record (RR) data for DNS responses, and categorization
        data, where the answer (or rdata) is the domain(s).
      parameters:
      - $ref: '#/components/parameters/domainParam'
      - $ref: '#/components/parameters/limitRecordsParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortorderParam'
      - $ref: '#/components/parameters/sortbyParam'
      - $ref: '#/components/parameters/recordTypeParam'
      - $ref: '#/components/parameters/includeFeaturesParam'
      - $ref: '#/components/parameters/minFirstSeenParam'
      - $ref: '#/components/parameters/maxFirstSeenParam'
      - $ref: '#/components/parameters/minLastSeenParam'
      - $ref: '#/components/parameters/maxLastSeenParam'
      - $ref: '#/components/parameters/sortCategoriesParam'
      - $ref: '#/components/parameters/requiredCategoriesParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Records'
              example:
                - minTtl: 3600
                  maxTtl: 3600
                  firstSeen: 1482339360
                  lastSeen: 1482339360
                  name: "coinhive.com"
                  type: "CNAME"
                  rr: "www.coinhive.com."
                  securityCategories:
                    - "Potentially Harmful"
                    - "Cryptomining"
                  contentCategories: []
                  firstSeenISO: "2016-12-21T16:56Z"
                  lastSeenISO: "2016-12-21T16:56Z"
        '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'

  '/pdns/ip/{ip}':
    get:
      summary: Get Resource Records for IP
      operationId: getPassiveDNSIp
      tags:
        - Passive DNS
      description: Returns the Resource Record (RR) data for DNS responses, and categorization
        data, where the answer (or rdata) is the domain(s).
      parameters:
      - name: ip
        in: path
        required: true
        description: An IP address, such as 208.67.222.222 or 2620:119:35::35.
        schema:
          type: string
      - $ref: '#/components/parameters/limitRecordsParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortorderParam'
      - $ref: '#/components/parameters/sortbyParam'
      - $ref: '#/components/parameters/recordTypeParam'
      - $ref: '#/components/parameters/includeFeaturesParam'
      - $ref: '#/components/parameters/minFirstSeenParam'
      - $ref: '#/components/parameters/maxFirstSeenParam'
      - $ref: '#/components/parameters/minLastSeenParam'
      - $ref: '#/components/parameters/maxLastSeenParam'
      - $ref: '#/components/parameters/sortCategoriesParam'
      - $ref: '#/components/parameters/requiredCategoriesParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Records'
              example:
                - minTtl: 3600
                  maxTtl: 3600
                  firstSeen: 1544388420
                  lastSeen: 1553839713
                  name: "146.112.61.104"
                  type: "A"
                  rr: "hit-block.umbrella.com."
                  securityCategories: []
                  contentCategories:
                    - "Software/Technology"
                  firstSeenISO: "2018-12-09T20:47Z"
                  lastSeenISO: "2019-03-29T06:08Z"
        '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'

  '/pdns/raw/{anystring}':
    get:
      summary: Get Resource Records for Raw Data
      operationId: getPassiveDNSRaw
      tags:
        - Passive DNS
      description: Returns the Resource Record (RR) data for DNS responses, and categorization
        data, where the answer (or rdata) could be anything.
      parameters:
      - name: anystring
        in: path
        required: true
        description: |-
          The text representation of the data. When querying TXT records, add quotes around the text.
          For example, to search for 'abc', provide the query: 'https://investigate.umbrella.com/pdns/raw/%22abc%22'.
        schema:
          type: string
      - $ref: '#/components/parameters/limitRecordsParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortorderParam'
      - $ref: '#/components/parameters/sortbyParam'
      - $ref: '#/components/parameters/recordTypeParam'
      - $ref: '#/components/parameters/includeFeaturesParam'
      - $ref: '#/components/parameters/minFirstSeenParam'
      - $ref: '#/components/parameters/maxFirstSeenParam'
      - $ref: '#/components/parameters/minLastSeenParam'
      - $ref: '#/components/parameters/maxLastSeenParam'
      - $ref: '#/components/parameters/sortCategoriesParam'
      - $ref: '#/components/parameters/requiredCategoriesParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Records'
              example:
                - minTtl: 3600
                  maxTtl: 3600
                  firstSeen: 1544386020
                  lastSeen: 1555327199
                  name: "926723159-3188410"
                  type: "TXT"
                  rr: "cisco.com"
                  securityCategories: []
                  contentCategories:
                    - "Software/Technology"
                    - "Business Services"
                  firstSeenISO: "2018-12-09T20:07Z"
                  lastSeenISO: "2019-04-15T11:19Z"
        '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'

  '/links/name/{domain}':
    get:
      summary: Get Related Domains for Domain
      operationId: getLinksName
      tags:
        - Related Domains for a Domain
      description: |-
        Returns a list of domain names that have been frequently requested around
        the same time (up to 60 seconds before or after) as the given domain name,
        but that are not frequently associated with other domain names.
      parameters:
        - $ref: '#/components/parameters/domainParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tb1:
                    type: array
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                        score:
                          type: number
                    description: |-
                      Array of [domain name, score] tuple where score is the number of client IP requests
                      to the site around the same time as the site being looked up.
                      This is a score reflecting the number of client IPs looking up related
                      sites within 60 seconds of the original request.
                  found:
                    type: boolean
                    description: Returns true if results available.
              example:
                tb1:
                  - domain: "www.example1.com"
                    score: 10
                  - domain: "info.example2.com"
                    score: 9
                  - domain: "support.example.com"
                    score: 3
                found: true
        '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'

  '/security/name/{domain}':
    get:
      summary: Get Security Score Information for Domain
      operationId: getSecurityName
      tags:
        - Security Information for a Domain
      description: |-
        List multiple scores or security features for a domain. You can use the scores
        or security features to determine relevant datapoints and build insights on the reputation
        or security risk posed by the site. No one security information feature is conclusive.
        Instead, consider these features as part of your security research.
      parameters:
        - $ref: '#/components/parameters/domainParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dga_score:
                    type: number
                    description: |-
                      Domain Generation Algorithm. This score is generated based on the likeliness
                      of the domain name being generated by an algorithm
                      rather than a human. This algorithm is designed to identify domains which
                      have been created using an automated randomization
                      strategy, which is a common evasion technique in malware kits or botnets.
                      This score ranges from -100 (suspicious) to 0 (benign).
                  perplexity:
                    type: number
                    description: |-
                      A second score on the likeliness of the name to be algorithmically
                      generated, on a scale from 0 to 100. This score is to be used in conjunction with DGA.
                  entropy:
                    type: number
                    description: The number of bits required to encode the domain name, as a score.
                      This score is to be used in conjunction with DGA and Perplexity.
                  securerank2:
                    type: number
                    description: |-
                      Suspicious rank for a domain that reviews based on the lookup behavior
                      of client IP for the domain.
                      Securerank is designed to identify hostnames requested by known infected
                      clients but never requested by clean clients,
                      assuming these domains are more likely to be bad.
                      Scores returned range from -100 (suspicious) to 100 (benign).
                  pagerank:
                    type: number
                    description: Popularity according to Google's pagerank algorithm.
                  asn_score:
                    type: number
                    description: |-
                      ASN reputation score, ranges from -100 to 0 with -100 being very suspicious.
                  prefix_score:
                    type: number
                    description: |-
                      Prefix ranks domains given their IP prefixes
                      (an IP prefix is the first three octets in an IP address)
                      and the reputation score of these prefixes. Ranges from -100 to 0, -100 being
                      very suspicious.
                  rip_score:
                    type: number
                    description: |-
                      RIP ranks domains given their IP addresses and the reputation score
                      of these IP addresses. Ranges from -100 to 0, -100 being very suspicious.
                  popularity:
                    type: number
                    description: |-
                      The number of unique client IPs visiting this site, relative to the all
                      requests to all sites. A score of how many different client/unique IPs go
                      to this domain compared to others.
                  geodiversity:
                    type: array
                    items:
                      type: number
                    description: A score representing the number of queries from clients visiting the domain,
                      broken down by country. Score is a non-normalized ratio between 0 and 1.
                  geodiversity_normalized:
                    type: array
                    items:
                      type: number
                    description: A score representing the amount of queries for clients visiting the domain,
                      broken down by country. Score is a normalized ratio between 0 and 1.
                  tld_geodiversity:
                    type: array
                    items:
                      type: number
                    description: |-
                      A score that represents the TLD country code geodiversity as a percentage
                      of clients visiting the domain.
                      Occurs most often with domains that have a ccTLD. Score is normalized ratio
                      between 0 and 1.
                  geoscore:
                    type: number
                    description: |-
                      A score that represents how far the different physical locations serving this name
                      are from each other.
                  ks_test:
                    type: number
                    description: |-
                      Kolmogorov-Smirnov test on geodiversity. 0 means that the client traffic matches
                      what is expected for this TLD.
                  attack:
                    type: string
                    description: |-
                      The name of any known attacks associated with this domain.
                      Returns blank if no known threat associated with domain.
                  threat_type:
                    type: string
                    description: |-
                      The type of the known attack, such as botnet or APT. Returns blank if no known
                      threat associated with domain.
                  found:
                    type: boolean
                    description: |-
                      Returns true if results available. Returns blank if no known threat associated
                      with domain.
              example:
                dga_score: 38.301771886101335
                perplexity: 0.4540313302593146
                entropy: 2.5216406363433186
                securerank2: -1.3135141095601992
                pagerank: 0.0262532
                asn_score: -29.75810625887133
                prefix_score: -64.9070502788884
                rip_score: -75.64720536038982
                popularity: 25.335450495507196
                geodiversity:
                  - 0.24074075
                  - 0.018518519
                geodiversity_normalized:
                  - 0.3761535390278368
                  - 0.0005015965168831449
                tld_geodiversity:
                  - 0.0
                geoscore: 0
                ks_test: 0
                attack: ""
                threat_type: ""
                found: true
        '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/risk-score/{domain}':
    get:
      summary: Get Risk Score for Domain
      operationId: getDomainsRiskScore
      tags:
        - Security Information for a Domain
      description: |-
        The Umbrella Investigate Risk Score is based on an analysis of
        the lexical characteristics of the domain name
        and patterns in queries and requests to the domain.
        The risk score is scaled from 0 to 100, with 100 being the highest risk
        and 0 being no risk at all. Periodically Umbrella updates this score based
        on additional inputs.
        A domain blocked by Umbrella receives a score of 100.
      parameters:
        - $ref: '#/components/parameters/domainParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/RiskScore'
              example:
                indicators:
                  - indicator: "Geo Popularity Score"
                    normalized_score: 2
                    score: -3.610878169999999
                  - indicator: "Keyword Score"
                    normalized_score: 3
                    score: 0.03586190445512534
                  - indicator: "Lexical"
                    normalized_score: 52
                    score: 0.525
                  - indicator: "Popularity 1 Day"
                    normalized_score: 100
                    score: 113.14
                  - indicator: "Popularity 30 Day"
                    normalized_score: 100
                    score: 112.01
                  - indicator: "Popularity 7 Day"
                    normalized_score: 100
                    score: 112.86
                  - indicator: "Popularity 90 Day"
                    normalized_score: 100
                    score: 111.4
                  - indicator: "TLD Rank Score"
                    normalized_score: 1
                    score: 0.010000315765229171
                  - indicator: "Umbrella Block Status"
                    normalized_score: 0
                    score: 0
                risk_score: 4
        '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'

  '/bgp_routes/ip/{ip}/as_for_ip.json':
    get:
      summary: Get BGP Route Information for IP
      operationId: getBgpRoutesIp
      tags:
        - AS Information for a Domain
      description: |-
        This endpoint provides data about ASN and IP relationships,
        showing how IP addresses are related to each other and to the regional registries.
        You can find out more about the IP space associated with an AS
        and correlate BGP routing information between AS.

        When querying an IP to find which AS (Autonomous System), it is helpful
        to find associated IP addresses. The AS is part of the BGP routing for that IP.
        To return the AS information for an IP, use the endpoint /bgp_routes/ip/.
        A valid result returns an array of hash references.
        The hash reference contains information about the AS such as the ASN,
        the CIDR prefix of the AS, the Internet Registry (RIR) number (0 through 6),
        the Description of the AS and the creation date for the AS.
        An empty response returns an empty array ([]).
      parameters:
      - name: ip
        in: path
        required: true
        description: IPv4 IP address for which to obtain the AS information
        schema:
          type: string
      responses:
        '200':
          description: Success. Returns data about ASN & IP relationships.
          content:
            application/json:
              schema:
                type: object
                properties:
                  creation_date:
                    type: string
                    description: Date when AS was first created.
                  ir:
                    type: integer
                    description: |-
                      The IR number corresponds to one of the 5 Regional Internet Registries (RIR).
                      | Registry | Number |	Region |
                      |-----|-----|-----|
                      | Registry | 1 | AfriNIC: Africa |
                      | Registry | 2 | APNIC: Asia, Australia, New Zealand, and neighboring countries. |
                      | Registry | 3 | ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica. |
                      | Registry | 4 | LACNIC: Latin America and parts of the Caribbean region. |
                      | Registry | 5 | RIPE NCC: Europe, Russia, the Middle East, and Central Asia. |
                      | Registry | 0 | Unknown / Not Available |
                  description:
                    type: string
                    description: Network Owner Description as provided by the network owner.
                  asn:
                    type: string
                    description: Autonomous System Number (ASN) associated with this IP address.
                  cidr:
                    type: string
                    description: IP CIDR for the ASN.
              example:
                creation_date: "2002-08-01"
                ir: 2
                description: "CHINANET-BACKBONE No.31,Jin-rong Street,CN 86400"
                asn: "4134"
                cidr: "123.172.0.0/15"
        '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'

  '/bgp_routes/asn/{asn}/prefixes_for_asn.json':
    get:
      summary: Get BGP Route Information for ASN
      operationId: getBgpRoutesAsn
      tags:
        - AS Information for a Domain
      description: |
        A response to a valid ASN returns an array of hash references.
        Each hash reference contains two keys: geo and cidr.
        Geo is a hash reference with the country name and country code
        (the code corresponds to the country code list for ISO-3166-1 alpha-2).
        CIDR contains the IP prefix for this ASN.
      parameters:
      - name: asn
        in: path
        required: true
        description: Autonomous System Number (ASN) for the AS.
        schema:
          type: string
      responses:
        '200':
          description: Success. Returns an array of hash references.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cidr:
                    type: array
                    items:
                      type: string
                    description: |-
                      A list of the CIDR Range of IP addresses associated with this AS.
                      The CIDR contains the IP prefix for the ASN.
                  geo:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                    description: |-
                      Geo is a hash reference with the country name and country code
                      (the code corresponds to the country code list for ISO-3166-1 alpha-2).
                      For more information, see [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
              example:
                cidr:
                  - '98.143.32.0/20'
                geo:
                  name: United States
                  id: 10
        '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'

  '/whois/{domain}':
    get:
      summary: Get WHOIS Information for Domain
      operationId: getWhois
      tags:
        - WHOIS Information for a Domain
      description: |
        This endpoint returns WHOIS information for the specified email addresses,
        nameservers, and domains. You can search by multiple email addresses or multiple nameservers.
        This documentation outlines the following API endpoints: Email (single and multiple) Domain
        Record (current and historical) and Nameserver (single and multiple).
        In some instances, WHOIS information can be irregular as there are no standards
        between domain registrars and large volumes of information can be returned from a query.
        As such, both the email and nameserver WHOIS endpoints have a limit of 500 results,
        which you can reduce to a smaller set of results.
        There is an `offset` parameter that can be leveraged to retrieve the entire set
        of domain entries for a given email without any limitation. Only the email parameter
        supports this.
        The email parameter can also be sorted by filtering the entries based on the timestamp field.
        If a domain, email or nameserver has no known WHOIS information, HTTP 404 is returned.
        If a domain, email or nameserver does not exist, HTTP 404 is returned.
      parameters:
      - name: domain
        in: path
        required: true
        description: Domain name without wildcards and including top-level domain (TLD).
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WhoisDomain'
              example:
                - administrativeContactFax: ""
                  whoisServers: ""
                  addresses:
                    - "1600 amphitheatre parkway"
                    - "please contact contact-admin@google.com, 1600 amphitheatre parkway"
                    - "2400 e. bayshore pkwy"
                  administrativeContactName: "DNS Admin"
                  zoneContactEmail: ""
                  billingContactFax: ""
                  administrativeContactTelephoneExt: ""
                  administrativeContactEmail: "dns-admin@google.com"
                  technicalContactEmail: "dns-admin@google.com"
                  technicalContactFax: "16506181499"
                  nameServers:
                    - "ns1.google.com"
                    - "ns2.google.com"
                    - "ns3.google.com"
                    - "ns4.google.com"
                  zoneContactName: ""
                  billingContactPostalCode: ""
                  zoneContactFax: ""
                  registrantTelephoneExt: ""
                  zoneContactFaxExt: ""
                  technicalContactTelephoneExt: ""
                  billingContactCity: ""
                  zoneContactStreet: []
                  created: ""
                  administrativeContactCity: "Mountain View"
                  registrantName: "Dns Admin"
                  zoneContactCity: ""
                  domainName: "google.com"
                  zoneContactPostalCode: ""
                  administrativeContactFaxExt: ""
                  technicalContactCountry: "UNITED STATES"
                  registrarIANAID: "292"
                  updated: "2011-07-20 00:00:00 UTC"
                  administrativeContactStreet:
                    - "1600 amphitheatre parkway"
                  billingContactEmail: ""
                  status:
                    - "clientDeleteProhibited"
                    - "clientTransferProhibited"
                    - "clientUpdateProhibited"
                    - "serverDeleteProhibited"
                    - "serverTransferProhibited"
                    - "serverUpdateProhibited"
                  registrantCity: "Mountain View"
                  billingContactCountry: ""
                  expires: "2020-09-14 00:00:00 UTC"
                  technicalContactStreet:
                    - "2400 e. bayshore pkwy"
                  registrantOrganization: "Google Inc."
                  billingContactStreet: []
                  registrarName: "MARKMONITOR INC."
                  registrantPostalCode: "94043"
                  zoneContactTelephone: ""
                  registrantEmail: "dns-admin@google.com"
                  technicalContactFaxExt: ""
                  technicalContactOrganization: "Google Inc."
                  emails:
                    - "dns-admin@google.com"
                  registrantStreet:
                    - "please contact contact-admin@google.com"
                    - "1600 amphitheatre parkway"
                  technicalContactTelephone: "16503300100"
                  technicalContactState: "CA"
                  technicalContactCity: "Mountain View"
                  registrantFax: "16506188571"
                  registrantCountry: "UNITED STATES"
                  billingContactFaxExt: ""
                  timestamp: 0
                  zoneContactOrganization: ""
                  administrativeContactCountry: "UNITED STATES"
                  billingContactName: ""
                  registrantState: "CA"
                  registrantTelephone: "16502530000"
                  administrativeContactState: "CA"
                  registrantFaxExt: ""
                  technicalContactPostalCode: "94043"
                  rawBase64: ""
                  zoneContctTelephoneExt: ""
                  administrativeContactOrganization: "Google Inc."
                  billingContactTelephone: ""
                  billingContactTelephoneExt: ""
                  zoneContactState: ""
                  administrativeContactTelephone: "16506234000"
                  billingContactOrganization: ""
                  technicalContactName: "DNS Admin"
                  administrativeContactPostalCode: "94043"
                  zoneContactCountry: ""
                  billingContactState: ""
        '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'

  '/whois/{domain}/history':
    get:
      summary: Get WHOIS History for Domain
      operationId: getWhoisHistory
      tags:
        - WHOIS Information for a Domain
      description: |
        Returns a standard WHOIS response record for a single domain with available historical
        WHOIS data returned in an object. The information displayed varies by registrant.
        The limit for history defaults to 10. You can set another value with the `limit` query parameter.
      parameters:
      - name: domain
        in: path
        required: true
        description: Domain name without wildcards and including top-level domain (TLD).
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WhoisDomain'
        '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'

  '/whois/nameservers/{nameserver}':
    get:
      summary: Get WHOIS Information for Nameserver
      operationId: getWhoisNameserver
      tags:
        - WHOIS Information for a Domain
      description: |-
        Get WHOIS information for the nameserver.
        As a nameserver can potentially register hundreds or thousands of domains,
        the server limits the number of results to 500.
      parameters:
      - name: nameserver
        in: path
        required: true
        description: The nameserver's domain name.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: |-
          Specify the number of records to return from the collection.
          The default limit is 500.
        schema:
          type: integer
          default: 500
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortFieldParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalResults:
                    type: integer
                  moreDataAvailable:
                    type: boolean
                  limit:
                    type: integer
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhoisEmailsAndNameservers'
              example:
                ns2.google.com:
                totalResults: 500
                moreDataAvailable: true
                limit: 500
                domains:
                  - domain: "46645.biz"
                    current: true
                  - domain: "800google411.net"
                    current: true
                  - domain: "zagatnyc.com"
                    current: true
                  - domain: "zavers.com"
                    current: true
        '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'

  '/whois/nameservers':
    get:
      summary: Get WHOIS Information for Nameservers
      operationId: getWhoisNameservers
      tags:
        - WHOIS Information for a Domain
      description: |-
        Get WHOIS information for nameservers. To search by multiple nameservers, provide
        a comma-delimited list of domain name in the `nameServerList` query parameter.
        For example: 'ns1.google.com,ns2.google.com'.
      parameters:
      - name: nameServerList
        in: query
        required: true
        description: Nameserver's domain name.
        schema:
          type: array
          items:
            type: string
        example:
        - ns1.google.com
        - ns2.google.com
      - name: limit
        in: query
        required: false
        description: Specify the number of records to return from the collection. Default value is 500.
        schema:
          type: integer
          default: 500
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortFieldParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalResults:
                    type: integer
                  moreDataAvailable:
                    type: boolean
                  limit:
                    type: integer
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhoisEmailsAndNameservers'
              example:
                ns1.google.com:
                  totalResults: 500
                  moreDataAvailable: true
                  limit: 500
                  domains:
                    - domain: "46645.biz"
                      current: true
                    - domain: "800google411.net"
                      current: true
                    - domain: "zagatnyc.com"
                      current: true
                    - domain: "zavers.com"
                      current: true
        '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'

  '/whois/emails/{email}':
    get:
      summary: Get WHOIS Email Information
      operationId: getWhoisEmail
      tags:
        - WHOIS Information for a Domain
      description: |-
        Returns the email address or addresses
        of the registrar for the domain or domains that are looked up. The results include
        the total number of results for domains
        registered by this email address and a list of the first 500 (by default) domains
        associated with this email.
        You can pivot on the email address to find other malicious domains registered
        by the same email.
        This endpoint is limited to a maximum of 500 results, which are the first 500 gathered from the database.
        Reduce the number of results by setting the `limit` query parameter.
        Note: Several of the samples have been truncated due to length.
      parameters:
      - name: email
        in: path
        required: true
        description: Email address following RFC5322 conventions.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: |-
          Specify the number of records to return from the collection.
          The default value is 500.
        schema:
          type: integer
          default: 500
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortFieldParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalResults:
                    type: integer
                    description: Total number of results for this email.
                  offset:
                    type: integer
                  moreDataAvailable:
                    type: boolean
                    description: Determines if there are more than 500 results for this email.
                  limit:
                    type: integer
                    description: |-
                      The total number of results for this page of results. The default
                      limit is 500.
                  sortField:
                    type: string
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhoisEmailsAndNameservers'
                    description: |-
                      Domains registered by this email and if the domain is currently registered
                      by this email address.
              example:
                dns-admin@google.com:
                totalResults: 500
                moreDataAvailable: true
                limit: 500
                domains:
                  - domain: "0emm.com"
                    current: true
                  - domain: "10tothe100.net"
                    current: true
                  - domain: "youtubube.com"
                    current: true
                  - domain: "zagat.net"
                    current: true
                  - domain: "zagatnyc.com"
                    current: true
                  - domain: "zavers.com"
                    current: true
        '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'

  '/whois/search/{searchField}/{regexExpression}':
    get:
      summary: Get WHOIS Information Search
      operationId: getWhoisSearch
      tags:
        - WHOIS Information for a Domain
      description: |
        Performs a regular expression (RegEx) search on the WHOIS data (domain, nameserver, and email fields)
        that was 'updated' or 'created' in the specified time range.
        Returns a list of ten WHOIS records that match the specified RegEx expression.
        Use the offset query parameter to paginate the collection.
        By default, Umbrella sorts by the `updated` field.
      parameters:
      - name: searchField
        in: path
        required: true
        description: |-
          Specifies the field name to use in the RegEx search.
          Valid field names: `domain`, `nameserver`, and `email`.
        schema:
          type: string
      - name: regexExpression
        in: path
        required: true
        description: A standard RegEx pattern search
        schema:
          type: string
      - name: start
        in: query
        required: true
        description: |-
          Specifies a relative or absolute start time. If specifying an absolute time,
          use an epoch time (Unix time) millisecond timestamp within the last 30 days as the Start.
          If specifying a relative time, use either seconds, minutes, hours, days
          or weeks with a minus sign in front.
          As an example, -1days, -1000minutes, or -2weeks are all valid.
          However these timestamps cannot be combined. Only use one of the relative time
          enumerators per query.
        schema:
          type: string
      - name: stop
        in: query
        required: false
        description: Specifies the exclusive end time in milliseconds or a relative time ('now', '-2days').
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortFieldParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalResults:
                    type: integer
                    description: Total number of results for this search.
                  offset:
                    type: integer
                  moreDataAvailable:
                    type: boolean
                    description: Determines if there are more than 10 results for this search.
                  limit:
                    type: integer
                    description: Total number of results for this page. Default limit is 10.
                  sortField:
                    type: string
                  records:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhoisDomain'
              example:
                totalResults: 500
                offset: 0
                moreDataAvailable: true
                limit: 10
                sortField: "updated"
                records: []
        '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'

  '/search/{expression}':
    get:
      summary: Get Domains by Search
      operationId: getSearch
      tags:
        - Search Domain
      description: List newly seen domains that match a regular expression pattern.
      parameters:
      - name: expression
        in: path
        required: true
        description: A standard regular expression pattern search.
        schema:
          type: string
      - name: start
        in: query
        required: true
        description: |-
          Specifies a relative or absolute start time. If specifying an absolute time,
          use an epoch time (Unix time) millisecond timestamp within the last 30 days.
          If specifying a relative time, use either seconds, minutes, hours, days
          or weeks with a minus sign in front.
          As an example, -1days, -1000minutes, or -2weeks are all valid.
          However these timestamps cannot be combined. Only use one of the relative time enumerators per query.
        schema:
          type: string
      - name: stop
        in: query
        required: false
        description: Specifies the exclusive end time in milliseconds or a relative time ('now', '-2days').
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: includeCategory
        in: query
        required: false
        description: |
          Enables or disables the inclusion of security categories in the response.
          The default value is false.
        schema:
          type: boolean
      - name: type
        in: query
        required: false
        description: |
          Specifies the search database node type.
          Valid values are: URL, IP, or HOST.
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  expression:
                    type: string
                    description: Specifies the regular expression used in the search.
                  totalResults:
                    type: integer
                    description: Total number of results for this search.
                  moreDataAvailable:
                    type: boolean
                    description: Determines if there are more results for this search.
                  limit:
                    type: integer
                    description: Total number of results for this page.
                  matches:
                    type: array
                    items:
                      $ref: '#/components/schemas/MatchRecord'
              example:
                expression: "exa[a-z]ple.com"
                totalResults: 1
                moreDataAvailable: false
                limit: 1000
                matches:
                - name: example
                  firstSeen: 1432330927421
                  firstSeenISO: 2015-05-22T21:42:07.421Z
                  securityCategories:
                    - Botnet
        '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'

  '/topmillion':
    get:
      summary: Get Top Most Seen Domains
      operationId: getTopmillion
      tags:
        - Umbrella Popularity List-Top Million Domains
      description: |
        List the most seen domains in Umbrella. You can download the data in a zip file,
        or use the Investigate API to stream the data into a SIEM.
        The popularity list contains our most queried domains based on passive DNS usage across
        our Umbrella global network of more than 180 billion requests per day with many tens of millions
        of unique active users, in more than 165 countries.
        The metric does not only consist of browser-based http requests from users but also takes
        in to account the number of unique client IPs invoking this domain relative to the sum of all requests
        to all domains.
        Our popularity ranking reflects the domain's relative internet activity agnostic
        to the invocation protocols and applications where as site ranking models (such as Alexa) focus
        on the web activity over port 80 (primarily from browsers).
        In addition, the Umbrella popularity algorithm also applies data normalization techniques
        to smooth potential biases that may occur due to sampling of DNS usage data.
      parameters:
      - name: limit
        in: query
        required: false
        description: |-
          The maximum number of domains to return in the list.
          If you do not set a limit, Umbrella returns up to one million results.
        schema:
          type: integer
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
                - "google.com"
                - "netflix.com"
                - "api-global.netflix.com"
                - "microsoft.com"
                - "www.google.com"
                - "facebook.com"
                - "doubleclick.net"
                - "g.doubleclick.net"
                - "googleads.g.doubleclick.net"
                - "hola.org"
        '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'

  '/samples/{destination}':
    get:
      summary: Get Samples for Domain, IP, or URL
      operationId: getSamplesDestination
      tags:
        #- Threat Grid Integration—Cisco AMP Threat Grid
        - Cisco Secure Malware Analytics Integration
      description: |
        Specify a domain, IP, or URL. Use the destination to search for all samples
        associated with the destination. The default number of items in a response is 10. You can extend the limit.
        You must have a license for Cisco Secure Malware Analytics to receive the samples data.

        Cisco Secure Malware Analytics retains checksum samples for one year.
        You may find that Umbrella Investigate previously listed a sample related
        to a destination. If Cisco Secure Malware Analytics no longer contains a sample
        related to the destination, Investigate does not display the sample in the list
        of associated samples.

        An error may occur when the requested destination is not in a valid format,
        if the requested host is not found in our database, or if there is no data available
        for the destination that you have requested. CIDR subnets (for example: 10.10.10.0/24) and pattern search is not supported.
      parameters:
      - $ref: '#/components/parameters/destinationParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/sortbyScoreParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Grids'
              example:
                - query: "google.com"
                  totalResults: 10
                  moreDataAvailable: true
                  limit: 10
                  offset: 0
                  samples:
                    - sha256: "e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd"
                      sha1: "de182fdcc3c0d473b90a0df0ad14c2074d1e7c50"
                      md5: "282f80e8a2cf9e0e0dd72093787d99c6"
                      magicType: "PE32 executable (GUI) Intel 80386, for MS Windows"
                      threatScore: 100
                      size: 192512
                      firstSeen: "1460108539000"
                      lastSeen: "1460108539000"
                      visible: true
                      avresults:
                        - signature: "Win.Trojan.Ramnit"
                          product: "ClamAV"
                        - signature: "Win.Trojan.Parite"
                          product: "ClamAV"
        '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'

  '/sample/{hash}':
    get:
      summary: Get Samples for Hash
      operationId: getSampleHash
      tags:
        #- Threat Grid Integration—Cisco AMP Threat Grid
        - Cisco Secure Malware Analytics Integration
      description: |
        Gather the information from the /samples endpoint, then pivot using the checksums
        of the samples revealed in your initial query.
        This pivot can reveal large chunks of new data about the malware being researched.
        Returns a variety of data as nested JSON arrays.
        The initial results array contains the information about the original sample.
        These results are described first and are, in effect, the samples of the sample.
      parameters:
      - name: hash
        in: path
        required: true
        description: |-
          The specific hash that you want to research,
          for example, `3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea`.
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
              example:
                sha256: "e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd"
                sha1: "de182fdcc3c0d473b90a0df0ad14c2074d1e7c50"
                md5: "282f80e8a2cf9e0e0dd72093787d99c6"
                magicType: "PE32 executable (GUI) Intel 80386, for MS Windows"
                threatScore: 100
                size: 192512
                firstSeen: "1460108539000"
                lastSeen: "1460108539000"
                visible: true
                avresults:
                  - signature: "Win.Trojan.Ramnit"
                    product: "ClamAV"
                  - signature: "Win.Trojan.Parite"
                    product: "ClamAV"
        '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'

  '/sample/{hash}/artifacts':
    get:
      summary: Get Samples for Hash Artifacts
      operationId: getSampleHashArtifacts
      tags:
        #- Threat Grid Integration—Cisco AMP Threat Grid
        - Cisco Secure Malware Analytics Integration
      description: |-
        Other samples associated with this sample. The sample data does not include a threatScore.
        Artifacts are only available for Cisco Secure Malware Analytics customers.
      parameters:
      - name: hash
        in: path
        required: true
        description: |-
          Specify the hash that you want to research,
          for example, `3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea`.
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleHashSamples'
              example:
                totalResults: 10
                moreDataAvailable: true
                limit: 100
                offset: 0
                artifacts:
                  - sha256: "fd6c69c345f1e32924f0a5bb7393e191b393a78d58e2c6413b03ced7482f2320"
                    sha1: "b4fa74a6f4dab3a7ba702b6c8c129f889db32ca6"
                    md5: "ff5e1f27193ce51eec318714ef038bef"
                    magicType: "PE32 executable (GUI) Intel 80386, for MS Windows, UPX compressed"
                    size: 56320
                    firstSeen: "1460108539000"
                    lastSeen: "1460108539000"
                    visible: false
                    avresults: []
                samples: []
        '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'

  '/sample/{hash}/connections':
    get:
      summary: Get Samples for Hash Connections
      operationId: getSampleHashConnections
      tags:
        #- Threat Grid Integration—Cisco AMP Threat Grid
        - Cisco Secure Malware Analytics Integration
      description: |-
        Information about network activity associated with this sample,
        such as connections to other domains or IPs.
      parameters:
      - name: hash
        in: path
        required: true
        description: |-
          Specific hash that you want to research,
          for example, `3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea`.
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleHashConnections'
              example:
                totalResults: 2
                moreDataAvailable: true
                limit: 2
                offset: 0
                connections:
                - name: "google.com"
                  firstSeen: 1456268452000
                  lastSeen: 1456268452000
                  securityCategories: []
                  attacks: []
                  threatTypes: []
                  type: "HOST"
                  ips:
                    - "172.217.1.78"
                  urls:
                    - "http://goo.gl/PDIfV"
                - name: "rtvwerjyuver.com"
                  firstSeen: 1456268452000
                  lastSeen: 1456268452000
                  securityCategories:
                      - "Botnet"
                      - "Malware"
                  attacks: []
                  threatTypes: []
                  type: "HOST"
                  ips: []
                  urls: []
        '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'

  '/sample/{hash}/behaviors':
    get:
      summary: Get Samples for Hash Behaviors
      operationId: getSampleHashBehaviors
      tags:
        #- Threat Grid Integration—Cisco AMP Threat Grid
        - Cisco Secure Malware Analytics Integration
      description: |-
        Information about specific actions or unique properties of this sample,
        especially local to your network or the computer the sample is run on.
      parameters:
      - name: hash
        in: path
        required: true
        description: |-
          The specific hash that you want to research,
          for example, `3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea`.
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleHashBehaviors'
              example:
                totalResults: 2
                moreDataAvailable: true
                limit: 2
                offset: 0
                behaviors:
                  - name: pe-packed-upx
                    title: Executable Packed with UPX
                    hits: 2
                    confidence: 30
                    severity: 30
                    tags:
                      - packer
                      - crypter
                      - encoding
                      - PE
                    threat: 9
                    category:
                      - attribute
                  - name: pe-header-timestamp-null
                    title: PE COFF Header Timestamp is Not Set
                    hits: 2
                    confidence: 60
                    severity: 5
                    tags:
                      - file
                      - attributes
                      - anomaly
                      - PE
                    threat: 3
                    category:
                      - attribute
        '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'

  '/timeline/{name}':
    get:
      operationId: getTimeline
      tags:
        - Tagging Timeline
      summary: Get Tagging Timeline for Destination
      description: |
        List the historical tagging timeline for a given IP, domain, or URL.
        Umbrella sorts the timeline items in descending order using the timestamp field.
        Each timeline item includes lists of security category,
        attack, or threat type associated with the destination.
        Use the Tagging Timeline endpoint to verify when Umbrella assigned or removed
        a security category, attack, or threat type.
        If the current timeline item contains the security category, type of attack,
        or threat type not found in the previous timeline item,
        Umbrella updated the current timeline item.
        If the current timeline item does not contain the security category, attack,
        or threat type found in the previous timeline item,
        Umbrella removed the security category, type of attack,
        or threat type.

      parameters:
      - name: name
        in: path
        required: true
        description: An IP, a domain, or an URL
        schema:
          type: string
      responses:
        '200':
          description: Everything worked as expected.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimelineItem'
              example:
                - categories:
                    - "Malware"
                  attacks: []
                  threatTypes: []
                  timestamp: 1561574807853
                - categories: []
                  attacks:
                    - "Trojan"
                  threatTypes: []
                  timestamp: 1559545774604
        '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'

  # sub-domains
  '/subdomains/{domain}':
      get:
        operationId: getSubDomains
        tags:
          - Subdomains for a Domain
        description: |
          Get subdomains of a given domain. If there is no subdomain for the domain,
          Umbrella Investigate returns an empty array.
        summary: Get Subdomains for Domain
        parameters:
        - name: domain
          in: path
          required: true
          description: A domain name.
          schema:
            type: string
          example: cisco.com
        - name: limit
          in: query
          required: false
          description: |-
            The number of records to return in the collection.
            The default limit is 20 records. The maximum number of records is 100.
          example: 50
          schema:
            type: integer
        - name: offsetName
          in: query
          required: false
          description: |-
            Specify the subdomain to filter the collection. For example: https://investigate.api.umbrella.com/subdomains/cisco.com?offsetName=api.cisco.com
            The default value is the target domain.
          schema:
            type: string
          example: api.cisco.com
        responses:
          '200':
            description: Success. Everything worked as expected.
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Subdomains'
                example:
                  - securityCategories: [Cryptomining]
                    firstSeen: 1612088333
                    name: 'api.c3pool.com'
                  - securityCategories: [Cryptomining]
                    firstSeen: 1615427410
                    name: 'asia.c3pool.com'

components:
  parameters:
    offsetParam:
      name: offset
      in: query
      required: false
      description:
        A number that represents an index into the collection.
        By default, the offset is 0 (the first record).
      schema:
        type: integer

    limitParam:
      name: limit
      in: query
      required: false
      description: |-
        The number of items to return from the collection. The default is 10.
        Increase the limit to request a larger set of data.
      schema:
        type: integer
        default: 10

    minFirstSeenParam:
      name: minFirstSeen
      in: query
      required: false
      description: Returns only records with firstSeen >= minFirstSeen.
      schema:
        type: integer
        format: int64
    maxFirstSeenParam:
      name: maxFirstSeen
      in: query
      required: false
      description: Returns only records with firstSeen <= maxFirstSeen.
      schema:
        type: integer
        format: int64
    minLastSeenParam:
      name: minLastSeen
      in: query
      required: false
      description: Returns only records with lastSeen >= minLastSeen.
      schema:
        type: integer
        format: int64
    maxLastSeenParam:
      name: maxLastSeen
      in: query
      required: false
      description: Returns only records with lastSeen <= maxLastSeen.
      schema:
        type: integer
        format: int64
    sortorderParam:
      name: sortorder
      in: query
      required: false
      description: Sort records by ascending (asc) or descending (desc) order. By
        default, the records are returned in descending order.
      schema:
        type: string
        enum:
          - asc
          - desc
        default: desc
    sortbyParam:
      name: sortby
      in: query
      required: false
      description: 'Sort records by one of the following fields: minTtl, maxTtl,
        firstSeen, or lastSeen.'
      schema:
        type: string
        enum:
          - minTtl
          - maxTtl
          - firstSeen
          - lastSeen

    # sortby with score option
    sortbyScoreParam:
      name: sortby
      in: query
      required: false
      description: |-
        Sorts the sample based on optional values, ["first-seen", "last-seen", "score"].
        The default value is score.
      schema:
        type: string
        enum:
          - firstSeen
          - lastSeen
          - score

    sortFieldParam:
      name: sortField
      in: query
      required: false
      description: |-
        Valid values are: 'created', 'updated', 'expires', or 'domainname'.
      schema:
        type: string
    requiredCategoriesParam:
      name: requiredCategories
      in: query
      required: false
      description: |-
        Filter for records with security categories.
        The case-sensitive security category strings are: Drive-by Downloads/Exploits, Mobile Threats,
        Dynamic DNS, High Risk Sites and Locations, Command and Control, Malware, Phishing,
        Newly Seen Domains, Potentially Harmful,
        DNS Tunneling VPN, and Cryptomining. Use commas to separate multiple security category strings.
      schema:
        type: string
    sortCategoriesParam:
      name: sortCategories
      in: query
      required: false
      description: |-
        Comma-separated list of security categories or 'All'. 'All' stands for all security categories.
        Records which have at least one of these security categories will be first in the ordering.
        The rest of the sorting parameters are applied within the records with and without any of
        the security categories.
      schema:
        type: string

    recordTypeParam:
      name: recordType
      in: query
      required: false
      description: |-
          The type of records. For example: 'A', 'CNAME', 'NS', 'MX'.
          Use commas to separate multiple types of record.
      schema:
        type: string

    includeFeaturesParam:
      name: includefeatures
      in: query
      required: false
      description: Specify 'true' to add feature sections to the response. The default value is 'false'.
      schema:
        type: boolean

    domainParam:
      name: domain
      in: path
      required: true
      description: A domain name. For example, 'cisco.com'.
      schema:
        type: string

    destinationParam:
      name: destination
      in: path
      required: true
      description: A domain, IP, or URL. For example, 'cisco.com', 195.22.28.196, or 'https://cisco.com'.
      schema:
        type: string

    limitRecordsParam:
      name: limit
      in: query
      required: false
      description: |
        The number of records to return in the collection.
        The default limit is 500 records. The maximum number of records
        returned for all requests to the endpoint is 10,000.
      schema:
        type: integer

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  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
  schemas:
    TimelineItem:
      type: object
      properties:
        categories:
          type: array
          items:
            type: string
          description: |-
            Security categories are tagged on this domain, ip or url at this timestamp.
            If none, returns an empty array.
        attacks:
          type: array
          items:
            type: string
          description: |-
            Threats are tagged on this domain, ip or url at this timestamp.
            If none, returns an empty array.
        threatTypes:
          type: array
          items:
            type: string
          description: |-
            Threat types are tagged on this domain, ip or url at this timestamp.
            If none, returns an empty array.
        timestamp:
          type: integer
          description: |-
            Timestamp of occurrence

    Subdomains:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: The name of the subdomain.
          securityCategories:
            type: array
            items:
              type: string
              description: |-
                The list of security categories that are tagged on this subdomain.
                Umbrella returns an empty array if no security categories match the subdomain.
          firstSeen:
            type: integer
            format: int64
            description: |-
              The first time Umbrella related the domain for the resource record.
              The date and time is specified in milliseconds elapsed since the epoch (Unix time).
            example: 1615427410

    DomainCategorization:
      type: object
      properties:
        status:
          type: integer
          format: int64
          description: |-
            * If the domain is considered malicious, the status returned is `-1`.
            * If the domain is considered benign, the status returned is `1`.
            * If the domain is unclassified, the status returned is 0.
        security_categories:
          type: array
          items:
            $ref: '#/components/schemas/SecurityCategory'
          description: |-
            The Umbrella security categories that match this domain.
            If the domain does not match any security categories, the server returns an empty list.
        content_categories:
          type: array
          items:
            $ref: '#/components/schemas/ContentCategory'
          description: |-
            The Umbrella content categories that match this domain.
            If the domain does not match any content categories, the server returns an empty list.
    SecurityCategory:
      properties:
        category:
          type: string
    ContentCategory:
      properties:
        category:
          type: string
      description: The Umbrella content categories, if any, that match the domain.
    Record:
      properties:
        minTtl:
          type: integer
          format: int64
          description: The minimum TTL for the record in seconds.
        maxTtl:
          type: integer
          format: int64
          description: The maximum TTL for the record in seconds.
        firstSeen:
          type: integer
          format: int64
          description: |-
            The first time Umbrella related the domain for the resource record, specified
            in Unix Epoch time.
        lastSeen:
          type: integer
          format: int64
          description: |-
            The last time Umbrella related the domain for the resource record, specified
            in Unix Epoch time.
        name:
          type: string
          description: The name of the query.
        type:
          type: string
          description: |-
            The DNS record type. For example: A, CNAME, NS, MX.
        securityCategories:
          type: array
          items:
            type: string
          description: The Umbrella security categories, if any, that match the domain.
        contentCategories:
          type: array
          items:
            type: string
          description: The Umbrella content categories, if any, that match the domain.
        firstSeenISO:
          type: string
          description: |-
            The first time Umbrella related the domain for the resource record,
            specified in ISO date and time format.
        lastSeenISO:
          type: string
          description: |-
            The last time Umbrella related the domain for the resource record,
            specified in ISO date and time format.
    Avresult:
      properties:
        signature:
          type: string
        product:
          type: string
    Sample:
      properties:
        sha256:
          type: string
        sha1:
          type: string
        md5:
          type: string
        magictype:
          type: string
        threatscore:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        firstSeen:
          type: string
        lastSeen:
          type: string
        visible:
          type: boolean
        avresults:
          type: array
          items:
            $ref: '#/components/schemas/Avresult'
    Connection:
      properties:
        name:
          type: string
        firstSeen:
          type: integer
          format: int64
        lastSeen:
          type: integer
          format: int64
        securityCategories:
          type: array
          items:
            type: string
        attacks:
          type: array
          items:
            type: string
        threatTypes:
          type: array
          items:
            type: string
        type:
          type: string
        ips:
          type: array
          items:
            type: string
        urls:
          type: array
          items:
            type: string
    Behavior:
      properties:
        name:
          type: string
        title:
          type: string
        hits:
          type: integer
          format: int64
        confidence:
          type: integer
          format: int64
        severity:
          type: integer
          format: int64
        tags:
          type: array
          items:
            type: string
        threat:
          type: integer
          format: int64
        category:
          type: array
          items:
            type: string
    SampleHashSamples:
      properties:
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          type: boolean
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/Sample'
        samples:
          type: array
          items:
            $ref: '#/components/schemas/Grids'
    SampleHashConnections:
      properties:
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          type: boolean
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        connections:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
    SampleHashBehaviors:
      properties:
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          type: boolean
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        behaviors:
          type: array
          items:
            $ref: '#/components/schemas/Behavior'
    Grid:
      properties:
        query:
          type: string
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          type: boolean
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        samples:
          type: array
          items:
            $ref: '#/components/schemas/Sample'
    Records:
      type: array
      items:
        $ref: '#/components/schemas/Record'
    Grids:
      type: array
      items:
        $ref: '#/components/schemas/Grid'
    RiskScore:
      type: object
      properties:
        indicators:
          type: array
          items:
            properties:
              indicator:
                type: string
              normalized_score:
                type: integer
              score:
                type: number
                format: float
            description: |-
              Array of [indicator, normalized_score, score] tuples. Each element is a behavioral
              or lexical feature that contributes to the calculation of the risk score.
              The values of normalized_score range between 0 and 100,
              while score is the raw outcome from the statistical algorithms.
        risk_score:
          type: number
          format: float
          description: risk score
    WhoisEmailsAndNameservers:
      type: object
      properties:
        domain:
          type: string
        current:
          type: boolean
    WhoisDomain:
      type: object
      description: A standard WHOIS response record for a single domain.
      properties:
        administrativeContactFax:
          type: string
        whoisServers:
          type: string
        addresses:
          type: array
          items:
            type: string
        administrativeContactName:
          type: string
        zoneContactEmail:
          type: string
        billingContactFax:
          type: string
        administrativeContactTelephoneExt:
          type: string
        administrativeContactEmail:
          type: string
        technicalContactEmail:
          type: string
        technicalContactFax:
          type: string
        nameServers:
          type: array
          items:
            type: string
        zoneContactName:
          type: string
        billingContactPostalCode:
          type: string
        zoneContactFax:
          type: string
        registrantTelephoneExt:
          type: string
        zoneContactFaxExt:
          type: string
        technicalContactTelephoneExt:
          type: string
        billingContactCity:
          type: string
        zoneContactStreet:
          type: array
          items:
            type: string
        created:
          type: string
        administrativeContactCity:
          type: string
        registrantName:
          type: string
        zoneContactCity:
          type: string
        domainName:
          type: string
        zoneContactPostalCode:
          type: string
        administrativeContactFaxExt:
          type: string
        technicalContactCountry:
          type: string
        registrarIANAID:
          type: string
        updated:
          type: string
        administrativeContactStreet:
          type: array
          items:
            type: string
        billingContactEmail:
          type: string
        status:
          type: array
          items:
            type: string
        registrantCity:
          type: string
        billingContactCountry:
          type: string
        expires:
          type: string
        technicalContactStreet:
          type: array
          items:
            type: string
        registrantOrganization:
          type: string
        billingContactStreet:
          type: array
          items:
            type: string
        registrarName:
          type: string
        registrantPostalCode:
          type: string
        zoneContactTelephone:
          type: string
        registrantEmail:
          type: string
        technicalContactFaxExt:
          type: string
        technicalContactOrganization:
          type: string
        emails:
          type: array
          items:
            type: string
        registrantStreet:
          type: array
          items:
            type: string
        technicalContactTelephone:
          type: string
        technicalContactState:
          type: string
        technicalContactCity:
          type: string
        registrantFax:
          type: string
        registrantCountry:
          type: string
        billingContactFaxExt:
          type: string
        timestamp:
          type: integer
        zoneContactOrganization:
          type: string
        administrativeContactCountry:
          type: string
        billingContactName:
          type: string
        registrantState:
          type: string
        registrantTelephone:
          type: string
        administrativeContactState:
          type: string
        registrantFaxExt:
          type: string
        technicalContactPostalCode:
          type: string
        zoneContactTelephoneExt:
          type: string
        administrativeContactOrganization:
          type: string
        billingContactTelephone:
          type: string
        billingContactTelephoneExt:
          type: string
        zoneContactState:
          type: string
        administrativeContactTelephone:
          type: string
        billingContactOrganization:
          type: string
        technicalContactName:
          type: string
        administrativeContactPostalCode:
          type: string
        zoneContactCountry:
          type: string
        billingContactState:
          type: string
        auditUpdatedDate:
          type: string
    MatchRecord:
      properties:
        firstSeen:
          type: integer
          format: int64
          description: |-
            The first time Umbrella related the domain for the resource record,
            specified in Unix Epoch time.
        name:
          type: string
          description: The name of the query.
        securityCategories:
          type: array
          items:
            type: string
          description: The Umbrella security categories that match the domain.
        firstSeenISO:
          type: string
          description: |-
            The first time Umbrella related the domain for the resource record,
            specified in ISO date and time format.
      example:
        expression: "exa[a-z]ple.com"
        totalResults: 1
        moreDataAvailable: false
        limit: 1000
        matches:
          - name: example
            firstSeen: 1432330927421
            firstSeenISO: 2015-05-22T21:42:07.421Z
            securityCategories:
              - Botnet
