CAWS CYBER THREAT PROTECTION PLATFORM API GUIDE. Version 2.3

Transcription

1 CAWS CYBER THREAT PROTECTION PLATFORM API GUIDE Version 2.3

2 Version 2.3, 6/29/2017 NSS Labs, Inc. 206 Wild Basin Road Building A, Suite 200 Austin, TX US NSS Labs, Inc. All rights reserved. No part of this publication may be reproduced, copied/scanned,stored on a retrieval system, ed or otherwise disseminated or transmitted without the express written consent of NSS Labs, Inc. ( us or we ). Please read the disclaimer in this box because it contains important information that binds you. If you do not agree to these conditions, you should not read the rest of this report but should instead return the report immediately to us. You or your means the person who accesses this report and any entity on whose behalf he/she has obtained this report. The information in this report is subject to change by us without notice, and we disclaim any obligation to update it. The information in this report is believed by us to be accurate and reliable at the time of publication, but is not guaranteed. All use of and reliance on this report are at your sole risk. We are not liable or responsible for any damages, losses, or expenses of any nature whatsoever arising from any error or omission in this report. NO WARRANTIES, EXPRESS OR IMPLIED ARE GIVEN BY US. ALL IMPLIED WARRANTIES, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, ARE HEREBY DISCLAIMED AND EXCLUDED BY US. IN NO EVENT SHALL WE BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, PUNITIVE, EXEMPLARY, OR INDIRECT DAMAGES, OR FOR ANY LOSS OF PROFIT, REVENUE, DATA, COMPUTER PROGRAMS, OR OTHER ASSETS, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This report does not constitute an endorsement, recommendation, or guarantee of any of the products (hardware or software) tested or the hardware and/or software used in testing the products. The testing does not guarantee that there are no errors or defects in the products or that the products will meet your expectations, requirements, needs, or specifications, or that they will operate without interruption. This report does not imply any endorsement, sponsorship, affiliation, or verification by or with any organizations mentioned in this report. All trademarks, service marks, and trade names used in this report are the trademarks, service marks, and trade names of their respective owners

3 Chapter 1: Introduction 1 Chapter 2: Testing the CAWS API with Postman 2 Chapter 3: Authorization 4 Chapter 4: API Calls for GET Captures 5 Request 5 Optional Request Parameters 5 Response 7 Capture Response 7 Capture Object 7 Indicators of Attack Object 8 File Object 9 Network Connection Object 9 Process Object 9 Chapter 5: Malware Classification Details 10 Request 10 Response 10 Classification Response 10 Example JSON Output 11 Chapter 6: Get Global Statistics 12 Request 12 Required Request Parameters 12 Response 12 Global Statistics Response 12 Applications Object

4 Chapter 3 Exploits Object 13 Daily Exploits Object 13 URLs Object 13 Daily URLs Object 14 Chapter 7: Get Organization Statistics 15 Request 15 Required Request Parameters 15 Response 15 Organization Statistics Response 15 Daily Stats Object 16 Targeted Applications Object 16 Application Object 16 Chapter 8: API Calls for URL Scan 17 Submit URL Request 17 Submit URL Required Parameters 17 Submit URL Response 17 Submit URL Response Object 18 URL Scan Status Request 18 URL Scan Status Response 18 URL Scan Status Response Object 18 Status Codes 18 URL Scan Result Request 19 URL Scan Result Response 19 URL Scan Status Response Object

5 Example JSON Output 20 Postman Example 21 Chapter 9: API Calls for File Scan 22 Submit File Request 22 Submit File Required Parameters 22 Submit File Response 22 Submit File Response Object 23 File Scan Status Request 23 File Scan Status Response 23 File Scan Response Object 23 Status Codes 24 File Scan Result Request 24 URL Scan Result Response 24 File Scan Result Response Object 24 Example JSON Output 25 Postman Examples 26 Chapter 10: API CAll for Replays 28 Request 28 Optional Request Parameters 28 Response 31 Replay Response 31 Replay Object 32 Indicators of Attack Object 33 File Object

6 Chapter 3 Network Connection Object 33 Process Object 34 Chapter 11: API Calls to Get Files 35 SAZ Files Request 35 PCAP Files Request 35 Exploit Payload Request 35 Shellcode Files Request 35 Chapter 12: Python Code Examples 36 GET Captures by NSSid 36 JSON Response 36 GET Captures by Application 37 JSON Response 37 GET Captures by DetectionDate 38 JSON Response 38 GET Captures by SourceUri 39 JSON Response 39 GET Captures by SourceCountry 40 JSON Response for SourceCountry 40 GET Captures by SourceIP 41 JSON Response for SourceIP 41 GET Captures by FileMd5Hash 41 JSON Response for FileMd5Hash 42 GET Captures by FileSha1Hash 42 JSON Response for FileSha1Hash

7 GET Captures by FileSha256Hash 43 JSON Response for FileSha256Hash 44 GET Captures by NetworkPort 44 JSON Response for NetworkPort 45 GET Captures by NetworkIP 45 JSON Response for NetworkIP 46 URL Scan Submission 46 URL Scan Status 47 URL Scan Result 47 File Scan Submission 47 File Scan Status 48 File Scan Result

8 CHAPTER 1: INTRODUCTION This user guide provides the RESTful API calls needed to access the API data. These instructions describe how you can immediately access the data programmatically using your preferred languages or methods

9 CHAPTER 2: TESTING THE CAWS API WITH POSTMAN Postman is a free extension to Google Chrome that allows you to test REST requests without the need to write any code. To test the CAWS API with Postman: 1. Obtain an API key from your NSS contact. 2. Open Google Chrome browser. 3. Go to to download Postman. 4. Open Google Postman. 5. Enter the following authentication options: a. Select Basic Auth from the drop-down list. b. In the Username field, enter the NSS user ID. c. In the Password field, enter the API key provided by NSS. 6. Test the API by performing the following steps: a. Select the appropriate HTTP request from the drop-down list. The GET request is shown as an example. b. Enter an appropriate base URI. The LIST/SEARCH URI is shown as an example. 7. Click Send. Postman displays the API responses in JSON format: - 2 -

10 Chapter 2 To interpret the results, see the optional HTTP GET parameters listed in Capture Data for Get Parameters - 3 -

11 CHAPTER 3: AUTHORIZATION The CAWS API uses a standard HTTP Authorization header for authorization. All requests to the API must include a basic access Authorization header with your username and password combined with a single colon and Base64 encoded. A missing Authorization header causes the request to fail. Here is an example: Authorization: Basic XXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI= - 4 -

12 CHAPTER 4: API CALLS FOR GET CAPTURES This section provides a description of the API request to get a list of URL captures found by NSS. The response is paginated and includes properties indicating the current page and the total number of pages matching the request. Use these properties to enumerate through all the results. Optional filtering parameters can be provided to filter the response. When multiple parameters are provided, they are ANDED together. Unless otherwise noted, all requests should be URL encoded otherwise the response is undefined. Request URI /Captures/List Method GET Optional Request Parameters Parameter Description Example PageNumber NSSId Application DetectionDate Displays the results for the provided page. Used to enumerate through a large result. Include only the capture assigned the provided NSS ID. Include only those captures targeting the provided application Include only those captures found on the provided date. /Captures/List?PageNumber=2 /Captures/List?NSSid=NSS-2016-XXXXXX /Captures/List?Application=Java 7 /Captures/List?DetectionDate=

13 Chapter 4 Parameter Description Example The format is YYYYMMDD. SourceUri SourceCountry SourceIP FileMd5Hash FileSha1Hash FileSha256Has h Include only those captures found for the provided URL. The format is ISO3166.Includ e only those captures originating from the provided country. The format is ISO3166. Include only those captures originating from the provided IPv4 address. Include only those captures with a detected file matching the provided MD5 hash. Include only those captures with a detected file matching the provided SHA1 hash. Include only those captures with a detected file matching the provided SHA256 hash. /Captures/List?SourceUri= /Captures/List?SourceCountry=US /Captures/List?SourceIp= xxx.12 /Captures/List?FileMd5Hash=A77A46D F02DD298XXXXXXXXX /Captures/List?FileSha1Hash=XXXXXXXX13B8C94604BAD73967CDE6962D59 F4A /Captures/List?FileSha256Hash=XXXXXXXX13B8C94604BAD D59F - 6 -

14 Chapter 4: API Calls for GET Captures Parameter Description Example NetworkIP NetworkPort Include only those captures that generated an outbound connection to the provided IPv4 address. Include only those captures that generated an outbound connection to the provided port. /Captures/List?NetworkIP= xxx.12 /Captures/List?CVEId=NetworkPort=80 Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error Capture Response Property Description Data Type Required? CurrentPage The current page of the result int TotalPages The total number of pages in the result int Captures An array of captures matching the request. See the table Capture Object below for more information array of objects Capture Object Property Description Data Type Required? NSSID The unique identifier assigned to the capture string - 7 -

15 Chapter 4 Property Description Data Type Required? DetectionDate The timestamp the capture was found on DateTime (ISO8601) InstalledApplication The tested application. Will be deprecated in future versions string TargetedApplication The targeted application string Platform The tested platform string Browser The tested browser string SourceUri The tested URL. Will be deprecated in future versions string SourceCountry The country the tested URL was hosted in. A value of ZZ indicates the country could not be resolved. Will be deprecated in future versions string (ISO3166) SourceIp The IPv4 address of the tested URL. A value of indicate the IPv4 address could not be resolved. Will be deprecated in future versions string Files An array of file objects detected. An empty array indicates no files were detected. See the table File Object for more information. Will be deprecated in future versions array of objects NetworkConnections An array of network connection objects detected. An empty array indicates no network connections were detected. See the table Network Connection Object for more information. Will be deprecated in future versions array of objects IndicatorsOfAttack The indicators of attack. See the table Indicators of Attack Object for more information object Indicators of Attack Object Property Description Data Type Required? SourceUri The tested URL string SourceCountry The country the tested URL was hosted in. A value of ZZ indicates the country could not be resolved string (ISO3166) SourceIp The IPv4 address of the tested URL. A value of indicate the IPv4 address could not be resolved string Files An array of file objects detected. An empty array indicates no files were detected. See the table File Object for more information array of objects - 8 -

16 Chapter 4: API Calls for GET Captures Property Description Data Type Required? NetworkConnections An array of network connection objects detected. An empty array indicates no network connections were detected. See the table Network Connection Object for more information array of objects Processes An array of process objects detected. An empty array indicates no processes were detected. See the table Process Object for more information array of objects File Object Property Description Data Type Required? Name The file s name string Md5Hash The file s MD5 hash String Sha1Hash The file s SHA1 hash String Sha256Hash The file s SHA256 hash string Network Connection Object Property Description Data Type Required? IP The network connection s IPv4 address string Port The network connection s port int Process Object Property Description Data Type Required? Name The process name string Md5Hash The process MD5 hash String Sha1Hash The process SHA1 hash String Sha256Hash The process SHA256 hash string IsMalicious A flag indicating whether the process is malicious bool CommandLine The command line arguments passed to the process when it was launched string - 9 -

17 CHAPTER 5: MALWARE CLASSIFICATION DETAILS This section provides a description of the API request to get classification data associated with malware. Request URI /Files/<Md5hash> Method GET Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error Classification Response Property Description Data Type Required? Md5Hash The malware s MD5 hash String Sha1Hash The malware s SHA1 hash String Sha256Hash The malware s SHA256 hash String ThreatName The malware's classified name String ThreatLevel The malware's threat severity, on a scale of 1-5. String Classification A classification object with further information about the malware. See the example JSON output. Object

18 Chapter 5 Example JSON Output { "Md5Hash": "47DEAX...", "Sha1Hash": "DB019E40...", "Sha256Hash": "C7C21CD74...", "ThreatName": "Win32.Trojan.Krap", "ThreatLevel": 5, "Classification": { "sha1": "5cd3bc161e2e47d...", "sha256": "c7c21ccdcefd74", "sha512": "9ed2a8aaf11e98d844e524c...", "md5": "47deabce140e2fe65e73dafed04cd69c", "info": { "statistics": { "file_stats": [{ "count": 1, "subtype": "Exe", "identifications": [{ "count": 1, "name": "UPX: x" }], "type": "PE" }] }, "validation": { "valid": false, "warnings": [ "PEHeader.AddressOfEntryPoint is fixable", "PEHeader.ImportTable is invalid", "PEHeader.ResourceTable is invalid" ] }, "identification": { "version": " x", "name": "UPX","success": true, "author": "ReversingLabs" }, "file": { } }}}

19 CHAPTER 6: GET GLOBAL STATISTICS This section provides a description of the API request to get global statistics computed by CAWS between a data range. Request URI /Statistics/Global Method GET Required Request Parameters Parameter Description Example startdate enddate The start date in the range to pull computed global statistics (YYYY-MM-DD). The end date in the range to pull computed global statistics (YYYY-MM-DD). /Statistics/Global?startdate= /Statistics/Global?enddate= Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error Global Statistics Response Property Description Data Type Required? Applications An object containing application level metrics. See the table Applications Object for more information Object Exploits An object containing exploit level metrics. See the tableexploits Object for more information. Object

20 Chapter 6 Property Description Data Type Required? URLs An object containing URL level metrics. See the table URLs Object for more information Object Applications Object Property Description Data Type Required? Tested The number of tested applications Int Compromised The number of compromised applications Int Exploits Object Property Description Data Type Required? Total The total number of exploits found Int Daily An array of objects in the daily drilldown of the total number of exploits found. See the table Daily Exploits Object for more information. Array of objects Daily Exploits Object Property Description Data Type Required? Date A date one or more exploits was found DateTime (ISO8601) Count The number of exploits found on this date Int URLs Object Property Description Data Type Required? Scanned The number of URLs scanned Int Malicious The number of URLs serving an exploit Int AverageTtl The average Time to Live (TTL), in Int

21 Chapter 6: Get Global Statistics Property Description Data Type Required? days, of the URLs that were scanned and serving an exploit Daily An array of objects with the daily drilldown of the total number of URLs serving an exploit. See the table Daily URLs Object for more information. Array of objects Daily URLs Object Property Description Data Type Required? Date A date one or more URLs was serving an exploit DateTime (ISO8601) Count The number of URLs found serving an exploit Int

22 CHAPTER 7: GET ORGANIZATION STATISTICS This section provides a description of the API request to get statistics computed by CAWS between a data range for your organization. Request URI /Statistics/Organization Method GET Required Request Parameters Parameter Description Example startdate enddate The start date in the range to pull computed organization statistics (YYYY-MM-DD). The end date in the range to pull computed organization statistics (YYYY-MM-DD). /Statistics/Organization?startdate= /Statistics/Organization?enddate= Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error Organization Statistics Response Property Description Data Type Required? dailystats An array of objects containing security product level metrics. See the tabledaily Stats Object for more information Array of objects targetedapplications An array of objects containing application level metrics. See the Array of objects

23 Chapter 7 Property Description Data Type Required? table Targeted Applications Object for more information Daily Stats Object Property Description Data Type Required? Date A date DateTime (ISO 8601) Bypassing The number of exploits bypassing one or more of your security products Int BlockRate The percentage of exploits blocked by your security products Decimal Targeted Applications Object Property Description Data Type Required? Family The applications's family String Count The total number of exploits targeting all versions of this application family Int Applications An array of objects with the drilldown of the total number of exploits targeting each version of the application in this family. See the table Application Object for more information Array of objects Application Object Property Description Data Type Required? Name The name of the application String Count The number of exploits targeting this version of the application Int

24 CHAPTER 8: API CALLS FOR URL SCAN The CAWS API has three calls for URL scanning: Submission, Status and Results. Unless otherwise noted, all parameter values in the requests should be encoded. Otherwise, the response is undefined. Submit URL Request URI /Scan/Url Method POST Submit URL Required Parameters Parameter Description Example BrowserPackage Platform The browser package to scan the URL on. Use one of the values listed in the example and make sure to encode the value in the request. Internet Explorer 9 is only available when Windows 7 is selected as a platform. Internet Explorer 11 is only available on Windows 10 is selected as a platform. The platform to scan the URL on. Use one of the values listed in the example Firefox 50 Firefox Firefox Google Chrome Google Chrome Google Chrome Internet Explorer 9 Internet Explorer 11 Windows7 Windows10 Url The URL to scan Submit URL Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error

25 Chapter 8 Submit URL Response Object Property Description Data Type Required? Token A token, or unique identifier, used to poll the URL submission to determine its status string URL Scan Status Request URI /Scan/Status/url/<Token> Method GET URL Scan Status Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error URL Scan Status Response Object Property Description Data Type Required? Status The URL s scanning status. See the table Status Codes for more information Int NSSid The unique identifier assigned to the scan results. This property is only be available when the Status property indicates the URL has completed scanning String No Status Codes Status Code Status 0 Indicates the URL was queued up for scanning

26 Chapter 8: API Calls for URL Scan Status Code Status 1 Indicates the URL is in progress of being scanned 2 Indicates the URL has completed scanning and results are available URL Scan Result Request URI /Users/Captures/< NSS-xxx-xxxxxx> Method GET URL Scan Result Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error URL Scan Status Response Object See the table Capture Object for more information on the structure of the response object that is returned

27 Chapter 8 Example JSON Output { " NSSId": "NSS-xxx-xxxxxx ", "IsMalicious": true, "DetectionDate": " T22:47:11", "InstalledApplication": "Internet Explorer 9", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "DE", "SourceIp": " ", "Files": [], "NetworkConnections": [], "CVEs": [], "IndicatorsOfAttack": { "SourceUri": " "SourceCountry": "DE", "SourceIp": " ", "Files": [], "NetworkConnections": [] }

28 Chapter 8: API Calls for URL Scan Postman Example

29 CHAPTER 9: API CALLS FOR FILE SCAN The CAWS API has three calls for file scanning: Submission, Status, and Results. Unless otherwise noted, all parameter values in the requests should be encoded. Otherwise, the response is undefined. Submit File Request URI /Scan/File Method POST Submit File Required Parameters Parameter Description Example ApplicationPackage Platform File The application to scan the file with. Use one of the values listed in the example and make sure to encode the value in the request. Certain applications are only valid for certain files. The platform to scan the file on. Use one of the values listed in the example. The encoded file to scan Adobe Reader DC Adobe Reader DC Adobe Reader 9.4 Adobe Reader DC Quicktime 7.79 Itunes Itunes Microsoft Office 2013 Microsoft Office 2016 Windows7 Windows10 Submit File Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid

30 Chapter 9 HTTP Response Code Description 500 Internal error Submit File Response Object Property Description Data Type Required? Token A token, or unique identifier, used to poll the file submission to determine its status String File Scan Status Request URI /Scan/Status/File/<Token> Method GET File Scan Status Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error File Scan Response Object Property Description Data Type Required? Status The file s scanning status. See the table Status Codes for more information Int NSSId The unique identifier assigned to the scan results. This property is only available when the Status property indicates the file has completed scanning String No

31 Chapter 9: API Calls for File Scan Status Codes Status Code Status 0 Indicates the file was queued up for scanning 1 Indicates the file is in progress of being scanned 2 Indicates the file has completed scanning and results are available File Scan Result Request URI /Users/Files/<NSS-xxx-xxxxxx> Method GET URL Scan Result Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error File Scan Result Response Object Property Description Data Type Required? NSSId The unique identifier assigned to the file String DetectionDate The timestamp the file was scanned on DateTime (ISO 8601) Md5Hash The file s MD5 hash String Sha1Hash The file s SHA1 hash String Sha256Hash The file's Sha256 Hash String Platform The platform the file was scanned on String IsMalicious A flag indicating whether or not the file was exploited bool

32 Chapter 9 Property Description Data Type Required? IndicatorsOfAttack The indicators of attack. This property is only available if the IsMalicious property has a value of true. See the table Indicators of Attack Object for more information. Object No Example JSON Output { "capturemodel": { "NSSId": "NSS BY7", "Md5Hash": "C3A C5F13CB01CFE53F2C62973", "Sha1Hash": "98F21192ECE4523A243B4AB106FE93E47B5F2DA0", "Sha256Hash": "66852B297F1F49DED2D5D27AA27FCB6D51C9E0EEB A63FEF138582A73", "IsMalicious": false, "DetectionDate": " T19:26:51", "Platform": "Windows 7 SP1", "IndicatorsOfAttack": { "Files": [], "NetworkConnections": [], "Processes": [] } } }

33 Chapter 9 Postman Examples

34 CHAPTER 10: API CALL FOR REPLAYS Additional replay request filter parameters. Request URI /Replays/List Method GET Optional Request Parameters Parameter Description Example Device MissedOnly PageNumber NSSId Includes only those replays associated with the provided device name. Includes only those replays that were not blocked when tested against a device. Displays the results for the provided page. Used to enumerate through a large result the API returns all /Replays/List?Device=Cisco&MissedOnly=true /Replays/List?Device=Cisco&MissedOnly=true /Replays/List?PageNumber=2 /Replays/List?NSSid=NSS-2016-XXXXXX

35 Chapter 10 Parameter Description Example metadata associated with the NSSId. When using this GET request all source IPs will be returned for the NSSId in the request. Application DetectionDate SourceUri SourceCountry The API returns all metadata associated with the entered application. This parameter restricts the results to a specific date. The format for the date is YYYYMMDD. The API returns all events associated with a specific source URI. The API returns all /Replays/List?Application=Java 7 /Replays/List?DetectionDate= /Replays/List?SourceUri= /Replays/List?SourceCountry=US

36 Chapter 10: API CAll for Replays Parameter Description Example events associated with a specific source country. The format is ISO3166. SourceIP FileMd5Hash FileSha1Hash FileSha256Hash The API returns all events associated with a specific source IPv4 address. The API returns all events associated with a specific MD5 hash. The API returns all events associated with a specific SHA1 hash. The API returns all events associated with a specific SHA256 hash. /Replays/List?SourceIp= xxx.12 /Replays/List?FileMd5Hash=A77A46D F02DD298XXXXXXXXX /Replays/List?FileSha1Hash=XXXXXXXX13B8C94604BAD73967CDE6962D59F4A /Replays/List?FileSha256Hash=XXXXXXXX13B8C94604BAD73967CDE6962D59F NetworkIP The /Replays/List?NetworkIP= xxx

37 Chapter 10 Parameter Description Example API returns all events associated with outbound connections to the specified IP address. NetworkPort The API returns all events associated with outbound connections to the specified port. /Replays/List?CVEId=NetworkPort=80 Response HTTP Response Code Description 200 Response returned successfully 401 Authorization header missing or invalid 500 Internal error Replay Response Property Description Data Type Required? CurrentPage The current page of the result int TotalPages The total number of pages in the result int Captures An array of captures matching the request. See the table Capture Object below for more information array of objects

38 Chapter 10: API CAll for Replays Replay Object Property Description Data Type Required? Device Includes only those replays associated with the provided device name. String MissedOnly Includes only those replays that were not blocked when tested against a device. Boolean NSSID The unique identifier assigned to the capture string DetectionDate The timestamp the capture was found on DateTime (ISO8601) InstalledApplication The tested application. Will be deprecated in future versions string TargetedApplication The targeted application string Platform The tested platform string Browser The tested browser string SourceUri The tested URL. Will be deprecated in future versions string SourceCountry The country the tested URL was hosted in. A value of ZZ indicates the country could not be resolved. Will be deprecated in future versions string (ISO3166) SourceIp The IPv4 address of the tested URL. A value of indicate the IPv4 address could not be resolved. Will be deprecated in future versions string Files An array of file objects detected. An empty array indicates no files were detected. See the table File Object for more information. Will be deprecated in future versions array of objects NetworkConnections An array of network connection objects detected. An empty array indicates no network connections were detected. See the table Network Connection Object for more information. Will be deprecated in future versions array of objects IndicatorsOfAttack The indicators of attack. See the table Indicators of Attack Object for more information object

39 Chapter 10 Indicators of Attack Object Property Description Data Type Required? SourceUri The tested URL string SourceCountry The country the tested URL was hosted in. A value of ZZ indicates the country could not be resolved string (ISO3166) SourceIp The IPv4 address of the tested URL. A value of indicate the IPv4 address could not be resolved string Files An array of file objects detected. An empty array indicates no files were detected. See the table File Object for more information array of objects NetworkConnections An array of network connection objects detected. An empty array indicates no network connections were detected. See the table Network Connection Object for more information array of objects Processes An array of process objects detected. An empty array indicates no processes were detected. See the table Process Object for more information array of objects File Object Property Description Data Type Required? Name The file s name string Md5Hash The file s MD5 hash String Sha1Hash The file s SHA1 hash String Sha256Hash The file s SHA256 hash string Network Connection Object Property Description Data Type Required? IP The network connection s IPv4 address string Port The network connection s port int

40 Chapter 10: API CAll for Replays Process Object Property Description Data Type Required? Name The process name String Md5Hash The process MD5 hash String Sha1Hash The process SHA1 hash String Sha256Hash The process SHA256 hash String IsMalicious A flag indicating whether the process is malicious Boolean CommandLine The command line arguments passed to the process when it was launched String

41 CHAPTER 11: API CALLS TO GET FILES Since malicious files (if available) are retained after capturing the exploitation of end systems, the API can return SAZ and/or PCAP formatted captures of the attack. The exploit shellcode is also available. In some cases, the NSSId may not contain a corresponding malicious file. All files are returned BASE64-encoded, so the application must decode the file before performing analysis. Additionally, the Size field in the response is measured in bytes. SAZ Files Request URI /Captures/Files/Saz/NSS-2015-XXXXX Method GET PCAP Files Request Since PCAP files can be large, NSS zips the file prior to BASE64 encoding. Prior to analysis, your application must decode the BASE64 format and then unzip the file prior to analysis. URI /Captures/Files/Pcap/NSS-2015-XXXXX Method GET Exploit Payload Request URI /Captures/Files/Payload/<Md5Hash> Method GET Shellcode Files Request URI /Captures/Files/Shell/NSS-2015-XXXXX Method GET

42 CHAPTER 12: PYTHON CODE EXAMPLES The following Python script is a simple example of how to create a request and process a response from the CAWS API. The example uses the parameter and value inputs to build the request. GET Captures by NSSid import requests url = " querystring = {"NSSid":"NSS-2017-XXXXX"} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response { "NSSId": "NSS-2017-XXXXXX", "DetectionDate": " T00:04:30", "InstalledApplication": "Internet Explorer 9", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "DE", "SourceIp": "149.2xx.xxx.86", "Files": [], "NetworkConnections": [], "CVEs": [], "IndicatorsOfAttack": { "SourceUri": " "SourceCountry": "DE", "SourceIp": "149.2xx.xxx.86", "Files": [], "NetworkConnections": [] }

43 Chapter 12 GET Captures by Application import requests url = " querystring = {"Application":"Java 7"} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response { "NSSId": "NSS-2016-XXXXXX", "DetectionDate": " T21:32:58", "InstalledApplication": "Java 7", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "CN", "SourceIp": "218.xxx.xxx.158", "Files": [ { "Name": "putty.exe", "Md5Hash": "50BF F8967B5FCE71F32561D7", "Sha1Hash": "BF4A8C3BA315B0565F423D83DC88C17F5044D7D6", "Sha256Hash": "2E9E372A292BD922E9E80FB0614EF71B64CC000876B63158D4ACEEAB401250A0" }

44 Chapter 12: Python Code Examples GET Captures by DetectionDate import requests url = " querystring = {"DetectionDate":" "} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response { "NSSId": "NSS-2017-XXXXXX", "DetectionDate": " T15:09:02", "InstalledApplication": "Internet Explorer 9", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "ZZ", "SourceIp": " XXX.145", "Files": [], "NetworkConnections": [], "CVEs": [], "IndicatorsOfAttack": { "SourceUri": " "SourceCountry": "ZZ", "SourceIp": " XXX.145", "Files": [], "NetworkConnections": [] }

45 Chapter 12 GET Captures by SourceUri import requests url = " querystring = {"SourceUri":" headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response { "NSSId": "NSS-2015-XXXX", "DetectionDate": " T15:19:43", "InstalledApplication": "Adobe Reader 8.1.1", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": " xxx.12", "Files": [ { "Name": "Uninstall.vbs", "Md5Hash": "N/A ", "Sha1Hash": "N/A ", "Sha256Hash": "N/A " }, { "Name": "h3sdb.exe", "Md5Hash": "C598DB096B1D21709D147245B3E43961", "Sha1Hash": "4E95FD61CD4D48F49CBD8CA38BA8D5EC44B358F8", "Sha256Hash": "71027D89213B8C94604BAD73967CDE6962D59F4A49A239056BC671CE6FE9A681" }, { "Name": "Elvvi.exe", "Md5Hash": "A77A46D F02DD298D0FFE2BA3", "Sha1Hash": "F D24759E898EA96B29E71A1D4BA051A92", "Sha256Hash": "FB55EA41A0D6DA2CEC8ECF BE6AD1F8CFE8291F5EB372B56BE1E2E1CA5" },

46 Chapter 12: Python Code Examples GET Captures by SourceCountry import requests url = " querystring = {"SourceCountry":"KR"} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response for SourceCountry { "NSSId": "NSS-2017-XXXXX", "DetectionDate": " T03:51:44", "InstalledApplication": "Java 6 Update 27", "TargetedApplication": "Java 6 Update 27", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": "110.xx.146.xx", "Files": [], "NetworkConnections": [], "CVEs": [], "IndicatorsOfAttack": { "SourceUri": " "SourceCountry": "KR", "SourceIp": "110.xx.146.xx", "Files": [], "NetworkConnections": [] }

47 Chapter 12 GET Captures by SourceIP import requests url = " querystring = {"SourceIp":" "} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text) JSON Response for SourceIP { "NSSId": "NSS-2015-XXXX", "DetectionDate": " T15:19:43", "InstalledApplication": "Adobe Reader 8.1.1", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": " xxx.12", "Files": [ { "Name": "Uninstall.vbs", "Md5Hash": "N/A ", "Sha1Hash": "N/A ", "Sha256Hash": "N/A " }, GET Captures by FileMd5Hash import requests url = " querystring = {"FileMd5Hash":"A77A46D F02DD298D0FFE2BA3"} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text)

48 Chapter 12: Python Code Examples JSON Response for FileMd5Hash { "NSSId": "NSS-2015-XXXXX", "DetectionDate": " T15:19:43", "InstalledApplication": "Adobe Reader 8.1.1", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": " xxx.12", "Files": [ { "Name": "Uninstall.vbs", "Md5Hash": "N/A ", "Sha1Hash": "N/A ", "Sha256Hash": "N/A " }, GET Captures by FileSha1Hash import requests url = " querystring = {"FileSha1Hash":"4E95FD61CD4D48F49CBD8CA38BA8D5EC44B358F8"} headers = { 'authorization': "Basic XXXXXXXXXXM6OTE0RkFCNTdCOTBCNDhFREJBOTM5RDk1QkY3RDA3ODI=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text)

49 Chapter 12 JSON Response for FileSha1Hash {"NSSId": "NSS-2015-XXXXX", "DetectionDate": " T15:19:43", "InstalledApplication": "Adobe Reader 8.1.1", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": " xxx.12", "Files": [ { "Name": "Uninstall.vbs", "Md5Hash": "N/A ", "Sha1Hash": "N/A ", "Sha256Hash": "N/A " }, GET Captures by FileSha256Hash import requests url = " querystring = {"FileSha256Hash":"99D76B422F572D315857DB9E4F4889DFC0E2CAD09D725AF64E0096FE7E637872" headers = {'authorization': 'Basic xxxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi='} response = requests.request("get", url, headers=headers, params=querystring) print(response.text)

50 Chapter 12: Python Code Examples JSON Response for FileSha256Hash { "CurrentPage": 1, "TotalPages": 1, "Captures": [ { "NSSId": "NSS-2016-XXXX", "DetectionDate": " T11:04:18", "InstalledApplication": "Internet Explorer 9", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "CN", "SourceIp": " ", "Files": [ { "Name": "KM2016_z907.exe", "Md5Hash": "B934D82E48DC4CED250EAEA85BF0E64F", "Sha1Hash": "00B5FF620F80765D77E1B98363C A", "Sha256Hash": "2AC182E7A50CFA8113C6ADE2CCFBAA1CE06F7F4F1AAC DA1F2FF1A9339" }, GET Captures by NetworkPort import requests url = " querystring = {"NetworkPort":"80"} headers = { 'authorization': "Basic xxxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi=", 'cache-control': "no-cache" } response = requests.request("get", url, headers=headers, params=querystring) print(response.text)

51 Chapter 12 JSON Response for NetworkPort { "CurrentPage": 1, "TotalPages": 81, "Captures": [{ "NSSId": "NSS-2016-XXXX", "DetectionDate": " T19:57:27", "InstalledApplication": "Internet Explorer 10", "TargetedApplication": "Internet Explorer 10", "Platform": "Windows 8", "Browser": "Internet Explorer 10", "SourceUri": " "SourceCountry": "JP", "SourceIp": "103.1.xxx.74", "Files": [{ "Name": "d.exe", "Md5Hash": "44F ACFF223E9BA59BD4C7DF6", "Sha1Hash": "562EF55FB6ACFE39763EF1F7DD8E8875C493B28D", "Sha256Hash": "C6BF48761E85EB58638EBC5738D3C F25B0D45DB15CCD28C466A95AD" } GET Captures by NetworkIP import requests url = " querystring = {"SourceIp":" "} headers = {'authorization': 'Basic xxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi='} response = requests.request("get", url, headers=headers, params=querystring) print(response.text)

52 Chapter 12: Python Code Examples JSON Response for NetworkIP { "CurrentPage": 1, "TotalPages": 1, "Captures": [{ "NSSId": "NSS-2015-XXXX", "DetectionDate": " T15:19:43", "InstalledApplication": "Adobe Reader 8.1.1", "TargetedApplication": "Internet Explorer 9", "Platform": "Windows 7 SP1", "Browser": "Internet Explorer 9", "SourceUri": " "SourceCountry": "KR", "SourceIp": " ", "Files": [{ "Name": "Uninstall.vbs", "Md5Hash": "N/A ", "Sha1Hash": "N/A ", "Sha256Hash": "N/A " }, { "Name": "h3sdb.exe", "Md5Hash": "C598DB096B1D21709D147245B3E43961", "Sha1Hash": "4E95FD61CD4D48F49CBD8CA38BA8D5EC44B358F8", "Sha256Hash": "71027D89213B8C94604BAD73967CDE6962D59F4A49A239056BC671CE6FE9A681" }, { "Name": "Elvvi.exe", "Md5Hash": "A77A46D F02DD298D0FFE2BA3", "Sha1Hash": "F D24759E898EA96B29E71A1D4BA051A92", "Sha256Hash": "FB55EA41A0D6DA2CEC8ECF BE6AD1F8CFE8291F5EB372B56BE1E2E1CA5" } URL Scan Submission import requests url = " headers = { 'url': " 'browserpackage': "Internet Explorer 9", 'platform': "Windows7", 'authorization': "Basic xxxxxxxxxficzpfqkrbndqwmjrfnee0qundqtq2rtq2otywqkq2nja3ng==", 'content-type': "application/x-www-form-urlencoded", } response = requests.request("post", url, headers=headers) print(response.text)

53 Chapter 12 URL Scan Status import requests url = " headers = { 'authorization': "Basic xxxxxxxxntdcotbcndhfrejbotm5rdk1qky3rda3odi=", } response = requests.request("get", url, headers=headers) print(response.text) URL Scan Result import requests url = " headers = {'authorization': 'Basic xxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi='} response = requests.request("get", url, headers=headers) print(response.text) File Scan Submission import requests url = " payload = "------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"file\"; filename=\"testfile.pdf\"\r\ncontent-type: application/pdf\r\n\r\n\r\n WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"template\"\r\n\r\n1\r\n------webkitformboundary7ma4ywxktrzu0gw--" headers = { 'content-type': "multipart/form-data; boundary=--webkitformboundary7ma4ywxktrzu0gw", 'authorization': "Basic xxxxxxxxxxxxxxxxxxxxxxxqky3rda3odi=", } response = requests.request("post", url, data=payload, headers=headers) print(response.text)

54 Chapter 12: Python Code Examples File Scan Status import requests url = " headers = {'authorization': 'Basic xxxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi='} response = requests.request("get", url, headers=headers) print(response.text) File Scan Result import requests url = " headers = {'authorization': 'Basic xxxxxx6ote0rkfcntdcotbcndhfrejbotm5rdk1qky3rda3odi='} response = requests.request("get", url, headers=headers) print(response.text)