LevelBlue External API documentation version 1

/api/v1

Home

The OTX DirectConnect API allows you to easily synchronize the Threat Intelligence available in OTX to the tools you use to monitor your environment. Using the DirectConnect agents you can integrate with your infrastructure to detect threats targeting your environment. If there is no pre-built agent for the products you are using, leverage the DirectConnect SDK (available in Java and Python) to develop your own integration for the community.

/api/v1/indicators

post

post

Analyze suspicious files to quickly detect malware and malicious activity. When you submit a file, the system will first analyze the file statically and then submit it to our sandbox for dynamic analysis if applicable. You can check the status of your submitted files the submitted_files api.

Unlike most of the endpoints in OTX, this one only takes multipart form data, and the 'name' of the part containing the file should simply be 'file'

Analyze suspicious files to quickly detect malware and malicious activity. When you submit a file, the system will first analyze the file statically and then submit it to our sandbox for dynamic analysis if applicable. You can check the status of your submitted files the submitted_files api.

Unlike most of the endpoints in OTX, this one only takes multipart form data, and the 'name' of the part containing the file should simply be 'file'

Body

Type: multipart/form-data

HTTP status code 200

Body

Type: application/json

get

Returns a list of all submitted files, along with the status of the submission. When complete results can be found at /indicator/file/{file_hash} in your browser, or /api/v1/indicators/file/{file_hash}/{section} in the API

get

post

post

Update the TLP level of previously submitted files. Valid TLPs are white, green, amber and red. You can only update the TLP of a file you submitted yourself, and you can not update the TLP if someone else has submitted the same file

Update the TLP level of previously submitted files. Valid TLPs are white, green, amber and red. You can only update the TLP of a file you submitted yourself, and you can not update the TLP if someone else has submitted the same file

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalParameters": false,
  "required": [
    "urls", "tlp"
  ],
  "parameters": {
    "urls": {"type": "array", "items": {"type": "string"}},
    "tlp": {"type": "string", "enum":  ["white", "green", "amber", "red"]}
  }
}

HTTP status code 200

Body

Type: application/json

post

post

(This is an endpoint to submit a single url at once. To submit in bulk see submit_urls) Analyze suspicious URLs to quickly detect malware and malicious activity. When you submit a URL, the system will automatically visit the URL and analyze the content. If the URL has other artifacts, such as a file in the response, this will be automatically submitted to our system for analysis.

(This is an endpoint to submit a single url at once. To submit in bulk see submit_urls) Analyze suspicious URLs to quickly detect malware and malicious activity. When you submit a URL, the system will automatically visit the URL and analyze the content. If the URL has other artifacts, such as a file in the response, this will be automatically submitted to our system for analysis.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalParameters": false,
  "required": ["url"],
  "parameters": {
    "url": {"type": "string"},
    "tlp": {"type": "string", "enum":  ["white", "green", "amber", "red"]}
  }
}

HTTP status code 200

Body

Type: application/json

post

post

(This is an endpoint to submit multiple urls at once. For a simpler single-url endpoint see submit_url) Analyze suspicious URLs to quickly detect malware and malicious activity. When you submit a URL, the system will automatically visit the URL and analyze the content. If the URL has other artifacts, such as a file in the response, this will be automatically submitted to our system for analysis.

(This is an endpoint to submit multiple urls at once. For a simpler single-url endpoint see submit_url) Analyze suspicious URLs to quickly detect malware and malicious activity. When you submit a URL, the system will automatically visit the URL and analyze the content. If the URL has other artifacts, such as a file in the response, this will be automatically submitted to our system for analysis.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalParameters": false,
  "required": ["url"],
  "parameters": {
    "url": {"type": "string"},
    "tlp": {"type": "string", "enum":  ["white", "green", "amber", "red"]}
  }
}

HTTP status code 200

Body

Type: application/json

get

Returns a list of all submitted URLs, along with the status of the submission. When complete results can be found at /indicator/url/{url}} in your browser, or /api/v1/indicators/url/{url}/{section} in the API

get

post

post

Update the TLP level of previously submitted URLs. Valid TLPs are white, green, amber and red. You can only update the TLP of a URL you submitted yourself, and you can not update the TLP if someone else has submitted the same URL

Update the TLP level of previously submitted URLs. Valid TLPs are white, green, amber and red. You can only update the TLP of a URL you submitted yourself, and you can not update the TLP if someone else has submitted the same URL

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalParameters": false,
  "required": [
    "hashes", "tlp"
  ],
  "parameters": {
    "hashes": {"type": "array", "items": {"type": "string"}},
    "tlp": {"type": "string", "enum":  ["white", "green", "amber", "red"]}
  }
}

HTTP status code 200

Body

Type: application/json

get

Indicator page api for IPv4 Addresses

sections:

  • general: General information about the IP, such as geo data, and a list of the other sections currently available for this IP address.
  • reputation: OTX data on malicious activity observed by LevelBlue Labs (IP Reputation).
  • geo: A more verbose listing of geographic data (Country code, coordinates, etc.)
  • malware: Malware samples analyzed by LevelBlue Labs which have been observed connecting to this IP address.
  • url_list: URLs analyzed by LevelBlue Labs which point to or are somehow associated with this IP address.
  • passive_dns: passive dns information about hostnames/domains observed by LevelBlue Labs pointing to this IP address.
  • http_scans: Meta data for http(s) connections to the IP.

Example: api/v1/indicators/IPv4/8.8.8.8/general

get

URI Parameters

  • ip: required (string)

    Example:

    8.8.8.8
  • section: required (one of general, reputation, geo, malware, url_list, passive_dns)

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for IPv6 Addresses

sections:

  • general: General information about the IP, such as geo data, and a list of the other sections currently available for this IP address.
  • reputation: OTX data on malicious activity observed by LevelBlue Labs (IP Reputation).
  • geo: A more verbose listing of geographic data (Country code, coordinates, etc.)
  • malware: Malware samples analyzed by LevelBlue Labs which have been observed connecting to this IP address.
  • url_list: URLs analyzed by LevelBlue Labs which point to or are somehow associated with this IP address.
  • passive_dns: passive dns information about hostnames/domains observed by LevelBlue Labs pointing to this IP address.

Example: api/v1/indicators/IPv6/2a03:2880:10:1f02:face:b00c::25/general

get

URI Parameters

  • ip: required (string)

    Example:

    2001:4860:4860::8888
  • section: required (one of general, reputation, geo, malware, url_list, passive_dns)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for domain names

Example domains: 'rghost.net', 'spywaresite.info'

sections:

  • general: General information about the domain, including any pulses, and a list of the other sections currently available for this domain.
  • geo: A more verbose listing of geographic data (Country code, coordinates, etc.)
  • malware: Malware samples analyzed by LevelBlue Labs which have been observed connecting to this domain.
  • url_list: URLs analyzed by LevelBlue Labs on this domain.
  • passive_dns: Passive dns records observed by LevelBlue Labs pointing to this domain.
  • whois: Whois records for the domain.
  • http_scans: Meta data for http(s) connections to the domain.

Example: api/v1/indicators/domain/rghost.net/malware

get

URI Parameters

  • domain: required (string)

    Example:

    spywaresite.info
  • section: required (one of general, geo, malware, url_list, passive_dns)

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for hostname names

Example hostnames: 'otx.alienvault.com', 'bad-guys.no-ip.org', 'alpha.beta.google.co.uk'

sections:

  • general: General information about the hostname, including any pulses, and a list of the other sections currently available for this hostname.
  • geo: A more verbose listing of geographic data (Country code, coordinates, etc.)
  • malware: Malware samples analyzed by LevelBlue Labs which have been observed connecting to this hostname.
  • url_list: URLs analyzed by LevelBlue Labs on this hostname.
  • passive_dns: passive dns records observed by LevelBlue Labs pointing to this hostname.
  • http_scans: Meta data for http(s) connections to the hostname.

Example: api/v1/indicators/hostname/mail.vspcord.com/malware

get

URI Parameters

  • hostname: required (string)

    Example:

    mail.vspcord.com
  • section: required (one of general, geo, malware, url_list, passive_dns)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for files (file hashes)

sections:

  • general: General metadata about the file hash, and a list of the other sections currently available for this hash.
  • analysis: dynamic and static analysis of this file (Cuckoo analysis, exiftool, etc.)

Example: api/v1/indicators/file/6c5360d41bd2b14b1565f5b18e5c203cf512e493/analysis

get

URI Parameters

  • file_hash: required (string)

    Example:

    6c5360d41bd2b14b1565f5b18e5c203cf512e493
  • section: required (one of general, analysis)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for URLs

sections:

  • general: Historical geographic info, any pulses this indicator is on, list of the other sections currently available for this URL.
  • url_list: Full results (potentially multiple) from LevelBlue Labs url analysis.

Example: api/v1/indicators/url/http://www.fotoidea.com/sport/4x4_san_ponso/slides/IMG_0068.html/url_list

get

URI Parameters

  • url: required (string)

    Example:

    http://www.fotoidea.com/sport/4x4_san_ponso/slides/IMG_0068.html
  • section: required (one of general, url_list)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for CVEs (MITRE's Common Vulnerability Enumeration)

sections:

  • general: MITRE CVE data (CPEs, CWEs, etc.), any pulses this indicator is on, list of the other sections currently available for this URL.

Example: api/v1/indicators/cve/CVE-2014-0160/general

get

URI Parameters

  • cve: required (string)

    Example:

    CVE-2014-0160
  • section: required (one of general)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for NIDSs

sections:

  • general: General metadata about NIDS

Example: api/v1/indicators/nids/2820184/general

get

URI Parameters

  • nids: required (string)

    Example:

    2820184
  • section: required (one of general)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Indicator page api for Correlation Rules

sections:

  • general: General metadata about the Correlation Rule

Example: api/v1/indicators/correlation-rule/572f8c3c540c6f0161677877/general

get

URI Parameters

  • correlationrule: required (string)

    Example:

    572f8c3c540c6f0161677877
  • section: required (one of general)

    Example:

    general

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

/api/v1/pulses

get patch

View or edit of pulse with id pulse_id. When editing a pulse, use PATCH. Post body should be json format, containing fields you wish to edit. For string, numeric or boolean fields provide the literal value, for list fields provide the list of values you wish to add or remove (see example). Any fields that can be used to create a pulse can also be used to edit.

View Example: /api/v1/pulse/57204e9b3c4c3e015d93cb12

In an edit you can pass any pulse field(s) you wish to change. For string or numeric fields, pass the new value you wish to have. For "list" fields, pass a dictionary that can contain a "add" or "remove" field. For "add", pass a list of new values. For "remove", pass a list of values to remove

Indicators are a special case, you can also incude an "edit" field in the value dictionary.

Please see examples below for details

Edit Example: /api/v1/pulse/57204e9b3c4c3e015d93cb12

body: {
    "description": "New Description",
    "tags": {"add": ["addtag1", "addtag2"], "remove": ["remtag1"]}
}

Edit Example with indicators: /api/v1/pulse/57204e9b3c4c3e015d93cb12

This assumes you already have indicators in the pulse with ids 1, 2, 3 and 4. We edit 3 of them and remove 1. Note that for removing indicators, only the indicator id is necessary. For editing, you need the id and any fields you wish to change.

body: {'indicators': {
    'add': [
        {'indicator': '8.8.8.9', 'type': 'IPv4', 'role': 'command_and_control'},
        {'indicator': '8.8.8.10', 'type': 'IPv4'},
    ],
    'edit': [
        {'id': 1 'type': 'hostname', 'indicator': 'www.amazon.com'},
        {'id': 2, 'indicator': 'you@rustybrooks.com'},
        {'id': 3, 'is_active': True, 'expiration': '2017-01-01', 'role': 'scanning_host'},
    ],
    'remove': [
        {'id': 4},
    ]
}
get
patch

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

Body

Type: application/json

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Returns paginated list view of the indicators inside the pulse pulse_id.

Example: api/v1/pulse/57204e9b3c4c3e015d93cb12/indicators

get

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

Return all pulses that share an indicator with this pulse

get

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

HTTP status code 404

Body

Type: application/json

get

get

Threat intelligence subscriptions

  • All pulses by users you are subscribed to
  • All pulses you are directly subscribed to
  • All pulses you have created yourself
  • All pulses from groups you are a member of
get

get

List the ids of all pulses you are subscribed to.

get

get

Activity feed consists of pulses:

  • All pulse subscriptions (directly subscribed to pulse, and all pulses by subscribed to users)
  • All pulses created by myself
  • All pulses by users I am following
get

post

post

Allow users to submit pulses via the API.

Request Body fields (must be sent in HTTP POST body, json format). Click POST button above for examples and JSON schemas. [Note: group_ids in examples are for demonstration purposes, you must belong to a group to include it in the groups parameter]

Allow users to submit pulses via the API.

Request Body fields (must be sent in HTTP POST body, json format). Click POST button above for examples and JSON schemas. [Note: group_ids in examples are for demonstration purposes, you must belong to a group to include it in the groups parameter]

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": ["name", "public"],
  "properties": {
    "name": {"type": "string"},
    "description": {"type": "string"},
    "public": {"type": "boolean"},
    "tags": {
      "type": "array", "items": {"type": "string"}
    },
    "TLP": {"enum": ["white", "green", "amber", "red"]},
    "references": {
      "type": "array", "items": {"type": "string"}
    },
    "adversary": {"type": "string"},
    "targeted_countries": {
      "type": "array", "items": {"type": "string"}
    },
    "industries": {
      "type": "array", "items": {"type": "string"}
    },
    "group_ids": {
      "type": "array", "items": {"type": "integer"}
    },
    "malware_families": {
      "type": "array", "items": {"type": "string"}
    },
    "attack_ids": {
      "type": "array", "items": {
        "type": "string", "pattern": "^[A-Z][0-9]{4}$"
      }
    },
    "indicators": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["indicator", "type", "description"],
        "properties": {
          "indicator": {"type": "string"},
          "type": {"type": "string"},
          "title": {"type": "string"},
          "description": {"type": "string"},
          "expiration": {"type": "string", "format":  "date-time"},
          "content": {"type": "string"},
          "role": {"type": ["string", "null"], "enum": [
            null, "", "scanning_host", "malware_hosting",
            "command_and_control", "exploit_kit",
            "malvertising", "phishing",
            "bruteforce", "web_attack",
            "exploit_source", "trojan", "rat",
            "backdoor", "adware", "hacking_tool",
            "ransomware", "worm", "macro_malware",
            "domain_owner", "delivery_email",
            "unknown", "file_scanning",
            "memory_scanning", "hunting",
            "pcap_scanning"
          ]}
        }
      }
    }
  }
}

Example:

{
  "references": [
    "https://google.com",
    "https://amazon.com"
  ],
  "indicators": [
    {
      "expiration": "01/01/20",
      "type": "IPv4",
      "indicator": "8.8.8.8",
      "content": "",
      "role": null,
      "title": "",
      "description": ""
    },
    {
      "description": "A longer description can be used if desired",
      "indicator": "rustybrooks.com",
      "title": "It's my website",
      "content": "",
      "role": "scanning_host",
      "expiration": "2019-01-01T00:00:00",
      "type": "domain"
    }
  ],
  "name": "Test Pulse Name",
  "description": "Test Pulse Description",
  "public": true,
  "TLP": "white",
  "tags": ["tag1", "tag2", "tag3"],
  "group_ids": [1, 2, 3],
  "industries": [
    "Industry1",
    "Industry2"
  ],
  "targeted_countries": [
    "Afghanistan",
    "Anguilla"
  ],
  "malware_families": [
    "Backdoor:Linux/Netbus",
    "Backdoor:Linux/Cyrax"
  ],
  "attack_ids": ["T1001", "T1486"],
  "adversary": "APT 1"
}

HTTP status code 201

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "properties": {
    "id": {"type": "string"},
    "revision": {"type": "integer"},
    "author_id": {"type": "integer"},
    "author_name": {"type": "string"},
    "name": {"type": "string"},
    "pulse_name": {"type": "string"},
    "description": {"type": "string"},
    "public": {"type": "boolean"},
    "active": {"type": "boolean"},
    "locked": {"type": "boolean"},
    "tags": {"type": "array", "items": {"type": "string"}},
    "tags_count": {"type": "integer"},
    "TLP": {"type": "string", "enum": ["white", "green", "amber", "red", ""]},
    "references": {"type": "array", "items": {"type": "string"}},
    "adversary": {"type": "string"},
    "targeted_countries": {"type": "array", "items": {"type": "string"}},
    "industries": {"type": "array", "items": {"type": "string"}},
    "malware_families": {
      "type": "array", "items": {"type": "string"}
    },
    "attack_ids": {
      "type": "array", "items": {
        "type": "string", "pattern": "^[A-Z][0-9]{4}$"
      }
    },
    "indicators_count": {"type": "integer"},
    "references_count": {"type": "integer"},
    "extract_source": {"type": "array", "items": {"type": "string"}},
    "subscribers": {"type": "array", "items": {"type": "integer"}},
    "subscribers_count": {"type": "integer"},
    "followers": {"type": "array", "items": {"type": "integer"}},
    "followers_count": {"type": "integer"},
    "unsubscribed_users": {"type": "array", "items": {"type": "integer"}},
    "upvotes": {"type": "array", "items": {"type": "integer"}},
    "downvotes": {"type": "array", "items": {"type": "integer"}},
    "upvotes_count": {"type": "integer"},
    "downvotes_count": {"type": "integer"},
    "votes_count": {"type": "integer"},
    "comments_count": {"type": "integer"},
    "exported_by": {"type": "array", "items": {"type": "integer"}},
    "export_count": {"type": "integer"},
    "pulse_source": {"type": "string", "enum": ["api", "web"]},
    "group_ids": {"type": "array", "items": {"type": "integer"}},
    "validators": {"type": "array", "items": {"type": "string"}},
    "validators_count": {"type": "integer"},
    "cloned_from": {"type": ["null", "string"]},
    "created": {"type": "string"},
    "modified": {"type": "string"},
    "in_group": {"type":  "boolean"},
    "groups": {
      "type": "array",
      "additionalProperties": false,
      "required": ["name", "id"],
      "items": {
        "properties": {
          "name": {"type": "string"},
          "id": {"type": "integer"}
        }
      }
    },
    "indicators": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "indicator", "type", "description", "title", "content",
          "expiration", "role", "access_groups", "access_reason", "access_type"
        ],
        "properties": {
          "indicator": {"type": "string"},
          "type": {"type": "string"},
          "title": {"type": "string"},
          "description": {"type": "string"},
          "expiration": {"type": "string", "format": "date-time"},
          "content": {"type": "string"},
          "role": {
            "type": ["string", "null"],
            "enum": [
              null, "",
              "scanning_host", "malware_hosting", "command_and_control",
              "exploit_kit", "malvertising", "phishing",
              "bruteforce", "web_attack", "exploit_source",
              "trojan", "rat", "backdoor",
              "adware", "hacking_tool", "ransomware",
              "worm", "macro_malware", "domain_owner",
              "delivery_email", "unknown", "file_scanning",
              "memory_scanning", "hunting", "pcap_scanning"
            ]
          },
          "access_groups": {"type": "array", "items": {"type":  "integer"}},
          "access_reason": {"type": "string"},
          "is_active": {"type": "boolean"},
          "access_type": {"type": "string"}
        }
      }
    }
  }
}

Example:

{
    "TLP": "white",
    "active": true,
    "adversary": "APT 1",
    "attack_ids": [],
    "author_id": 16976,
    "author_name": "rbrooks_av",
    "cloned_from": null,
    "comments_count": 0,
    "created": "2019-11-14T20:43:27.994238",
    "description": "Test Pulse Description",
    "downvotes": [],
    "downvotes_count": 0,
    "export_count": 0,
    "exported_by": [],
    "extract_source": [],
    "followers": [],
    "followers_count": 0,
    "group_ids": [1, 2, 3],
    "in_group": true,
    "groups": [
      {"id": 1, "name": "Group 1"},
      {"id": 2, "name": "Group 2"},
      {"id": 3, "name": "Group 3"}
    ],
    "id": "5dcdbc6f9d8108c36bbcbb56",
    "indicators": [
        {
            "access_groups": [],
            "access_reason": "",
            "access_type": "public",
            "content": "",
            "description": "",
            "expiration": "2020-01-01T00:00:00",
            "indicator": "8.8.8.8",
            "is_active": true,
            "role": null,
            "title": "",
            "type": "IPv4"
        },
        {
            "access_groups": [],
            "access_reason": "",
            "access_type": "public",
            "content": "",
            "description": "A longer description can be used if desired",
            "expiration": "2019-01-01T00:00:00+00:00",
            "indicator": "rustybrooks.com",
            "is_active": true,
            "role": "scanning_host",
            "title": "It's my website",
            "type": "domain"
        }
    ],
    "indicators_count": 2,
    "industries": [
        "Industry1",
        "Industry2"
    ],
    "locked": false,
    "malware_families": [
        "Backdoor:Linux/Netbus",
        "Backdoor:Linux/Cyrax"
    ],
    "modified": "2019-11-14T20:43:27.994238",
    "name": "Test Pulse Name",
    "public": true,
    "pulse_name": "Test Pulse Name",
    "pulse_source": "api",
    "references": [
        "https://google.com",
        "https://amazon.com"
    ],
    "references_count": 2,
    "revision": 1,
    "subscribers": [],
    "subscribers_count": 6,
    "tags": [
        "tag1",
        "tag2",
        "tag3"
    ],
    "tags_count": 3,
    "targeted_countries": [
        "Afghanistan",
        "Anguilla"
    ],
    "unsubscribed_users": [],
    "upvotes": [],
    "upvotes_count": 0,
    "validators": [],
    "validators_count": 0,
    "votes_count": 0
}

get

Delete an existing pulse that you had previously created

Example: url: /api/v1/pulses/57204e9b3c4c3e015d93cb12/delete

get

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": ["status"],
  "properties": {
    "status": {"type": "string"}
  } 
}

Example:

{"status": "Pulse removed (id: 5e46ee71665eed2ce67ed4be)"}

HTTP status code 404

Body

Type: application/json

get

Subscribe to pulse. This will cause the pulse to appear in your subscription feed

Example: url: /api/v1/pulses/57204e9b3c4c3e015d93cb12/subscribe

get

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": ["status", "subscriber_count"],
  "properties": {
    "status": {"type": "string", "enum": ["subscribe"]},
    "subscriber_count": {"type":  "integer"}
  }
}

Example:

{"status": "subscribe", "subscriber_count": 2}

HTTP status code 404

Body

Type: application/json

get

Unsubscribe from pulse. If you're subscribed to the pulse already, you will be unsubscribed. If you are subscribed to the author, you will remain subsribed to the author, but this particular pulse will no longer appear in your subscription

Example: url: /api/v1/pulses/57204e9b3c4c3e015d93cb12/unsubscribe

get

URI Parameters

  • pulse_id: required (string)

    Example:

    57204e9b3c4c3e015d93cb12

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": ["status", "subscriber_count"],
  "properties": {
    "status": {"type": "string", "enum": ["unsubscribe"]},
    "subscriber_count": {"type":  "integer"}
  }
}

Example:

{"status": "unsubscribe", "subscriber_count": 2}

HTTP status code 404

Body

Type: application/json

get

Returns string representations of each indicator type (i.e. "domain"), as recognized by OTX.

For use in indicator validation and create pulse.

get

post

Validate an indicator:type pair.

post

Body

Type: application/json

HTTP status code 200

Body

Type: application/json

get

List events, such as subscribe/unsubscribe to user/pulse.

Triggered when certain actions happen on the website. Events may be useful for the purposes of threat intelligence management. Pulse subscribed/unsubscribed User subscribed/unsubscribed * Pulse (in my subscriptions) deleted by author

When a pulse you've previously subscribed to is deleted by the author, it will gone from your subscriptions. Pulse events will help you purge these entries if you're doing incremental updates. Alternatively, you can always refresh your locally stored indicators entirely everytime you update.

Example: /api/v1/pulses/events/?modified_since=2016-04-25T22:49:03.704867&limit=10&page=1

get

get

Returns authenticated users or passed in user created pulse feed, default sorted by latest modified.

get

URI Parameters

  • username: required (string)

    Example:

    LevelBlue

Query Parameters

  • since: (string)

    (optional, iso format datetime (UTC) string) Only include pulses who's modified time is strictly greater than the supplied parameter. Accepts any valid ISO 8601 formatted datetime, with resolution up to and including milliseconds (for example "2017-01-01T12:35:00.123+00:00")

    Example:

    2017-01-01T12:35:00+00:00

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": [
    "count", "results", "next", "previous"
  ],
  "properties": {
    "count": {"type": "integer"},
    "next": {"type": ["string", "null"], "format": "uri"},
    "previous": {"type": ["string", "null"], "format": "uri"},
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id", "name", "created", "modified", "pulse_source", "TLP", "description", "indicator_type_counts",
          "tags", "malware_families", "references", "targeted_countries", "groups", "vote", "adversary", "industries",
          "cloned_from", "attack_ids", "author", "threat_hunter_has_agents", "threat_hunter_scannable", "is_author",
          "locked", "is_subscribing", "is_modified", "in_group", "public", "subscriber_count", "export_count",
          "upvotes_count", "downvotes_count", "votes_count", "validator_count", "comment_count", "indicator_count",
          "follower_count"
        ],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "created": {"type": "string", "format": "date-time"},
          "modified": {"type": "string", "format": "date-time"},
          "pulse_source": {"enum": ["web", "api"]},
          "TLP": {"enum": ["white", "green", "amber", "red"]},
          "description": {"type": "string"},
          "indicator_type_counts": {"type": "object"},
          "tags": {"type": "array", "items": {"type": "string"}},
          "malware_families": {
            "type": "array", "items": {
              "type": "object",
              "required": ["display_name", "id", "target"],
              "additionalProperties": false,
              "properties": {
                "display_name": {"type": "string"},
                "id": {"type": "string"},
                "target": {"type": ["string", "null"]}
              }
            }
          },
          "modified_text":  {"type": "string"},
          "references": {"type": "array", "items": {"type": "string"}},
          "targeted_countries": {"type": "array", "items": {"type": "string"}},
          "groups": {
            "type": "array",
            "items": {
              "additionalProperties": false,
              "required": ["name", "id"],
              "properties": {
                "name": {"type": "string"},
                "id": {"type": "integer"}
              }
            }
          },
          "vote": {"type": "integer"},
          "adversary": {"type": "string"},
          "industries": {"type": "array", "items": {"type": "string"}},
          "cloned_from": {"type": ["null", "string"]},
          "attack_ids": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "display_name", "name"],
              "additionalProperties": false,
              "properties": {
                "id": {"type": "string"},
                "display_name": {"type": "string"},
                "name": {"type": "string"}
              }
            }
          },
          "author": {
            "type": "object",
            "additionalProperties": false,
            "required": ["username", "is_subscribed", "avatar_url", "is_following", "id"],
            "properties": {
              "username": {"type": "string"},
              "is_subscribed": {"type": "boolean"},
              "avatar_url": {"type": "string"},
              "is_following": {"type":  "boolean"},
              "id": {"type": "string"}
            }
          },
          "threat_hunter_has_agents": {"type": "integer"},
          "threat_hunter_scannable": {"type": "boolean"},
          "is_author": {"type":  "boolean"},
          "locked": {"type":  "boolean"},
          "is_subscribing": {"type": ["boolean", "null"]},
          "is_modified": {"type": "boolean"},
          "in_group": {"type": "boolean"},
          "public": {"type": ["boolean", "integer"]},
          "subscriber_count": {"type": "integer"},
          "export_count": {"type": "integer"},
          "upvotes_count": {"type": "integer"},
          "downvotes_count": {"type": "integer"},
          "votes_count": {"type": "integer"},
          "validator_count": {"type": "integer"},
          "comment_count": {"type": "integer"},
          "indicator_count": {"type": "integer"},
          "follower_count":{"type": "integer"}
        }
      }
    }
  }
}

Example:

{
  "count": 3062,
  "next": "https://otx.alienvault.com/api/v1/pulses/my?page=2",
  "results": [
    {
      "indicator_type_counts": {
        "SSLCertFingerprint": 1
      },
      "pulse_source": "web",
      "TLP": "white",
      "description": "fdsfds",
      "subscriber_count": 16,
      "tags": [],
      "export_count": 0,
      "malware_families": [],
      "is_modified": false,
      "upvotes_count": 0,
      "modified_text": "5 days ago ",
      "is_subscribing": null,
      "references": [],
      "targeted_countries": [],
      "groups": [],
      "vote": 0,
      "validator_count": 0,
      "threat_hunter_scannable": false,
      "is_author": true,
      "adversary": "",
      "id": "5ef3f97d7210ef3380011424",
      "industries": [],
      "locked": false,
      "name": "fdfds",
      "created": "2020-06-25T01:10:21.979000",
      "threat_hunter_has_agents": 1,
      "cloned_from": null,
      "downvotes_count": 0,
      "modified": "2020-06-25T01:10:21.979000",
      "comment_count": 0,
      "indicator_count": 1,
      "attack_ids": [],
      "in_group": false,
      "follower_count": 0,
      "votes_count": 0,
      "author": {
        "username": "LevelBlue",
        "is_subscribed": true,
        "avatar_url": "https://otx.alienvault.com/assets/images/default-avatar.png",
        "is_following": false,
        "id": "2"
      },
      "public": 1
    },
    {
      "indicator_type_counts": {
        "domain": 1,
        "BitcoinAddress": 2
      },
      "pulse_source": "web",
      "TLP": "white",
      "description": "",
      "subscriber_count": 16,
      "tags": [],
      "export_count": 0,
      "malware_families": [],
      "is_modified": true,
      "upvotes_count": 0,
      "modified_text": "5 days ago ",
      "is_subscribing": null,
      "references": [],
      "targeted_countries": [
        "Albania",
        "Taiwan"
      ],
      "groups": [],
      "vote": 0,
      "validator_count": 0,
      "threat_hunter_scannable": false,
      "is_author": true,
      "adversary": "",
      "id": "5ecd781592397ee1cebf38fc",
      "industries": [],
      "locked": false,
      "name": "test test",
      "created": "2020-05-26T20:12:05.989000",
      "threat_hunter_has_agents": 1,
      "cloned_from": null,
      "downvotes_count": 0,
      "modified": "2020-06-25T01:09:25.054000",
      "comment_count": 0,
      "indicator_count": 3,
      "attack_ids": [],
      "in_group": false,
      "follower_count": 0,
      "votes_count": 0,
      "author": {
        "username": "LevelBlue",
        "is_subscribed": true,
        "avatar_url": "https://otx.alienvault.com/assets/images/default-avatar.png",
        "is_following": false,
        "id": "2"
      },
      "public": 1
    },
    {
      "indicator_type_counts": {
        "domain": 2,
        "JA3": 1
      },
      "pulse_source": "web",
      "TLP": "white",
      "description": "",
      "subscriber_count": 16,
      "tags": [],
      "export_count": 0,
      "malware_families": [],
      "is_modified": true,
      "upvotes_count": 0,
      "modified_text": "35 days ago ",
      "is_subscribing": null,
      "references": [],
      "targeted_countries": [],
      "groups": [],
      "vote": 0,
      "validator_count": 0,
      "threat_hunter_scannable": false,
      "is_author": true,
      "adversary": "",
      "id": "5ea34db3699f0f69a4028c76",
      "industries": [],
      "locked": false,
      "name": "fsfdsfds",
      "created": "2020-04-24T20:36:03.665000",
      "threat_hunter_has_agents": 1,
      "cloned_from": null,
      "downvotes_count": 0,
      "modified": "2020-05-26T15:28:28.627000",
      "comment_count": 0,
      "indicator_count": 3,
      "attack_ids": [],
      "in_group": false,
      "follower_count": 0,
      "votes_count": 0,
      "author": {
        "username": "LevelBlue",
        "is_subscribed": true,
        "avatar_url": "https://otx.alienvault.com/assets/images/default-avatar.png",
        "is_following": false,
        "id": "2"
      },
      "public": 1
    },
    {
      "indicator_type_counts": {
        "YARA": 1,
        "domain": 1,
        "FilePath": 1,
        "URL": 1,
        "FileHash-PEHASH": 1,
        "hostname": 1,
        "URI": 1,
        "email": 1,
        "FileHash-SHA1": 1,
        "Mutex": 1,
        "IPv4": 2,
        "IPv6": 1,
        "CVE": 1,
        "FileHash-MD5": 1,
        "FileHash-SHA256": 1,
        "FileHash-IMPHASH": 1
      },
      "pulse_source": "web",
      "TLP": "white",
      "description": "",
      "subscriber_count": 16,
      "tags": [],
      "export_count": 0,
      "malware_families": [],
      "is_modified": false,
      "upvotes_count": 0,
      "modified_text": "94 days ago ",
      "is_subscribing": null,
      "references": [],
      "targeted_countries": [],
      "groups": [
        {
          "name": "test group 1",
          "id": 1
        }
      ],
      "vote": 0,
      "validator_count": 0,
      "threat_hunter_scannable": true,
      "is_author": true,
      "adversary": "",
      "id": "5e7ea3da11d0c1fa4d81476c",
      "industries": [],
      "locked": false,
      "name": "misp feed test pulse",
      "created": "2020-03-28T01:09:46.249000",
      "threat_hunter_has_agents": 1,
      "cloned_from": null,
      "downvotes_count": 0,
      "modified": "2020-03-28T01:09:54.552000",
      "comment_count": 0,
      "indicator_count": 17,
      "attack_ids": [],
      "in_group": true,
      "follower_count": 0,
      "votes_count": 0,
      "author": {
        "username": "LevelBlue",
        "is_subscribed": true,
        "avatar_url": "https://otx.alienvault.com/assets/images/default-avatar.png",
        "is_following": false,
        "id": "2"
      },
      "public": 1
    },
    {
      "indicator_type_counts": {
        "domain": 2
      },
      "pulse_source": "web",
      "TLP": "white",
      "description": "",
      "subscriber_count": 16,
      "tags": [
        "tag1",
        "tag2"
      ],
      "export_count": 0,
      "malware_families": [
        {
          "display_name": "#Exploit:NtQueryIntervalProfile",
          "id": "#Exploit:NtQueryIntervalProfile",
          "target": null
        },
        {
          "display_name": "Backdoor:MSIL/Aataki",
          "id": "Backdoor:MSIL/Aataki",
          "target": "/malware/Backdoor:MSIL/Aataki"
        }
      ],
      "is_modified": true,
      "upvotes_count": 0,
      "modified_text": "35 days ago ",
      "is_subscribing": null,
      "references": [],
      "targeted_countries": [
        "Afghanistan",
        "Albania"
      ],
      "groups": [
        {
          "name": "private test group",
          "id": 3
        },
        {
          "name": "test group 1",
          "id": 1
        },
        {
          "name": "test group 2",
          "id": 2
        }
      ],
      "vote": 0,
      "validator_count": 0,
      "threat_hunter_scannable": false,
      "is_author": true,
      "adversary": "",
      "id": "5e7ce89583cf67a885acfee9",
      "industries": [
        "xxx",
        "yyy"
      ],
      "locked": false,
      "name": "test 1",
      "created": "2020-03-26T17:38:29.959000",
      "threat_hunter_has_agents": 1,
      "cloned_from": null,
      "downvotes_count": 0,
      "modified": "2020-05-26T15:28:51.390000",
      "comment_count": 0,
      "indicator_count": 2,
      "attack_ids": [
        {
          "display_name": "T1002 - Data Compressed",
          "id": "T1002",
          "name": "Data Compressed"
        },
        {
          "display_name": "T1001 - Data Obfuscation",
          "id": "T1001",
          "name": "Data Obfuscation"
        }
      ],
      "in_group": true,
      "follower_count": 0,
      "votes_count": 0,
      "author": {
        "username": "LevelBlue",
        "is_subscribed": true,
        "avatar_url": "https://otx.alienvault.com/assets/images/default-avatar.png",
        "is_following": false,
        "id": "2"
      },
      "public": 1
    }
  ],
  "previous": null
}

get

Returns your feed of pulses you've created, default sorted by latest modified.

get

get

Search for users matcing query

get

get

Search for pulses matcing query

get

/api/v1/users

get

Validate your API Key configuration. If valid, some basic information about the user account corresponding to the API Key supplied will be returned.

get

get

Perform actions like follow/subscribe to other users by username.

actions:

  • subscribe: Include all of this users' pulses in my threat intelligence feed.
  • unsubscribe: Remove all of this users' pulses from my threat intelligence feed.
  • follow: Include all of this users' pulses in my activity feed, (Individual pulses must be subscribed to directly for inclusion in threat intelligence feed).
  • unfollow: Remove all of this users' pulses from my activity feed.

Examples:

* Subscribe to LevelBlue user account: api/v1/users/LevelBlue/subscribe
* Unsubscribe to LevelBlue user account: api/v1/users/LevelBlue/unsubscribe
* Follow LevelBlue user account: api/v1/users/LevelBlue/follow
* Unfollow LevelBlue user account: api/v1/users/LevelBlue/unfollow
get

URI Parameters

  • username: required (string)

    Example:

    LevelBlue
  • action: required (one of subscribe, unsubscribe, follow, unfollow)

    Example:

    subscribe

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "subscribed",
        "unsubscribed",
        "followed",
        "unfollowed"
      ]
    }
  }
}

Example:

{
  "status": "followed"
}

HTTP status code 404

Body

Type: application/json

/api/v1/user

get

Validate your API Key configuration. If valid, some basic information about the user account corresponding to the API Key supplied will be returned.

get

get

Perform actions like follow/subscribe to other users by username.

actions:

  • subscribe: Include all of this users' pulses in my threat intelligence feed.
  • unsubscribe: Remove all of this users' pulses from my threat intelligence feed.
  • follow: Include all of this users' pulses in my activity feed, (Individual pulses must be subscribed to directly for inclusion in threat intelligence feed).
  • unfollow: Remove all of this users' pulses from my activity feed.

Examples:

* Subscribe to LevelBlue user account: api/v1/users/LevelBlue/subscribe
* Unsubscribe from the LevelBlue user account: api/v1/users/LevelBlue/unsubscribe
* Follow LevelBlue user account: api/v1/users/LevelBlue/follow
* Unfollow LevelBlue user account: api/v1/users/LevelBlue/unfollow
get

URI Parameters

  • username: required (string)

    Example:

    LevelBlue
  • action: required (one of subscribe, unsubscribe, follow, unfollow)

    Example:

    subscribe

HTTP status code 200

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "additionalProperties": false,
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "subscribed",
        "unsubscribed",
        "followed",
        "unfollowed"
      ]
    }
  }
}

Example:

{
  "status": "followed"
}

HTTP status code 404

Body

Type: application/json