Submission Helper Scripts

We provide two simple command-line programs that use the Lastline Analyst API and the Analyst API client to analyze artifacts (files or URLs) from a specified directory, and to wait for and fetch the analysis results.

The analyze_files and analyze_urls code is available as Python script at analyze_files.py and analyze_urls.py or as stand-alone windows executable at analyze_files.exe and analyze_urls.exe.

Requirements

analyze_files and analyze_urls need a configuration file with API credentials. By default, this should be in a file called license.ini in the directory where the tool is run.

A license.ini file looks like this:

[analysis_api]
key=XXXXXXXXXXXXXXX
api_token=yyyyyyyyyyyyyy

Here, XXX and yyy need to be replaced with your API key and token respectively.

By default, the tool will connect to the API hosted in the Lastline datacenters. To use it with an API running on an On-Premises system, please use the –api-url parameter to point the code to correct API location or specify the optional url parameter in the configuration file.

Windows Executable

The windows executable analyze_files.exe and analyze_urls.exe are self-contained, and have no other requirements. It has been tested on Windows XP, Windows 7, and Windows 10.

Python Script

The Python script analyze_files.py and analyze_urls.py have some additional requirements. See requirements for analysis_apiclient.

It also needs to be able to import the analysis_apiclient module. This requires to either create a Python module - essentially a directory with the following contents to be in the Python search path:

llapi_client/
    __init__.py (may be an empty file)
    analysis_apiclient.py

or to place the analysis_apiclient.py in the current working directory (the tool will automatically attempt to load modules from there).

analyze_files: Usage

Submit one file for analysis, and write analysis results to RESULTS_DIRECTORY:

  • python analyze_files.py RESULTS_DIRECTORY FILE OR
  • analyze_files.exe RESULTS_DIRECTORY FILE

Submit all files in a directory for analysis, and write analysis results to RESULTS_DIRECTORY:

  • python analyze_files.py RESULTS_DIRECTORY DIRECTORY OR
  • analyze_files.exe RESULTS_DIRECTORY DIRECTORY

To find files to submit recursively, specify the –recursive option.

To add submissions done using the API to the web-portal, refer to the –portal-account parameter.

The tool also allows various other options, such as filtering files by file-extension or file size. For details, refer to the detailed usage by invoking the tool with the –help option.

For demonstration purposes, this tool downloads analysis results in both JSON and XML formats.

Here is an example of using the stand-alone executable on windows XP:

C:\data\lastline>dir

19.04.2012  02:58    <DIR>          .
19.04.2012  02:58    <DIR>          ..
04.04.2012  01:14         4.395.065 analyze_files.exe
19.04.2012  02:58    <DIR>          files
03.04.2012  21:56                78 license.ini

C:\data\lastline>analyze_files.exe

C:\data\lastline>analyze_files.exe results files
-> Testing connectivity to Lastline analysis API server
-> Successfully connected to Lastline analysis API server
-> Submitting file notepad.exe (md5=600e0cdc7f68e8ade5f14ae3c35a9320, sha1=7fd96f118a9863c7d8a8a0162b1c95978c92e747,
    sha256=949dc04be394ff45d1ffda9cf99f5400d820cc77070d8e46fbaeb37f15e9de82)
-> Submitting file winhelp.exe (md5=72fa7039f8ae0735579f7b399d6cb22f, sha1=9daa7cd89285fe0e4909546f578ab57b85baaca6,
    sha256=6721ae82935d9b13cda142420bb6c55b0256dd38a5b57ecd1644b48ca37332a4)
-> Done waiting for completion of 2 submissions
-> Done fetching results for all tasks.

C:\data\lastline>dir results

19.04.2012  03:01    <DIR>          .
19.04.2012  03:01    <DIR>          ..
19.04.2012  03:01               674 analysis.log
19.04.2012  03:01               208 error.log
19.04.2012  03:01                84 notepad.exe_62e91774ae63440aae5c45c97db551af_analysis_tags.json
19.04.2012  03:01               134 notepad.exe_62e91774ae63440aae5c45c97db551af_analysis_tags.xml
19.04.2012  03:01               108 notepad.exe_62e91774ae63440aae5c45c97db551af_report_url.json
19.04.2012  03:01             8.710 notepad.exe_62e91774ae63440aae5c45c97db551af_result.json
19.04.2012  03:01            10.138 notepad.exe_62e91774ae63440aae5c45c97db551af_result.xml

19.04.2012  03:01                63 winhelp.exe_14ab96a9d326454298ddb79479e00601_analysis_tags.json
19.04.2012  03:01                98 winhelp.exe_14ab96a9d326454298ddb79479e00601_analysis_tags.xml
19.04.2012  03:01                74 winhelp.exe_14ab96a9d326454298ddb79479e00601_report_url.json
19.04.2012  03:01               165 winhelp.exe_14ab96a9d326454298ddb79479e00601_result.json
19.04.2012  03:01               242 winhelp.exe_14ab96a9d326454298ddb79479e00601_result.xml

analyze_urls: Usage

The URLs to submit for analysis can be read from a file, one URL per line. The file looks like this:

https://some.url
https://lastline.com
https://some-other.url

Submit one file for analysis, and write URL analysis results to RESULTS_DIRECTORY:

  • python analyze_urls.py --from-file URL_FILE RESULTS_DIRECTORY OR
  • analyze_urls.exe --from-file URL_FILE RESULTS_DIRECTORY

Submit one or more URLs for analysis, and write analysis results to RESULTS_DIRECTORY:

  • python analyze_urls.py RESULTS_DIRECTORY URL1 URL2 ... OR
  • analyze_urls.exe RESULTS_DIRECTORY URL1 URL2 ...

It is also possible to specify URLs from file and the command line at once, and write analysis results to RESULTS_DIRECTORY:

  • python analyze_urls.py --from-file URL_FILE RESULTS_DIRECTORY URL1 URL2 ... OR
  • analyze_urls.exe --from-file URL_FILE RESULTS_DIRECTORY URL1 URL2 ...

The tool also allows various other options. For details, refer to the detailed usage by invoking the tool with the –help option.

For demonstration purposes, this tool downloads analysis results in both JSON and XML formats.

Here is an example of using the stand-alone executable on windows XP:

C:\data\lastline>dir

19.04.2012  02:58    <DIR>          .
19.04.2012  02:58    <DIR>          ..
04.04.2012  01:14         4.395.065 analyze_urls.exe
19.04.2012  02:58                15 file.txt
03.04.2012  21:56                78 license.ini

C:\data\lastline>analyze_urls.exe

C:\data\lastline>analyze_urls.exe --from-file file.txt results
-> Testing connectivity to Lastline analysis API server
-> Successfully connected to Lastline analysis API server
-> Submitting 1 URLs
-> Submitting URL http://some.url
-> Done waiting for completion of 1 submissions
-> Done fetching results for all tasks.

C:\data\lastline>dir results

19.04.2012  03:01    <DIR>          .
19.04.2012  03:01    <DIR>          ..
19.04.2012  03:01               674 analysis.log
19.04.2012  03:01               208 error.log
19.04.2012  03:01                94 some.url_5c2ec595e95e00100b4e97f4db321f3d_analysis_tags.json
19.04.2012  03:01               144 some.url_5c2ec595e95e00100b4e97f4db321f3d_analysis_tags.xml
19.04.2012  03:01               118 some.url_5c2ec595e95e00100b4e97f4db321f3d_report_url.json
19.04.2012  03:01               731 some.url_5c2ec595e95e00100b4e97f4db321f3d_result.json
19.04.2012  03:01               958 some.url_5c2ec595e95e00100b4e97f4db321f3d_result.xml