Cisco Umbrella Cisco Secure Malware Analytics Integration API

openapi: 3.2.0
info:
  title: Cisco Umbrella Investigate Cisco Secure Malware Analytics Integration API
  description: 'The Umbrella Investigate API provides a complete view of domains in relation to IP and autonomous system number (ASN) information.

    You can get the following domain information:


    * Domain status, risk score, and geolocation

    * Number of domain searches

    * Co-occurring domains

    * Subdomains of a domain

    * Tagged timeline of a domain, IP, or URL

    * Security reputation of a domain

    * Top accessed domains

    * WHOIS information for the domain

    * Threat intelligence data for domains, IPs, and URLs

    * Threat intelligence samples by file hash'
  version: 2.0.0
  contact:
    name: Cloud Security Developer Community
  x-provenance:
    method: harvested
    authored_by: Cisco Umbrella
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously. Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
  - type: source
    url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
  variables:
    basePath:
      default: investigate/v2
security:
- oauthFlow: []
tags:
- name: Cisco Secure Malware Analytics Integration
paths:
  /samples/{destination}:
    get:
      summary: Get Samples for Domain, IP, or URL
      operationId: getSamplesDestination
      tags:
      - 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 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'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          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:
      - 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:
      - $ref: '#/components/parameters/hash'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          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:
      - Cisco Secure Malware Analytics Integration
      description: 'Other samples associated with this sample. The sample data does not include a threat score.

        Artifacts are only available for Cisco Secure Malware Analytics customers.'
      parameters:
      - $ref: '#/components/parameters/hash'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          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:
                  - signature: Win.Trojan.Ramnit
                    product: ClamAV
                  - signature: Win.Trojan.Parite
                    product: ClamAV
                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:
      - Cisco Secure Malware Analytics Integration
      description: Information about network activity associated with this sample, such as connections to other domains or IPs.
      parameters:
      - $ref: '#/components/parameters/hash'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          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:
                  - Botnet
                  - Malware
                  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:
      - Cisco Secure Malware Analytics Integration
      description: 'Get the information about specific actions or unique properties of this sample,

        especially local to your network or the computer where the sample is run.'
      parameters:
      - $ref: '#/components/parameters/hash'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      security:
      - oauthFlow:
        - investigate.investigate:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          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'
components:
  schemas:
    SampleHashSamples:
      type: object
      description: The hash sample information and list of hash samples.
      properties:
        totalresults:
          type: integer
          description: The total number of samples.
          format: int64
          example: 100000
        moreDataAvailable:
          $ref: '#/components/schemas/moreDataAvailable'
        limit:
          $ref: '#/components/schemas/limit'
        offset:
          $ref: '#/components/schemas/offset'
        artifacts:
          type: array
          description: The list of samples.
          items:
            $ref: '#/components/schemas/Sample'
        samples:
          type: array
          description: The list of all samples associated with the destination and related sample information.
          items:
            $ref: '#/components/schemas/Grids'
    moreDataAvailable:
      type: boolean
      description: Specifies whether more samples are available for the destination.
      example: true
    Grids:
      type: array
      description: The list of all samples associated with the destination.
      items:
        $ref: '#/components/schemas/Grid'
      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
    limit:
      type: integer
      description: The maximum number of records to include in the response.
      format: int64
      example: 100
    Grid:
      type: object
      description: The samples and information associated with the destination.
      properties:
        query:
          type: string
          description: The domain, IP, or URL.
          example: google.com
        totalresults:
          type: integer
          description: The number of total results.
          format: int64
          example: 10
        moreDataAvailable:
          $ref: '#/components/schemas/moreDataAvailable'
        limit:
          $ref: '#/components/schemas/limit'
        offset:
          $ref: '#/components/schemas/offset'
        samples:
          type: array
          description: The list of hash samples and information for the destination.
          items:
            $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.Parit
              product: ClamAV
      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.Parit
            product: ClamAV
    Sample:
      type: object
      description: The information about the hash sample.
      properties:
        sha256:
          type: string
          description: The sha256 hash string.
          example: e9d3470c37dada28d5a32fb53a243c5b20def35bb01abf8f5403182cc2b91fdd
        sha1:
          type: string
          description: The sha1 hash string.
          example: de182fdcc3c0d473b90a0df0ad14c2074d1e7c50
        md5:
          type: string
          description: The md5 hash string.
          example: 282f80e8a2cf9e0e0dd72093787d99c6
        magictype:
          type: string
        threatscore:
          type: integer
          format: int64
          description: The threat score assigned to the sample.
          example: 100
        size:
          type: integer
          format: int64
          description: The size of the sample.
          example: 19251
        firstSeen:
          $ref: '#/components/schemas/firstSeen'
        lastSeen:
          $ref: '#/components/schemas/lastSeen'
        visible:
          type: boolean
          description: Specifies whether the threat is visible.
          example: false
        avresults:
          type: array
          description: The list of antivirus results.
          items:
            $ref: '#/components/schemas/Avresult'
      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.Parit
          product: ClamAV
    lastSeen:
      type: integer
      format: int64
      description: 'The last time Umbrella related the domain for the resource record, specified

        in Unix Epoch time.'
      example: 1615427410
    SampleHashConnections:
      type: object
      description: The properties of the sample hash connections.
      properties:
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          $ref: '#/components/schemas/moreDataAvailable'
        limit:
          $ref: '#/components/schemas/limit'
        offset:
          $ref: '#/components/schemas/offset'
        connections:
          type: array
          description: The list of connection information.
          items:
            $ref: '#/components/schemas/Connection'
    Behavior:
      type: object
      description: The properties of the 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
    firstSeen:
      type: integer
      format: int64
      description: 'The first time Umbrella related the domain for the resource record, specified

        in Unix Epoch time.'
      example: 1615427410
    Avresult:
      type: object
      description: The information about the antivirus result.
      properties:
        signature:
          type: string
          description: The signature of the antivirus.
        product:
          type: string
          description: The name of the product associated with the antivirus.
      example:
        signature: Win.Trojan.Ramnit
        product: ClamAV
    SampleHashBehaviors:
      type: object
      description: The properties of the sample hash behaviors.
      properties:
        totalresults:
          type: integer
          format: int64
        moreDataAvailable:
          $ref: '#/components/schemas/moreDataAvailable'
        limit:
          $ref: '#/components/schemas/limit'
        offset:
          $ref: '#/components/schemas/offset'
        behaviors:
          type: array
          description: The list of behavioral information related to the destination.
          items:
            $ref: '#/components/schemas/Behavior'
    offset:
      type: integer
      description: The place to start reading in the collection.
      format: int64
      default: 0
      example: 5
    Connection:
      type: object
      description: The properties of the connection.
      properties:
        name:
          type: string
        firstSeen:
          $ref: '#/components/schemas/firstSeen'
        lastSeen:
          $ref: '#/components/schemas/lastSeen'
        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
  headers:
    Date:
      schema:
        type: string
        pattern: ^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
  responses:
    500Error:
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    403Error:
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    401Error:
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    404Error:
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    400Error:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  parameters:
    hash:
      name: hash
      in: path
      required: true
      description: A hash value.
      schema:
        type: string
      example: 3ee3cbe0ca92d2470f50712adf60fb03e4ad327fd78e630e004571b89db47cea
    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
      example: https://cisco.com
    sortbyScoreParam:
      name: sortby
      in: query
      required: false
      description: 'Sort the sample based on optional values: `first-seen`, `last-seen`, or `score`.

        The default value is `score`.'
      schema:
        type: string
        enum:
        - firstSeen
        - lastSeen
        - score
      example: score
    offsetParam:
      name: offset
      in: query
      required: false
      description: A number that represents an index in the collection. By default, the offset is 0 (the first record).
      schema:
        type: integer
        default: 0
      example: 2
    limitParam:
      name: limit
      in: query
      required: false
      description: 'The number of items to return in the response from the collection. The default limit is 10.

        Increase the limit to request a larger set of data.'
      schema:
        type: integer
        default: 10
      example: 25
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: The client credential flow.
      flows:
        clientCredentials:
          scopes:
            investigate.investigate:read: Investigate read access
            investigate.bulk:read: Investigate bulk read access
          tokenUrl: https://api.umbrella.com/auth/v2/token
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/investigate/investigate.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/investigate/investigate.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/