Symantec DeepSight™ Intelligence API

User’s Guide
 ii

Symantec DeepSight™ Intelligence API User’s Guide

The software described in this book is furnished under a license agreement and may be
used only in accordance with the terms of the agreement.
Documentation version 1.0

Legal Notice
Copyright © 2015 Symantec Corporation. All rights reserved.
Symantec, the Symantec Logo, DeepSight Intelligence, and the Checkmark Logo are
trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S.
and other countries. Other names may be trademarks of their respective owners.
The product described in this document is distributed under licenses restricting its use,
copying, distribution, and decompilation/reverse engineering. No part of this document
may be reproduced in any form by any means without prior written authorization of
Symantec Corporation and its licensors, if any.
THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED
CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-
INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS
ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE
FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE
FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION
CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE.
The Licensed Software and Documentation are deemed to be commercial computer
software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section
52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202, et
seq. "Commercial Computer Software and Commercial Computer Software Documentation,"
as applicable, and any successor regulations, whether delivered by Symantec as on
premises or hosted services. Any use, modification, reproduction release, performance,
display or disclosure of the Licensed Software and Documentation by the U.S. Government
shall be solely in accordance with the terms of this Agreement.
Symantec Corporation
350 Ellis Street
Mountain View, CA 94043
http://www.symantec.com
 Contents

Chapter 1 Introducing the DeepSight Intelligence API ........................................ 1

About this document ..............................................................................................................1
About the DeepSight Intelligence API ................................................................................1
About access and licensing ........................................................................................1
About status codes and which calls count against your total ..............................3
About authentication ..................................................................................................3
About SSL and certificates .........................................................................................3
Obtaining your API key .........................................................................................................4
Generating API audit reports ...............................................................................................4
Glossary....................................................................................................................................5

Chapter 2 Interface endpoints ............................................................................. 6

Interface definition ................................................................................................................6
/application/usage_limit_status ...............................................................................6
/domains/{domain} ......................................................................................................7
/files/{hash} ............................................................................................................... 11
/ips/{ip address} ........................................................................................................ 12
/mati/actors?q={q}.................................................................................................... 16
/mati/emails?q={q} ................................................................................................... 18
/mati/files?q={q} ....................................................................................................... 19
/mati/groups?q={q} .................................................................................................. 20
/mati/profiles/actors................................................................................................ 21
/mati/profiles/actors/{name} ................................................................................. 22
/mati/reports ............................................................................................................. 25
/mati/reports/{id} ..................................................................................................... 27
/mati/reports/{id}/report ........................................................................................ 32
/mati/reports/{id}/summary ................................................................................... 33
/urls/{url} ................................................................................................................... 34
 1
1

Chapter

Introducing the DeepSight

Intelligence API
This chapter contains the following sections:
 About this document
 About the DeepSight Intelligence API
 Obtaining your API key
 Generating API audit reports
 Glossary

About this document

This document defines the interface for DeepSight Intelligence API functionality.

About the DeepSight Intelligence API

The DeepSight Intelligence API provides REST-based access to the same security
intelligence content you can find in the DeepSight Intelligence portal, but in a readily
consumable JSON format.

About access and licensing

To gain access to the DeepSight Intelligence API, your company must purchase a
subscription license to either the DeepSight Intelligence Portal or the DeepSight
Intelligence Datafeeds. Then, the API feature can be enabled for your company, and
administrators can enable access for individual users. The process can be summarized as
follows:
1. Symantec enables the API functionality for a company upon license purchase.
2. The company's portal administrator enables the functionality for designated users in
their organization. Only an administrator can enable and disable API access at the user
level.
3. When notified that the feature is enabled, users log into the portal and generate their
key.
Symantec DeepSight™ Intelligence API User’s Guide 2

The API lets you access the same intelligence content that your subscription licenses entitle
you to see:
Subscription License API Endpoints Available
DeepSight Intelligence Enterprise service level /application/usage_limit_status
Portal /ips/{ip address}
/domains/{domain}
/urls/{url}
/files/{hash}
Advanced Enterprise service level /application/usage_limit_status
/ips/{ip address}
/domains/{domain}
/urls/{url}
/files/{hash}
All MATI endpoints
DeepSight Intelligence IP Reputation /application/usage_limit_status
Datafeeds /ips/{ip address} (basic field set)
Domain/URL Reputation /application/usage_limit_status
/domains/{domain} (basic field
set)
/urls/{url} (basic field set)
Advanced IP Reputation /application/usage_limit_status
/ips/{ip address} (advanced field
set)
Advanced Domain/URL Reputation /application/usage_limit_status
/domains/{domain} (advanced
field set)
/urls/{url} (advanced field set)
Vulnerability NA*
Security Risk NA*
*In API version 1, no data is returned for the Vulnerability and Security Risk Datafeeds.

The number of calls allowed depends on your organization's subscriptions:

License Maximum calls per day*
Enterprise service level 1,000
Advanced Enterprise service level 3,000
IP Reputation datafeed 2,000
Domain/URL Reputation datafeed 2,000
Advanced IP Reputation datafeed 3,000
Advanced Domain/URL Reputation datafeed 3,000
Vulnerability datafeed 1,000**
Security Risk datafeed 1,000**
*The API call accounting period starts at 00:00:00 UTC and ends 24 hours later at 23:59:59.
**In API version 1, no data is returned for the Vulnerability and Security Risk Datafeeds, however,
additive rules apply when combined with other licenses (that is, these licenses will add 1,000 calls
each to your company's daily maximum).
Symantec DeepSight™ Intelligence API User’s Guide 3

Call count is additive, meaning that you add the maximum calls for multiple licenses that
your company purchased. For example, if your company has both Advanced IP Reputation
datafeed and Advanced Domain/URL Reputation datafeed licenses, your company can make
a maximum of 6,000 calls per day.
If you need more API calls than your entitlement allows, you can purchase an additional
1,000 calls per day via the SKU "SYMC CYBER SECURITY DEEPSIGHT API ADDON 1K
CALLS PACK". You can purchase as many add-on packs as you need to reach the API call
count you require.
Contact your Account Manager for more information.

About status codes and which calls count against your total
Every API call returns a status code in the response. The status code lets you know whether
your call succeeded or failed and gives a reason for failure.
The following table shows the API return codes and identifies which codes count against
your daily call total:
Status Description Counts
Code against
total?
200 Request fulfilled. Yes
400 Invalid input. Input was in an incorrect format. No
403 Access denied. The API key was successfully authenticated, but the license No
does not permit access to the requested resource.
404 Data not found. The call completed successfully, but no information was found Yes
for the queried data.
429 The license count usage for the given period has been exceeded. No
503 Server is overloaded. Retry your call after the time period displayed. No

About authentication
For every API call, you need a custom API key header to authenticate your access. Use the
DeepSight Intelligence portal to obtain your API key (see Obtaining your API key on page 4
for more information). Each user in an organization must have a separate key.
Upon successful authentication, the API call returns HTTP response code 200 with relevant
data. For an invalid or failed authentication, the response code is:
Status Code Description
401 The API key is not valid to access this service or the API-KEY header was not
properly specified.

About SSL and certificates

The API endpoints are configured to use a full VeriSign certificate. The set of Secure
Sockets Layer (SSL) algorithms supported and enabled is under regular review. As new
vulnerabilities are discovered and reported, the specific SSL/TLS configuration may
change.
Currently, this API supports connections using the following protocols:
 TLS1.2
 TLS1.0
Symantec DeepSight™ Intelligence API User’s Guide 4

Obtaining your API key

When your administrator notifies you that your account has the API feature enabled, log
into the DeepSight Intelligence portal and generate a key.

Note: Where the portal interface uses the term "DeepSight API token," it is referring to the
API key.

To enable the API feature for a user (Administrator only)

1. On any portal page, click Settings in the upper right corner.
2. On the Settings page, click the Users link.
3. On the Users page, search for or scroll through the grid to the user you want to view
and click that user's email address link.
4. At the user's detail page, locate the DeepSight API Token tab and click Enable Access.

To disable the API feature for a user (Administrator only)

1. Repeat Steps 1 through 3 from the procedure above.
2. At the user's detail page, locate the DeepSight API Token tab and click Disable Access.

Note: If you disable a user's access by mistake and then re-enable it, know that the disable
action invalidated the user's API key. Re-enabling access generates another key. Be sure to
notify the user so that they know to copy and use the new, valid API key.

To generate an API key

1. Log in to the portal.
2. On any portal page, click Settings in the upper right corner.
3. On the Settings page, click the My Profile link.
4. On your profile detail page, locate the DeepSight API Token tab.
5. Highlight and copy the API key displayed, or click Regenerate and replace your existing
key. You can have only one key at a time per account and it remains valid until you
generate another to replace it.

Generating API audit reports

Another part of API functionality in the portal is the ability to generate audit reports.
Administrators can run reports for themselves and for their entire organization's user base.
Non-administrative users can run reports only on their own activity.
The audit report provides either summary or detailed API call activity for up to the last
year. The summary version provides user IDs and call totals; the detailed version shows
user IDs, endpoints called and call totals per endpoint.
See the right side of the page for a count of your API calls as well as your company's calls on
the current day.

To generate an API audit report

1. On any portal page, click Settings in the upper right corner.
2. On the Settings page, click the DeepSight API link.
3. Click in the first Data Range field and use the widget to set a start date for the report,
then repeat the action in the second field. The maximum reporting period for the audit
report is one year from the current day.
Symantec DeepSight™ Intelligence API User’s Guide 5

4. Click the Search Type pick list and select one of the options displayed:
 Detailed: Returns a table of user IDs, endpoints that the user ID called, and call
totals per endpoint for the reporting period.
 Summary: Returns a table of user IDs and the total number of API calls that the
user made during the reporting period.
5. Administrators only: Click the Include all user data box to return audit data for all
users in your organization.
6. Click Submit.

Glossary
Refer to the following table for unfamiliar terms and abbreviations.
Term Description
API Application Programming Interface
JSON JavaScript Object Notation
MATI Managed Adversary & Threat Intelligence
REST Representational State Transfer
 2
6

Chapter

Interface endpoints
This chapter contains the following sections:
 Interface definition

Interface definition
The following sections provide detailed endpoint definitions with JSON response schema.
Regarding the schema fields, it is important to note the following:
 All strings are in UTF8 format unless explicitly stated.
 IP address fields support IPv4 format only.
All of the following endpoints append to this base URL:
https://deepsightapi.symantec.com/v1
Also, when forming your request, we highly recommend that you include the Accept:
application/json statement.

Note: The API call accounting period starts at 00:00:00 UTC and ends 24 hours later at
23:59:59.

/application/usage_limit_status
Returns current usage limits based on license entitlement. This API call is not counted
against your entitlement limit.
Input Required Header: API-KEY
Optional Accept: application/json
Output  X-License-Limit-Limit
 X-License-Limit-Remaining
 X-License-Limit-Reset

Request
URL: https://deepsightapi.symantec.com/v1/application/usage_limit_status
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/application/usage_limit_status HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json
Symantec DeepSight™ Intelligence API User’s Guide 7

Response
Status codes
Status Code Description
200 Request fulfilled.

Content
Data Item Type Description
X-License-Limit-Limit Integer The maximum number of calls allowed per license
entitlement per day
X-License-Limit-Remaining Integer The number of calls allowed before the license
entitlement limit is reached for the day
X-License-Limit-Reset Integer The number of seconds before the license enforcement
period is reset; you will be able to successfully make API
calls again after the indicated period

Example
{
"X-License-Limit-Limit": 100,
"X-License-Limit-Remaining": 97,
"X-License-Limit-Reset": 9624
}

/domains/{domain}
Retrieves reputation and metadata for a domain name. The input must be a domain name;
IP addresses are not supported. The domain name is not case sensitive.
If no reputation data exists, those data items will be removed from the response.
Input Required  Header: API-KEY
 Domain
Optional Accept: application/json
Output Domain information and associated MATI report IDs depending on your subscriptions

Request
URL: https://deepsightapi.symantec.com/v1/domains/{domain}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/domains/example.com HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
Symantec DeepSight™ Intelligence API User’s Guide 8

Status Code Description

400 Invalid input. The domain is in an incorrect format.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Domain not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema properties
schemaVersion Integer The schema version identifier
domain String The domain searched
whitelisted Boolean Indicates whether the domain is whitelisted
firstSeen String The time and date that the domain first appeared in the
database
lastSeen String The time and date that the domain last appeared in the
database
reputationValues
reputation Integer A value that combines an item’s behaviors exhibited,
confidence in the listing, hostility of the item, consecutive
listings and listing ratio; values range from 1 to 10 with
higher values representing a worse reputation
confidence Integer Shows our confidence on whether the listing is correct or a
false positive with values ranging from 1 to 5 with higher
values representing more confidence in the listing
hostility Integer Enumerates the IP address’ hostility level with values
ranging from 1 to 5 with higher values representing a more
hostile item
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier
whois properties
person String The name of the person who registered the domain
email String The email address of the person who registered the domain
organization String The organization that registered the domain
city String The city portion of the registration address
postalCode String The postal code portion of the registration address
country String The country portion of the registration address
created String The date on which the domain was registered
Symantec DeepSight™ Intelligence API User’s Guide 9

Data Item Type Description

updated String The date on which the registration of the domain was
updated
expires String The date on which the registration is scheduled to expire
registrar String The registrar that registered the domain
nameServers Array An array of name servers associated with the registered
person in the whois record
(nameServers) items String Individual name servers in the array
ips items properties
ip String The IPv4 formatted address associated with the domain
uri String The Uniform Resource Identifier for the IP address
url items properties
url String The Uniform Resource Locator associated with the domain
uri String The Uniform Resource Identifier for the URL
behaviours items properties
type String A subcategory of behaviour
behaviour String Indicates that the domain has been observed as part of a
specific activity: Attack, Bot, CnC, Fraud, Malware,
Phish_host, or Spam
detail String A description of the activity observed
urls Array An array of the URLs associated with a particular behaviour
(urls) items String An individual URL from the array
targetCountries
(targetCountries) items String Three-letter ISO3 code representing a country associated
with the domain's activity
targetIndustries items properties
naics Integer North American Industry Classification System; this
provides the numerical code for the type of industry to which
the targeted domain belongs
name String This is the name linked to the NAICS code

Example
{
"schemaVersion": 1,
"domain": "example.com",
"whitelisted": false,
"firstSeen": "2015-04-23T00:00:00Z",
"lastSeen": "2015-04-27T00:00:00Z",
"reputationValues": {
"reputation": 2,
"confidence": 1,
"hostility": 3
},
"matiReports": [
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10:47Z",
Symantec DeepSight™ Intelligence API User’s Guide 10

"uri": "/v1/mati/reports/300156"
}
],
"whois": {
"person": "Bad Guy",
"email": "[email protected]",
"organization": "BAD GUY",
"city": "Rez",
"postalCode": "54400",
"country": "France",
"created": "2015-03-13T00:00:00Z",
"updated": "2015-03-13T00:00:00Z",
"expires": "2016-03-13T00:00:00Z",
"registrar": "OVH",
"nameServers": [ "DNS800.ANYCAST.ME", "NS800.ANYCAST.ME" ]
},
"ips": [
{
"ip": "1.2.3.4",
"uri": "/v1/ips/1.2.3.4"
},
{
"ip": "1.2.3.5",
"uri": "/v1/ips/1.2.3.5"
}
],
"urls": [
{
"url": "http://www.example.com/malicious/path",
"uri": "/v1/urls/http://www.example.com/malicious/path"
}
],
"behaviours": [
{
"type": "Anti-Malware",
"behaviour": "Malware",
"description": "PUA.Gen"
},
{
"type": "Anti-Malware",
"behaviour": "Malware",
"description": "Suspicious.Cloud"
},
{
"type": "Anti-Malware",
"behaviour": "Malware",
"description": "Trojan.Gen"
},
{
"type": "Intrusion Detection",
"behaviour": "Malware",
"description": "Fake Flash Update Website"
},
{
"type": "Reputation",
"behaviour": "Phish_Host",
"description": "Phishing Site"
},
{
"type": "Intrusion Detection",
"behaviour": "WWW Attacks",
"description": "This signature detects Web pages displaying download prompts or
fake scans to lure the user into downloading misleading applications."
}
Symantec DeepSight™ Intelligence API User’s Guide 11

],
"targetCountries": [ "usa", "gbr", "can", "aus", "deu", "ita", "sxm", "afg", "rus",
"sau" ],
"targetIndustries": [
{
"naics": 541,
"name": "Professional, Scientific, and Technical Services"
},
{
"naics": 517,
"name": "Telecommunications"
}
]
}

/files/{hash}
Retrieves metadata and/or MATI report IDs for a MD5 or SHA256 file hash.
 SHA256: Returns metadata, including a Symantec disposition, and any MATI report
IDs that reference the hash.
 MD5: Returns MATI report IDs that reference the hash.
The string should contain only hexadecimal characters and may be prepended with an
optional "0x" string. The value is case insensitive.
Input Required  Header: API-KEY
 MD5 or SHA256 file hash
Optional Accept: application/json
Output File hash metadata and/or associated MATI report IDs depending on your subscriptions

Request
URL: https://deepsightapi.symantec.com/v1/files/{hash}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/files/a77e89bf60e931477f5858a004fb5e0a
HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. The hash is in an invalid format.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 File not found. Ensure that the file hash is in MD5 or SHA256 format.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.
Symantec DeepSight™ Intelligence API User’s Guide 12

Content
Data Item Type Description
Schema properties
schemaVersion Integer The schema version identifier
MD5 String The MD5 hash string
SHA256 String The SHA256 hash string
reputation String Returns one of the following codes:
Malicious
Trending Bad
Unknown Reputation
Trending Clean
Clean
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier

Example
{
"schemaVersion": 1,
"md5": "a77e89bf60e931477f5858a004fb5e0a",
"sha256": "e46d5472e49793017892cb18a0aa174ff9c5b79cec0a9451f1b70e21b19855c2",
"reputation": "Malicious",
"matiReports": [
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10:47Z",
"uri": "/v1/mati/reports/300156"
}
]
}

/ips/{ip address}
Get reputation and metadata for a single IPv4 formatted IP address. IP address fields
support IPv4 format only.
If no reputation data exists, those data items will be removed from the response.
Input Required  Header: API-KEY
 IPv4 IP address
Optional  Accept: application/json
 Accept-Encoding: gzip, deflate
Output IP address information and associated MATI report IDs depending on your
subscriptions

Request
URL: https://deepsightapi.symantec.com/v1/ips/{ip_address}
Symantec DeepSight™ Intelligence API User’s Guide 13

Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/ips/192.0.2.1 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. The address must be in standard IPv4 format; e.g., abc.def.ghi.jkl.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 IP address not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema properties
schemaVersion Integer The schema version identifier
whitelisted Boolean Indicates whether the IP address is whitelisted
ip String The IP address searched
firstSeen String The time and date that the IP address first appeared in the
database
lastSeen String The time and date that the IP address last appeared in the
database
reputationValues
reputation Integer A value that combines an item’s behaviors exhibited,
confidence in the listing, hostility of the item, consecutive
listings and listing ratio; values range from 1 to 10 with
higher values representing a worse reputation
confidence Integer Shows our confidence on whether the listing is correct or a
false positive with values ranging from 1 to 5 with higher
values representing more confidence in the listing
hostility Integer Enumerates the IP address’ hostility level with values
ranging from 1 to 5 with higher values representing a more
hostile item
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier
Symantec DeepSight™ Intelligence API User’s Guide 14

Data Item Type Description

organization properties
name String The name of the organization that owns the IP address
type String The type of the organization that owns the IP address;
examples include (but are not limited to):
Telecommunications, Professional Service, Banking,
Manufacturing, Data Services, Insurance, Transportation,
Business Conglomerate, Utilities, Legal Services, Religious
Organizations, Building Services, Publishing, Member
Organization, Motor Vehicles, Animal Production,
Agriculture, Internet Colocation Services, and Mining
naics Integer North American Industry Classification System; this
provides the numerical code for the type of industry to
which the IP address belongs
isic String International Standard Industrial Classification; this
provides the code for the type of industry to which the IP
address belongs
network properties
carrier String The carrier/ISP name where the IP address is located
asn Integer The Autonomous System Number where the IP address
resides
lineSpeed String The connection speed for the IP address; possible values
are: low, medium, high, and NULL
ipRouting String The IP routing type for the IP address; possible values
include: cache proxy, satellite, aol, regional proxy, fixed,
superpop, mobile gateway, international proxy, and pop
anonymizerStatus String Indicates whether the IP address has or is being used as a
proxy; possible values include: NULL, suspect, private,
active, and inactive
proxyType String Lists the IP address as one of the following: http, service,
socks, socks http, tor, unknown, or web
proxyLevel String Lists the IP address as one of the following: anonymous,
distorting, elite, or transparent
proxyLastDetected String The last date the proxy was detected as a private proxy
geolocation properties
country String The country in which the IP address is located
city String The city in which the IP address is located
latitude Number GPS coordinates for the IP address' latitude
longitude Number GPS coordinates of the IP address' longitude
behaviours items properties
type String A subcategory of behaviour
behaviour String Indicates that the IP address has been observed as part of a
specific activity: Attack, Bot, CnC, Fraud, Malware,
Phish_host, or Spam
details Array An array of descriptions observed for the behaviour
(details) items String An individual description
Symantec DeepSight™ Intelligence API User’s Guide 15

Data Item Type Description

domains items properties
domain String The domain associated with the IP address
uri String The Uniform Resource Identifier for the domain
url items properties
url String The Uniform Resource Locator associated with the IP
address
uri String The Uniform Resource Identifier for the URL
targetCountries
(targetCountries) items String Three-letter ISO3 code representing a country associated
with the domain's activity
targetIndustries items properties
naics Integer North American Industry Classification System; this
provides the numerical code for the type of industry to
which the targeted domain belongs
name String This is the name linked to the NAICS code

Example
{
"schemaVersion": 1,
"ip": "104.28.31.70",
"whitelisted": false,
"firstSeen": "2015-04-23T00:00:00Z",
"lastSeen": "2015-04-27T00:00:00Z",
"reputationValues": {
"reputation": 2,
"confidence": 1,
"hostility": 3
},
"matiReports": [
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10:47Z",
"uri": "/v1/mati/reports/300156"
}
],
"organization": {
"name": "test project",
"type": "Telecommunications",
"naics": 518210,
"isic": "J6311"
},
"network": {
"carrier": "example, inc.",
"asn": 123,
"lineSpeed": "High",
"ipRouting": "Fixed",
"anonymizerStatus": "Private",
"proxyType": "Web",
"proxyLevel": "Elite",
"proxyLastDetected": "2015-03-04T00:00:00Z"
},
"geolocation": {
"country": "United States",
Symantec DeepSight™ Intelligence API User’s Guide 16

"city": "San Francisco",

"latitude": 67.98217,
"longitude": -132.49756
},
"behaviours": [
{
"type": "Anti-Malware",
"behaviour": "Malware",
"description": "PUA.Gen"
},
{
"type": "Intrusion Detection",
"behaviour": "Malware",
"description": "Fake Flash Update Website"
},
{
"type": "Reputation",
"behaviour": "Phish_Host",
"description": "Phishing Site"
}
],
"domains": [
{
"domain": "example.com",
"uri": "/v1/domains/example.com"
},
{
"domain": "example1.com",
"uri": "/v1/domains/example1.com"
}
],
"urls": [
{
"url": "www.platformdll.com/~foobar",
"uri": "/v1/urls/www.platformdll.com%2F~foobar"
}
],
"targetCountries": [ "usa", "gbr", "can", "aus", "deu", "ita", "sxm", "afg", "rus",
"sau" ],
"targetIndustries": [
{
"naics": 541,
"name": "Professional, Scientific, and Technical Services"
},
{
"naics": 517,
"name": "Telecommunications"
}
]
}

/mati/actors?q={q}
Finds all MATI reports containing a specific actor handle. Substitute {q} with your search
phrase; for example, actors?q=BadGuy1.

Note: This endpoint queries MATI report data using exact case-insensitive phrase matches.
For example, you are searching for reports related to the syrian electronic army. Using the
search phrases syrian electronic army, syrian electronic, and electronic army, would return
relevant reports. The search phrases Syrian army or electronic syrian will not return
relevant reports as they do not match the phrase used in the reports. Likewise, partial
words, like syr, would not return results for syrian.
Symantec DeepSight™ Intelligence API User’s Guide 17

Input Required  Header: API-KEY

 Actor name search string
Optional Accept: application/json
Output MATI report information

Request
URL: https://deepsightapi.symantec.com/v1/mati/actors?q={q}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/actors?q=BadGuy1 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Actor not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier

Example
[
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10Z",
"uri": "/v1/mati/reports/300156"
}
]
Symantec DeepSight™ Intelligence API User’s Guide 18

/mati/emails?q={q}
Finds all MATI reports containing a specific email address.

Note: This endpoint queries MATI report data using exact case-insensitive string matches.
For example, if you are searching for reports related to [email protected], you must use
the entire address. Using parts of the address, such as badguy or badguy@email, would not
return relevant reports.
Substitute {q} with your search phrase; for example, [email protected].
The value should be URL encoded. This parameter is not case sensitive.
Input Required  Header: API-KEY
 Email address
Optional Accept: application/json
Output MATI report information

Request
URL: https://deepsightapi.symantec.com/v1/mati/emails?q={q}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/[email protected] HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. The specified string is not in the form required for an e-mail
address.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Email not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier
Symantec DeepSight™ Intelligence API User’s Guide 19

Example
[
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10Z",
"uri": "/v1/mati/reports/300156"
}
]

/mati/files?q={q}
Use this endpoint to query a detection name from MATI reports. It finds all MATI reports
containing a specific file reference in the indicator data.

Note: This endpoint queries MATI report data using exact case-insensitive string matches.
For example, if you are searching for reports related to svchost, you must use the entire file
name. Using a partial name, such as svcho, would not return relevant reports. Likewise, if
you search for a file hash, you must use the entire hash.
Substitute {q} with your search phrase; for example, files?q=BadGuy1. The value should
be URL encoded. This value can be a hash or filename. Only indicator data is searched. This
parameter is not case sensitive.
Input Required  Header: API-KEY
 MD5 or SHA256 file hash OR a file name
Optional Accept: application/json
Output MATI report information

Request
URL: https://deepsightapi.symantec.com/v1/mati/files?q={q}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/files?q=BadGuy1 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 File not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.
Symantec DeepSight™ Intelligence API User’s Guide 20

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier

Example
[
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10Z",
"uri": "/v1/mati/reports/300156"
}
]

/mati/groups?q={q}
Finds all MATI reports containing a specific group name. Substitute {q} with your search
phrase; for example, groups?q=BadGroup10. The value should be URL encoded. This
parameter is not case sensitive.

Note: This endpoint queries MATI report data using exact case-insensitive phrase matches.
For example, you are searching for reports related to the syrian electronic army. Using the
search phrases syrian electronic army, syrian electronic, and electronic army, would return
relevant reports. The search phrases Syrian army or electronic syrian will not return
relevant reports as they do not match the phrase used in the reports. Likewise, partial
words, like syr, would not return results for syrian.
Input Required  Header: API-KEY
 Group name
Optional Accept: application/json
Output MATI report information

Request
URL: https://deepsightapi.symantec.com/v1/mati/groups?q={q}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/groups?q=BadGroup10 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json
Symantec DeepSight™ Intelligence API User’s Guide 21

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Group not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier

Example
[
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10Z",
"uri": "/v1/mati/reports/300156"
}
]

/mati/profiles/actors
Retrieves the list of actor profiles.
Input Required Header: API-KEY
Optional Accept: application/json
Output List of actors

Request
URL: https://deepsightapi.symantec.com/v1/mati/profiles/actors
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/profiles/actors HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json
Symantec DeepSight™ Intelligence API User’s Guide 22

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Actor not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema items properties
id Integer The actor identification number
handle String The actor handle
lastActive String The date when the actor was last observed as active
uri String The actor profile location identifier

Example
[
{
"id": "MATI0001",
"handle": "example",
"lastactive": "2015-09-27T00:00:00Z",
"uri": "/v1/mati/profiles/actors/MATI0001"
}
]

/mati/profiles/actors/{name}
Retrieves a specific actor profile.
Input Required  Header: API-KEY
 Actor name
Optional Accept: application/json
Output Actor information

Request
URL: https://deepsightapi.symantec.com/v1/mati/profiles/actors/{name}
Method: GET
Header: API-KEY
Symantec DeepSight™ Intelligence API User’s Guide 23

Example
GET https://deepsightapi.symantec.com/v1/mati/profiles/actors/BadGuy1 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Actor not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema properties
record_id String The overall actor record identifier
status String The actor status
type String The type of actor
first_active String The data and time that the actor first appeared as active in
the database
last_active String The data and time that the actor last appeared as active in
the database
primary_handle String The primary actor handle
aliases Array An array of associated aliases
(aliases) items String An individual alias in the array
facebook_id Array An array of associated Facebook IDs
(facebook_id) items String An individual Facebook ID in the array
twitter_id Array An array of associated Twitter IDs
(twitter_id) items String An individual Twitter ID in the array
associated_incidents Array An array of associated incidents
record_id String A record identifier for an associated incident
targeted_naics String The NAICS targeted in an associated incident
targeted_country String The country targeted in an associated incident
associated_actors Array An array of associated actors
(associated_actors) String An individual associated actor in the array
items
associated_groups Array An array of associated groups
Symantec DeepSight™ Intelligence API User’s Guide 24

Data Item Type Description

(associated_groups) String A single associated group in the array
items
ttps Array An array of associated TTPs
ttps items properties
(malware) id String Identifies the activity as malware
type Array An array of malware types
malware type array items properties
md5 String The malware file's MD5 file hash
file_name String The malware file's name
sha256 String The malware file's SHA256 file hash
description String The malware file's description
ip_address properties
ipv4 Array An array of IP addresses in IPv4 format
(ipv4) items String An individual IP address in the array
url Array An array of URLs
(url) items String An individual URL in the array
domain Array An array of domains
(domain) items String An individual domain in the array
vuln Array An array of associated vulnerabilities
(vuln) items String An individual vulnerability in the array
email_address Array An array of related email addresses
(email_address) items String An individual email address in the array

Example
{
"record_id": "ACT0012",
"status": "active",
"type": "actor",
"first_active": "20150202",
"last_active": "20150202",
"primary_handle": "example",
"aliases": [
"6811",
"demo"
],
"facebook_id": [
"sample2_fb"
],
"twitter_id": [
"sample2_twt"
],
"associated_incidents": [
{
"record_id": "INC100101",
"targeted_naics": [
"719"
],
"targeted_country": [
Symantec DeepSight™ Intelligence API User’s Guide 25

"france"
]
}
],
"associated_actors": [
"ACT0012",
"ACT0013"
],
"associated_groups": [
"GRP0004",
"GRP0007"
],
"ttps": [
{
"malware": [
{
"md5": "473fcd3d9f4e57ed70ccc4700fc00b3b",
"file_name": "winrshost.exe",
"sha256":
"2841437d1bd2871ac7923dc25f7c7d3f935798b0fcc770ad853faff8eb506e4a",
"description": "This is an example"
}
],
"ip_address": {
"ipv4": [
"192.0.2.1"
]
},
"url": [
"www.example.org/demo"
],
"domain": [
"www.example.org"
],
"vuln": [
"cve-2015-1182"
],
"email_address": [
"[email protected]"
]
}
]
}

/mati/reports
Retrieves the list of all available MATI reports and allows paging through the list.
There are many MATI reports accessible in the API. To help you page through the list, the
endpoint accepts the following parameters. These parameters are not case sensitive.
 Offset: Controls the number of records to skip.
 Limit: Controls the number of records to return per page. The default is 50 records.
For example, to retrieve the first 100 rows, you can make the following request:
../mati/reports?limit=100

Then, to retrieve the second 100 rows, you would make the following request:
../mati/reports?offset=100&limit=100

An alternative is to paginate through the entire record set as shown below, continuing until
the number of reports returned is less than 50.
../mati/reports
../mati/reports?offset=50
Symantec DeepSight™ Intelligence API User’s Guide 26

../mati/reports?offset=100
../mati/reports?offset=150

Note:
1. If you specify the limit and/or offset parameters as 0 or less than 0, you will see the
message "The 'offset' and/or 'limit' parameters are out of range".
2. If you specify a very large number for the limit parameter, the API will return the default
50 records instead. Please specify a lower limit.

Input Required  Header: API-KEY

Optional  Limit
 Offset
 Accept: application/json
Output MATI report list

Request
URL: https://deepsightapi.symantec.com/v1/mati/reports
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/reports?offset=50&limit=50 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier
Symantec DeepSight™ Intelligence API User’s Guide 27

Example
[
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10Z",
"uri": "/v1/mati/reports/300156"
}
]

/mati/reports/{id}
Retrieves data for a specific MATI report. This information only includes the indicator data.
Input Required  Header: API-KEY
 Report ID
Optional Accept: application/json
Output MATI report information

Request
URL: https://deepsightapi.symantec.com/v1/mati/reports/{id}
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/reports/300161 HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. Report IDs must be numeric and non-negative.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Report ID not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema properties
schemaVersion Integer The schema version identifier
threatDomains
items String An individual threat domain from the report
Symantec DeepSight™ Intelligence API User’s Guide 28

Data Item Type Description

incidents items properties
id String The incident identifier
date String The incident date
victims Array The array of victimized companies
(victims) items String A single company in the array
ips items properties
ip String An IP address mentioned in the report
uri String The Uniform Resource Identifier for the IP address
relatedCVEs Array The array of related Common Vulnerability and Exposure
(CVE) IDs
(relatedCVEs) items String A single CVE in the array
urls items properties
url String A URL mentioned in the report
uri String The Uniform Resource Identifier for the URL
relatedCVEs Array The array of related Common Vulnerability and Exposure
(CVE) IDs
(relatedCVEs) items String A single CVE in the array
domains items properties
domain String A domain mentioned in the report
uri String The Uniform Resource Identifier for the domain
relatedCVEs Array The array of related Common Vulnerability and Exposure
(CVE) IDs
(relatedCVEs) items String A single CVE in the array
otherIndicators items properties
indicator String An indicator mentioned in the report
uri String The Uniform Resource Identifier for the indicator
relatedCVEs Array The array of related Common Vulnerability and Exposure
(CVE) IDs
(relatedCVEs) items String A single CVE in the array
files items properties
filename Array The array of file names mentioned in the report
(filename) items String A file name from the array
isMalicious Boolean Identifies whether the file is considered malicious
md5 String The file's MD5 hash string
sha256 String The file's SHA256 hash string
uri String The Uniform Resource Identifier for the file
detectionName Array The array of detection names from the report
(detectionName) items String A detection name from the array
relatedCVEs Array The array of related Common Vulnerability and Exposure
(CVE) IDs
Symantec DeepSight™ Intelligence API User’s Guide 29

Data Item Type Description

(relatedCVEs) items String A single CVE in the array
campaigns items properties
name String The name of an campaign mentioned in the report
id String The campaign identifier
status String The campaign status; for example, active or inactive
actors items properties
name String The name of an actor mentioned in the report
twitterAccounts Array The array of Twitter accounts associated with the actor
(twitterAccounts) String A single account from the array
items
facebookAccounts Array The array of Facebook accounts associated with the actor
(facebookAccounts) String A single account from the array
items
pastebinSites Array The array of Pastebin sites associated with the actor
(pastebinSites) items String A single site from the array
vkontakteAccounts Array The array of Vkontakte accounts associated with the actor
(vkontakteAccounts) String A single account from the array
items
orkutAccounts Array The array of Orkut accounts associated with the actor
(orkutAccounts) items String A single account from the array
tumblrAccounts Array The array of Tumblr accounts associated with the actor
(tumblrAccounts) String A single account from the array
items
targetIndustries items properties
naics Integer North American Industry Classification System; this
provides the numerical code for the type of industry to
which the targeted domain belongs
name String This is the name linked to the NAICS code
targetRegions items properties
regionName String The name of a targeted region
subregions Array The array of targeted subregions
subregionName String The name of a subregion in the array
countries Array The array of countries within the targeted subregion
(countries) items String An individual three-letter country code in the array
sourceRegions items properties
regionName String The name of a source region
subregions Array The array of source subregions
subregionName String The name of a subregion in the array
countries Array The array of countries within the source subregion
(countries) items String An individual three-letter country code in the array
Symantec DeepSight™ Intelligence API User’s Guide 30

Example
{
"schemaVersion": 1,
"threatDomains": [
"Cybercrime"
],
"incidents": [
{
"id": "LS1",
"date": "2014-08-18T00:00:00Z",
"victims": ["Example Company"]
}
],
"ips": [
{
"ip": "192.0.0.1",
"uri": "/v1/ips/192.0.0.1"
},
{
"ip": "192.0.0.2",
"uri": "/v1/ips/192.0.0.2",
"relatedCVEs": [
"CVE-2014-6332",
"CVE-2013-2551",
"CVE-2015-3090"
]
}
],
"domains": [
{
"domain": "example.org",
"uri": "/v1/domains/example.org",
"relatedCVEs": [
"CVE-2014-6332",
"CVE-2013-2551",
"CVE-2015-3090"
]
},
{
"domain": "demo.org",
"uri": "/v1/domains/demo.org"
}
],
"files": [
{
"filename": ["first example","1stexample"]
"isMalicious": true,
"md5": "84928f0dbf61be64c0ea8a5fcff54e38",
"sha256": "a90ac22c9424104a2a7392cee4bfae65b2005dae29435da2bd32a9402d9e5251",
"uri":
"/v1/files/a90ac22c9424104a2a7392cee4bfae65b2005dae29435da2bd32a9402d9e5251",
"detectionName": ["WS.Malware 2","Suspicious.Cloud.2"],
"relatedCVEs": ["CVE-2012-0158","CVE-2015-0118"]
},
{
"filename": ["second example"],
"isMalicious": true,
"md5": "2506b229d8f907ec26910a508cd43527",
"sha256": "6fb8a620a3104f2447d0ae9a88884b694b36e5111cc6018deb78f414a0ba10e9",
"uri":
"/v1/files/6fb8a620a3104f2447d0ae9a88884b694b36e5111cc6018deb78f414a0ba10e9"
},
{
Symantec DeepSight™ Intelligence API User’s Guide 31

"filename": "example file",

"isMalicious": true,
"md5": "b7c282690ef05c8bfd4d6fd44c9725ed",
"sha256": "7b2dbc12d21bfe9e6c29213f14b9fabaee124ecbad92a5ff72f9bcae787e8a94",
"uri":
"/v1/files/7b2dbc12d21bfe9e6c29213f14b9fabaee124ecbad92a5ff72f9bcae787e8a94",
"detectionName": ["W97M.Downloader"]
}
],
"campaigns": [
{
"name": "ABC.0052",
"id": "AA.0052",
"status": "Active"
},
{
"name": "ABC.0012",
"id": "AA.0012",
"status": "Active"
}
],
"actors": [
{
"name": "Example Actor",
"twitterAcounts": ["@TwitterActor"],
"facebookAccounts": ["Facebook Actor"],
"pastebinSites": ["PastebinSite1"],
"vkontakteAccounts": ["vkontakteActor1"],
"orkutAccounts": ["orkutActor1"],
"tumblrAccounts": ["tumblrActor1"]
}
],
"otherIndicators": [
{
"indicator": "[email protected]",
"type": "email_from_address"
}
],
"targetIndustries": [
{
"naics": 52,
"name": "Finance and Insurance"
},
{
"naics": 44,
"name": "Retail"
}
],
"targetRegions": [
{
"regionName": "Americas",
"subregions": [
{
"subregionName": "North America",
"countries": [
"United States"
]
}
]
},
{
"regionName": "Europe",
"subregions": [
{
Symantec DeepSight™ Intelligence API User’s Guide 32

"subregionName": "Western Europe",

"countries": [
"Germany"
]
}
]
},
{
"regionName": "Asia",
"subregions": [
{
"subregionName": "Eastern Asia",
"countries": [
"Korea, Democratic People's Republic of"
]
}
]
}
],
"sourceRegions": [
{
"regionName": "Europe",
"subregions": [
{
"subregionName": "Eastern Europe"
}
]
}
],
"urls": [
{
"url": "www.platformdll.com/~foobar",
"uri": "/v1/urls/www.platformdll.com%2F~foobar",
"relatedCVEs": [
"CVE-2014-6332",
"CVE-2013-2551",
"CVE-2015-3090"
]
}
]
}

/mati/reports/{id}/report
Retrieves the rendered and personalized MATI report in PDF format.
Input Required  Header: API-KEY
 Report ID
Optional Accept: application/pdf
Output PDF

Request
URL: https://deepsightapi.symantec.com/v1/mati/reports/{id}/report
Method: GET
Header: API-KEY
Symantec DeepSight™ Intelligence API User’s Guide 33

Example
GET https://deepsightapi.symantec.com/v1/mati/reports/300161/report HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/pdf

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. Report IDs must be numeric and non-negative.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Report ID not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
PDF file

Example
Not applicable

/mati/reports/{id}/summary
Retrieves the executive summary text for a MATI report.
Input Required  Header: API-KEY
 Report ID
Optional Accept: application/json
Output MATI report summary section

Request
URL: https://deepsightapi.symantec.com/v1/mati/reports/{id}/summary
Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/mati/reports/300161/summary HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
Symantec DeepSight™ Intelligence API User’s Guide 34

Status Code Description

400 Invalid input. Report IDs must be numeric and non-negative.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 Report ID not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
summary String The MATI report summary text
date String The MATI report creation date
uri String The MATI report location identifier

Example
{
"id": "300080",
"title": "Napolar Malware Likely to Continue Spreading Using Different Methods",
"summary": "Symantec assesses with medium confidence that Napolar (a.k.a. Solarbot),
a malware to steal user information, is likely to continue developing its capabilities
to spread. In May 2013, a self-proclaimed malware developer created a website to
advertise the sale of Napolar. In September 2013, Napolar stole Facebook credentials
and used Facebook messages to spread the malware to individuals on the victim’s
Facebook friends list. As of October 2014, the malware spread using two spam email
campaigns. Symantec assesses with low confidence that Napolar infections are likely to
increase in the near term of two-to-four months. In early 2014, Symantec noted there
were less than 100 Napolar infections per day as compared to middle-to-late 2014 when
there were 450 infections per day. As of October 2014, Napolar combined with Pony,
which is a malware used to steal user credentials such as banking information. Napolar
can launch denial-of-service (DoS) attacks, act as a proxy server, and steal
information entered into web forms. Spreading using spam emails and working with Pony
malware suggests that Napolar can target victims for financial gain.",
"date": "2015-01-15T01:10:47Z",
"uri": "/v1/mati/reports/300080"
}

/urls/{url}
Retrieves information about a specific URL. IPv4 format addresses are supported as part of
the URL. The portion of the URL after the domain is case sensitive.
Input Required  Header: API-KEY
 URL
Optional Accept: application/json
Output URL information and associated MATI report IDs depending on your subscriptions

Request
URL: https://deepsightapi.symantec.com/v1/urls/{url}
Symantec DeepSight™ Intelligence API User’s Guide 35

Method: GET
Header: API-KEY

Example
GET https://deepsightapi.symantec.com/v1/urls/http://example.com/badfile.exe HTTP/1.1
API-KEY: 035912b2063f35f717b7180139f96cb06cb8b1d2f76cf293bcb5b4eb286e9201
Accept: application/json

Response
Status codes
Status Code Description
200 Request fulfilled.
400 Invalid input. The URL is in an invalid format.
403 Access denied. The API key was successfully authenticated, but the license does
not permit access to the requested resource.
404 URL not found.
429 The license count usage for the given period has been exceeded.
503 Server is overloaded. Retry your call after the time period displayed.

Content
Data Item Type Description
Schema properties
schemaVersion Integer The schema version identifier
url String The URL searched
whitelisted Boolean Indicates whether the URL is whitelisted
firstSeen String The time and date that the URL first appeared in the
database
lastSeen String The time and date that the URL last appeared in the database
host properties
domain String The domain associated with the URL
ip String The IPv4 formatted address associated with the URL
uri String The Uniform Resource Identifier for the URL
matiReports items properties
id Integer The MATI report identification number
title String The MATI report title
date String The MATI report creation date
uri String The MATI report location identifier
whois properties
person String The name of the person who registered the domain
email String The email address of the person who registered the domain
organization String The organization that registered the domain
city String The city portion of the registration address
Symantec DeepSight™ Intelligence API User’s Guide 36

Data Item Type Description

postalCode String The postal code portion of the registration address
country String The country portion of the registration address
created String The date on which the domain was registered
updated String The date on which the registration of the domain was
updated
expires String The date on which the registration is scheduled to expire
registrar String The registrar that registered the domain
nameServers Array An array of name servers associated with the registered
person in the whois record
(nameServers) items String Individual name servers in the array
behaviours items properties
type String A subcategory of behaviour
behaviour String Indicates that the domain has been observed as part of a
specific activity: Attack, Bot, CnC, Fraud, Malware,
Phish_host, or Spam
details Array An array of descriptions observed for the behaviour
(details) items String An individual description
ips items properties
ip String The IPv4 formatted address associated with the domain
uri String The Uniform Resource Identifier for the IP address
targetCountries
(targetCountries) items String Three-letter ISO3 code representing a country associated
with the domain's activity
targetIndustries items properties
naics Integer North American Industry Classification System; this
provides the numerical code for the type of industry to which
the targeted domain belongs
name String This is the name linked to the NAICS code

Example
{
"schemaVersion": 1,
"url": "http://example.com/malicious/path",
"whitelisted": false,
"firstSeen": "2015-04-23T00:00:00Z",
"lastSeen": "2015-04-27T00:00:00Z",
"host": {
"domain": "example.com",
"uri": "/v1/domains/example.com"
},
"matiReports": [
{
"id": 300156,
"title": "Laziok Trojan Activity and Infrastructure—January to April 2015",
"date": "2015-04-27T01:10:47Z",
"uri": "/v1/mati/reports/300156"
}
],
Symantec DeepSight™ Intelligence API User’s Guide 37

"whois": {
"person": "Bad Guy",
"email": "[email protected]",
"organization": "BAD GUY",
"city": "Rez",
"postalCode": "54400",
"country": "France",
"created": "2015-03-13T00:00:00Z",
"updated": "2015-03-13T00:00:00Z",
"expires": "2015-03-13T00:00:00Z",
"registrar": "OVH",
"nameServers": [ "DNS800.ANYCAST.ME", "NS800.ANYCAST.ME" ]
},
"behaviours": [
{
"type": "Anti-Malware",
"behaviour": "Malware",
"description": "PUA.Gen"
},
{
"type": "Intrusion Detection",
"behaviour": "Malware",
"description": "Fake Flash Update Website"
},
{
"type": "Reputation",
"behaviour": "Phish_Host",
"description": "Phishing Site"
}
],
"ips": [
{
"ip": "1.2.3.4",
"uri": "/v1/ips/1.2.3.4"
},
{
"ip": "1.2.3.5",
"uri": "/v1/ip/1.2.3.5"
}
],
"targetCountries": [ "usa", "gbr", "can", "aus", "deu", "ita", "sxm", "afg", "rus",
"sau" ],
"targetIndustries": [
{
"naics": 541,
"name": "Professional, Scientific, and Technical Services"
},
{
"naics": 517,
"name": "Telecommunications"
}
]
}