NSX Network Detection and Response - Lastline Analyst API Quick Start Guide
search cancel

NSX Network Detection and Response - Lastline Analyst API Quick Start Guide

book

Article ID: 323955

calendar_today

Updated On:

Products

VMware

Issue/Introduction

NSX Lastline Analyst API Examples

 

NSX Lastline Documentation

https://analysis.lastline.com/docs/html/

https://analysis.lastline.com/docs/html/api.html#api.analysis.submit_file

https://analysis.lastline.com/docs/html/api.html#api.analysis.submit_url

 

NSX Lastline Sample Python Code

https://analysis.lastline.com/docs/html/analysis_client.html#api-client

 

Authentication

For authentication, all Lastine API methods require two parameters: 

key: Lastline Analyst API Key

api_token: secret Lastline API token

 

Hosted Authentication Example:

python analysis_apiclient.py <API Key> <API Token> 

On-Premise Authentication Example:

python analysis_apiclient.py --api-url https://analyst.lastline.local/ <API Key> <API Token>

(analyst.lastline.local is the FQDN of the on-premise server. Alternatively, the server IP address can be used.)

Note: Auto complete using tab can be used to see the available options.

--------------------------------------

NSX Lastline Analyst API shell

--------------------------------------

The 'analysis' object is an AnalysisClient, which can be used to access the functionality

of the NSX Lastline Analysis API.

This is an IPython shell, so you can take advantage of tab auto-completion and other

convenient features of IPython.

In [1]: analysis.

analysis.DATETIME_FMT            analysis.get_completed           analysis.set_key

analysis.DATE_FMT                analysis.get_license_activity    analysis.submit_exe_file

analysis.ERRORS                  analysis.get_progress            analysis.submit_exe_hash

analysis.FORMATS                 analysis.get_result              analysis.submit_file

analysis.SUB_APIS                analysis.get_result_artifact     analysis.submit_file_hash

analysis.analyze_sandbox_result  analysis.get_result_summary      analysis.submit_file_metadata

analysis.completed               analysis.rescore_task            analysis.submit_url

 

File Submission Examples

Submit File

In [1]: analysis.submit_file(file(‘abcd.exe’))

Out[1]: {u'data': {u'task_uuid': u'92bf0182b6e74d548419830cc13d3fe0'}, u'success': 1}

Get Result of File Submission 

In [2]: analysis.get_result(‘92bf0182b6e74d548419830cc13d3fe0')

Get Result Summary of File Submission

In [3]: analysis.get_result_summary(‘92bf0182b6e74d548419830cc13d3fe0')

Submit File with Analysis Environment Variable

In [1]: analysis.submit_file(file(‘myfile.docx’), analysis_env='windows7:office2007')

How to Use Get Completed

In [3]: analysis.get_completed('2014-7-12')

Out[3]: 

{u'data': {u'after': u'2014-07-12 00:00:00',

  u'before': u'2014-10-15 11:21:41',

  u'more_results_available': 1,

  u'tasks': [u'0003bd32b63f4ca887f92ca59c6021eb',

   u'0005b52103ff4902a4002a76674f58f4',

   u'000cde7e631c4dfb9f650e33fdb9c1a1',

   u'000d75c9cfda4bd9a7a2c72f99bafff6',

   u'0016cc058de3405fb67f515acf4a6749',

 
Submit URL

In [38]: analysis.submit_url("www.lastline.com")
 

File Hash Submission Example

Submit File Hash

In [3]: analysis.submit_file_hash('1236427d47489e4a24810b0fc1b31cc9')

Out[3]: {u'data': {u'task_uuid': u'f8fa504dca124c8096d7a504eefd3b9c'}, u'success': 1}

 

Get Progress of File Hash Submission

In [15]: analysis.get_progress('f8fa504dca124c8096d7a504eefd3b9c')

Out[15]: {u'data': {u'completed': 1, u'progress': 100}, u'success': 1}

 

Get Result of File Hash Submission

In [16]: analysis.get_result('f8fa504dca124c8096d7a504eefd3b9c')

Out[16]: 

{u'data': {u'analysis_subject': {u'md5': u'1236427d47489e4a24810b0fc1b31cc9',

   u'mime_type': u'application/x-lastline-test; charset=binary',

   u'sha1': u'acc5ac030c36ee72a8f08e4200de226f8e1b4c0e'},

  u'malicious_activity': [u'Autostart: Registering a dll for automatic loading in user applications',

   u'Evasion: Possibly stalling against analysis environment (sleep)',

   u'Memory: Writing to the memory of a non-child running process',

   u'Signature: Lastline Demo Malware',

   u'Evasion: Searching for specific processes: explorer.exe (system injection target)',

   u'Memory: Replacing the image of another process (detection evasion or privilege escalation)',

   u'File: Modifying executable in Windows directory'],

  u'report': {u'analysis_metadata': [{u'analysis_reason': u'Observed code execution

 

How to Query a File MD5 Hash

In [2]: analysis.query_file_hash(md5='5186ede94913e03c5a4c3acda73e46b0')

Out[2]: 

{u'data': {u'files_found': 1,

  u'tasks': [{u'file_md5': u'5186ede94913e03c5a4c3acda73e46b0',

    u'file_sha1': u'cab3e833995ae959fefa8f22a326878cf62d6c2b',

    u'score': 99,

    u'task_uuid': u'd777c455dcb4471e8cb258adcb1b7b1c'}]},

 u'success': 1}

 ______________________

Please see the example below. Once the UUID is known, additional research can be performed using NSX Lastline Malscape. 

https://user.lastline.com/portal#/analyst/task/d777c455dcb4471e8cb258adcb1b7b1c/overview

 

How to Query to Determine if a File Hash Is Blocked

In [4]: analysis.is_blocked_file_hash(md5='5186ede94913e03c5a4c3acda73e46b0')

Out[4]: 

{u'data': {u'decision': u'BLOCK',

  u'file_md5': u'5186ede94913e03c5a4c3acda73e46b0',

  u'file_sha1': u'cab3e833995ae959fefa8f22a326878cf62d6c2b'},

 u'success': 1}

 

How to Add the File/URL/Hash Submission to Web UI History

The API, by default, does not add the submission to the web-UI. However, the API client has an optional argument that can be set that gives the username under which a submission should be added to the web-UI history.

For example:

>> analysis.submit_url("http://www.lastline.com")

submits a URL for analysis using the API, without adding it to the analysis history. 

However, using

>> analysis.submit_url("http://www.lastline.com", push_to_portal_account="[email protected]")

submits the URL and *in addition* adds the submission to the web-UI using the account of John Doe.

 

File Submission Example

In [1]: analysis.submit_file(file('acbd.exe'), push_to_portal_account=“[email protected]”) 

 

File Hash Submission Example

analysis.submit_file_hash('80384e0869bf01d40386772bde1b78cd', push_to_portal_account=“[email protected]”)

Lastline Windows Time Based Reports

The time based report focuses on the timeline of different actions and exposes behavior as a series of events associated with the timestamp when each event was observed.
 

Step1: Submit a file using the API and record the task UUID. The following example uses the UUID '886fd020e4b54e17937070cf9cd7465d'.

 
In [12]: analysis.get_result('886fd020e4b54e17937070cf9cd7465d', full_report_score=-1)
Out[12]: 
{u'data': {u'analysis_subject': {u'md5': u'15e71957d4b09f0aaf346ad9c7ddaf7c',
   u'mime_type': u'application/msoffice-docx',
   u'sha1': u'58f2830c650f8b6ad9f85af76d475cfdaf347410'},
  u'child_tasks': [],
  u'reports': [{u'description': u'Dynamic analysis on Microsoft Windows XP',
    u'relevance': 1.0,
    u'report_uuid': u'2fbffe68406f50553d8d5400f3e3ef9c:4212aafe165cdec26Vy5CXvqqfYSoIKKRn_VWlgoI6ymYq8eq85Cly_4idc',
    u'report_versions': [u'll-int-win',
     u'll-int-win-doc',
     u'll-win-timeline-based',
     u'll-win-doc-timeline-based']},
   {u'description': u'Dynamic analysis on Microsoft Windows 7',
    u'relevance': 1.0,
    u'report_uuid': u'2fbffe68406f50553d8d5400f3e3ef9c:7725704be46c811fsQY6l6n6R5npdgoj4ecrSeZpPjSpS5lhPuhaPpb9QY0',
    u'report_versions': [u'll-int-win',
     u'll-int-win-doc',
     u'll-win-timeline-based',
     u'll-win-doc-timeline-based']}],
  u'score': 0,
  u'submission': u'2015-01-08 14:31:35',
  u'task_uuid': u'886fd020e4b54e17937070cf9cd7465d'},
 u'success': 1}

Step 2. Select one of the available reports and corresponding available report-version (see field "reports").

Example: 
report_uuid: '2fbffe68406f50553d8d5400f3e3ef9c:7725704be46c811fsQY6l6n6R5npdgoj4ecrSeZpPjSpS5lhPuhaPpb9QY0'
report_version: 'll-win-timeline-based'
 
and fetch the data:
 
In [14]: analysis.get_result('886fd020e4b54e17937070cf9cd7465d', report_uuid='2fbffe68406f50553d8d5400f3e3ef9c:7725704be46c811fsQY6l6n6R5npdgoj4ecrSeZpPjSpS5lhPuhaPpb9QY0', report_version='ll-win-timeline-based')
Out[10]: 
{u'data': {u'analysis_subject': {u'md5': u'15e71957d4b09f0aaf346ad9c7ddaf7c',
   u'mime_type': u'application/msoffice-docx',
   u'sha1': u'58f2830c650f8b6ad9f85af76d475cfdaf347410'},
  u'child_tasks': [],
  u'report': {u'analysis_metadata': [{u'analysis_subject_id': 2,
[...]
  u'score': 0,
  u'submission': u'2015-01-08 14:31:35',
  u'task_uuid': u'886fd020e4b54e17937070cf9cd7465d'},
 u'success': 1}

 

Multiple File Submission Example Using analyze_binaries.py Python Script

https://analysis.lastline.com/docs/html/analyze_binaries.html

Python Script Download (analyze_binaries.py)

https://analysis.lastline.com/docs/examples/analyze_binaries.py

In the following example, the malware samples have been placed in the Lastline_Results_Directory. The results of the submissions and log information will be written to the Results_Directory. Also, the file submissions will be uploaded to the web management portal as the —portal-account parameter has been set. Please note that the license.ini file will include the Analyst API key and token. In this example, the license.ini file has been placed in the same directory as the Python script. If the license has been installed in another directory, the -l option can be used.

Sample license.ini file

[analysis_api]

key=xxxxxxxxxxxx

api_token=xxxxxxxxxxx

test@lastline$ python analyze_binaries.py [email protected] Results_Directory Lastline_Results_Directory

Testing connectivity to Lastline analysis API server

OK Successfully connected to Lastline analysis API server!

-> Submitted file Lastline_Results_Directory/1daa165b3b1f4aae975b4a987b172f3e.pdf. Task UUID=ff2186a9b70e49d8836cf140a5ca462d

-> Submitted file Lastline_Results_Directory/3b296623831392b540b6f06644804152. Task UUID=29ff3a62e8f443dea127794a34decd51

-> Submitted file Lastline_Results_Directory/5780287babceb0c797e635aa65832966. Task UUID=2f13eea9f6394bf49d4510257589dd1a

-> Submitted file Lastline_Results_Directory/78fcc8cab19e539a0691b448691e7e70. Task UUID=032882b7569146a49c2cdb066aab74e5

-> Submitted file Lastline_Results_Directory/a44beaa302de0876b7cd2be4aeb6d3bf. Task UUID=40b9da5ad33145bca16d3c2a3b425852

-> Submitted file Lastline_Results_Directory/b235b6e7bc12ac0af8811b1186017047. Task UUID=f33a770599b648bfa85f271536c67f41

-> Submitted file Lastline_Results_Directory/eae627324c173701a4f59f9dccdd324e. Task UUID=61f78469400943ec9b110d6b9e515753

-> Successfully submitted 7 of 7 files for analysis

-> Results for 0 of 7 tasks are ready to be downloaded

-> Got no new results. Waiting 30 seconds.

-> Results for 6 of 7 tasks are ready to be downloaded

-> Successfully fetched results for UUID 032882b7569146a49c2cdb066aab74e5

-> Successfully fetched results for UUID 40b9da5ad33145bca16d3c2a3b425852

-> Successfully fetched results for UUID 2f13eea9f6394bf49d4510257589dd1a

-> Successfully fetched results for UUID 61f78469400943ec9b110d6b9e515753

 

-> Successfully fetched results for UUID 29ff3a62e8f443dea127794a34decd51

-> Successfully fetched results for UUID f33a770599b648bfa85f271536c67f41

-> Results for 1 of 1 tasks are ready to be downloaded

-> Successfully fetched results for UUID ff2186a9b70e49d8836cf140a5ca462d

-> Done fetching results for all tasks.

 


Additional Information

Note: This article is applicable to the standalone NSX Network Detection and Response product (formerly Lastline) and is not intended to be applied to the NSX NDR feature of NSX-T.