Overview

The Lastline Analyst API provides functionality for submitting resources for analysis and obtaining the results. Currently, it supports URLs as well as various types of executables and documents.

Executables are analyzed by running them inside a sandbox, recording the behavior of the program, and classifying the file based on the observed actions. Similarly, documents are opened in an instrumented file-editor/viewer or by analyzing any active components (such as scripts) embedded inside the documents; in either case, the behavior of the code is used for detecting if the file contains any anomalies.

Additionally, the content of a submitted file is analyzed for structural similarities with other, previously classified malware artifacts.

URLs are analyzed by visiting them with special, instrumented browsers and observing actions inside the browser or its interactions with its environment.

The latest version of this documentation can be found at https://analysis.lastline.com/analysis/api-docs/html/overview.html, or downloaded in PDF format from https://analysis.lastline.com/analysis/api-docs/LastlineAnalystAPI.pdf .

Supported Artifacts

The API supports submissions of URLs and files. The maximum file size is 64 MB for the hosted Lastline infrastructure - for On-Premises deployments, the limit is configurable (up to 100MB) and defaults to 10 MB.

The following table provides an overview of the supported file types:

Lastline File Type	Lastline Mime Type	Typical Extensions	Description
AceArchiveFile	application/x-ace	.ace	ACE archive data
BzipArchiveFile	application/x-bzip	.tbz, .tbz2, .bz2, .bz	bzip2 compressed data
CabArchiveFile	application/vnd.ms-cab-compressed	.cab	Microsoft Cabinet archive data
DiagCabArchiveFile	application/vnd.ms-diagcab- compressed	.diagcab	Microsoft Diagnostic Cabinet archive data
OneNotePkgCabArchiveFile	application/vnd.ms-onepkg- compressed	.onepkg	Microsoft OneNote Package
DmgArchiveFile	application/x-apple-diskimage	.dmg, .smi	Apple disk image
Rfc2822EmailArchiveFile	data/email-rfc2822	.eml	RFC2822-formatted Email file
GzipArchiveFile	application/x-gzip	.gz, .tgz	gzip compressed data
JarArchiveFile	application/java-archive	.jar	Java JAR archive
WebappJarArchiveFile	application/war-archive	.war	Java Webapp archive
LhaArchiveFile	application/x-lha	.lzh, .lha	LHa archive data
LzmaArchiveFile	application/x-lzma	.lzma	LZMA compressed data
NugetArchiveFile	application/x-nuget	.nupkg	NuGet package archive
UDFISOArchiveFile	application/x-udf-image	.iso, .udf	UDF filesystem data
ISO9660ISOArchiveFile	application/x-iso9660-image	.iso	ISO 9660 CD-ROM filesystem data
RarArchiveFile	application/x-rar	.rar	RAR archive data
Rar5ArchiveFile	application/x-rar5	.rar	RAR archive data, version 5
TarArchiveFile	application/tar	.tar	POSIX tar archive data
DocumentLLAppBundleTarArchiveFile	application/llappbundle-document	.tar, .llapp, .llappbundle	Lastline Application Bundle Document Type
WindowsExecutableLLAppBundleTarArchiveFile	application/llappbundle-windows- executable	.tar, .llapp, .llappbundle	Lastline Application Bundle Windows Executable Type
WebReplayLLAppBundleTarArchiveFile	application/llappbundle-web-replay	.tar, .llapp, .llappbundle	Lastline Application Bundle Web Replay Type
TnefArchiveFile	application/vnd.ms-tnef	.dat	Transport Neutral Encapsulation Format
XarArchiveFile	application/x-xar	.pkg, .xar	XAR archive data
XzArchiveFile	application/x-xz	.txz, .xz	XZ compressed data
ZipArchiveFile	application/zip	.zip	Zip archive data
SevenZipArchiveFile	application/x-7z-compressed	.7z	7-zip archive data
MicrosoftSettingContentDataFile *	text/ms-settingcontent	.settingcontent-ms	Microsoft Content-Settings data file
CsvDataFile	data/csv	.csv	CSV Data
InternetInquiryDataFile *	text/x-ms-iqy	.iqy	Internet Inquiry data file
SymbolicLinkDataFile	data/symbolic-link	.sylk, .slk	Symbolic Link data file
PcapDataFile	application/vnd.tcpdump.pcap	.pcapng, .pcap	tcpdump capture file
WordHangulCdfDocFile	application/hangul-word	.hwp	Hangul Word Processor document
ChmDocFile	application/x-chm	.chm	Microsoft Windows HtmlHelp data
HangulDocFile *	application/x-hwp	.hwp	Hangul HWP3/HWP2000 document
ExcelMsMimeDocFile	application/msoffice-mime-xls	.xls	Microsoft Excel document in MHTML format
PowerpointMsMimeDocFile	application/msoffice-mime-ppt	.ppt	Microsoft Powerpoint document in MHTML format
WordMsMimeDocFile	application/msoffice-mime-doc	.doc	Microsoft Word document in MHTML format
ExcelMsDocFile	application/msoffice-xls	.xls	Microsoft Office Excel document
TemplateExcelMsDocFile	application/msoffice-xlt	.xlt	Microsoft Office Excel template document
ExcelEncryptedKnownMsDocFile	application/msoffice-xls-encrypted	.xlsx, .xls	Microsoft Office Excel document (with password)
MacroExcelEncryptedKnownMsDocFile	application/msoffice-xlam-encrypted	.xlam	Microsoft Office Excel document (with password), with macros
PowerpointEncryptedKnownMsDocFile	application/msoffice-ppt-encrypted	.pptx, .ppt	Microsoft Office Powerpoint document (with password)
WordEncryptedKnownMsDocFile	application/msoffice-doc-encrypted	.docx, .doc	Microsoft Office Word document (with password)
PowerpointMsDocFile	application/msoffice-ppt	.ppt, .pps	Microsoft Office Powerpoint document
TemplatePowerpointMsDocFile	application/msoffice-pot	.pot	Microsoft Office Powerpoint template document
WordMsDocFile	application/msoffice-doc	.doc	Microsoft Office Word document
PublisherWordMsDocFile	application/msoffice-publisher	.pub	Microsoft Publisher document
TemplateWordMsDocFile	application/msoffice-dot	.dot	Microsoft Office Word document template
OoDocFile	application/vnd.oasis.opendocument	.ott, .otg, .odp, .otp, .odt, .odg, .ods	Open/LibreOffice document
PdfDocFile	application/pdf	.pdf	PDF document
WordPerfectDocFile	application/wordperfect	.wpd	WordPerfect document
RtfDocFile	text/rtf	.rtf	RTF document
SwfDocFile	application/x-shockwave-flash	.swf	Macromedia Flash data
ExcelXmlDocFile	application/x-spreadsheetml	.xml	XML-based Microsoft Office Excel document, pre-Office2007
PowerpointXmlDocFile	application/x-presentationml	.xml	XML-based Microsoft Office Powerpoint presentation, pre-Office2007
WordXmlDocFile	application/x-wordprocessingml	.xml	XML-based Microsoft Office Word document, pre-Office2007
XdpXmlDocFile	application/vnd.adobe.xdp+xml	.xdp	Adobe XDP document
XslXmlDocFile	text/xsl	.xsl	eXtensible Stylesheet Language for XML file
ExcelMsDocxFile	application/msoffice-xlsx	.xlsx	Microsoft Office Excel document, Office Open XML format
MacroExcelMsDocxFile	application/msoffice-xlsm	.xlsm	Microsoft Office Excel document, Office Open XML format, with macros
BinaryMacroExcelMsDocxFile	application/msoffice-xlsb	.xlsb	Microsoft Office Excel document, Office Open XML format, with macros and binary storage
TemplateExcelMsDocxFile	application/msoffice-xltx	.xltx	Microsoft Office Excel template document, Office Open XML format
MacroTemplateExcelMsDocxFile	application/msoffice-xltm	.xltm	Microsoft Office Excel spreadsheet template, Office Open XML format, with macros
PowerpointMsDocxFile	application/msoffice-pptx	.pptx, .ppsx	Microsoft Office Powerpoint document, Office Open XML format
MacroAddInPowerpointMsDocxFile	application/msoffice-ppam	.ppam	Microsoft Office Powerpoint AddIn document, Office Open XML format, with macros
MacroPowerpointMsDocxFile	application/msoffice-pptm	.pptm	Microsoft Office Powerpoint document, Office Open XML format, with macros
SlideshowPowerpointMsDocxFile	application/msoffice-ppsx	.ppsx	Microsoft Office Powerpoint Slideshow, Office Open XML format
MacroSlideshowPowerpointMsDocxFile	application/msoffice-ppsm	.ppsm	Microsoft Office Powerpoint Slideshow, Office Open XML format, with macros
TemplatePowerpointMsDocxFile	application/msoffice-potx	.potx	Microsoft Office Powerpoint template document, Office Open XML format
MacroTemplatePowerpointMsDocxFile	application/msoffice-potm	.potm	Microsoft Office Powerpoint presentation template, Office Open XML format, with macros
WordMsDocxFile	application/msoffice-docx	.docx	Microsoft Office Word document, Office Open XML format
MacroWordMsDocxFile	application/msoffice-docm	.docm	Microsoft Office Word document, Office Open XML format, with macros
TemplateWordMsDocxFile	application/msoffice-dotx	.dotx	Microsoft Office Word template document, Office Open XML format
MacroTemplateWordMsDocxFile	application/msoffice-dotm	.dotm	Microsoft Office Word document template, Office Open XML format, with macros
MsXpsMsDocxFile	application/vnd.ms-xpsdocument	.xps	Microsoft XPS document
OpenXpsMsDocxFile	application/oxps	.oxps	OpenXPS document
JavaClassExeFile	application/x-java-class	.class	compiled Java class data
ComExeFile	application/x-com	.com	COM executable for DOS
EicarComExeFile	application/x-eicar	.com	EICAR test virus
DosExeFile	application/x-dosexec	.exe	MS-DOS executable
ElfExeFile	application/x-elf	.elf	ELF executable
MsInstallerExeFile *	application/x-msi	.msi	Microsoft Installer file
LnkExeFile	application/x-ms-shortcut	.lnk, .url	Microsoft Windows shortcut
MachOExeFile	application/x-mach-o-binary	.bundle, .o, .dylib	Mach-O executable
BundleMachOExeFile	application/x-mach-o-binary-bundle	.bundle	Mach-O executable bundle
ExecutableMachOExeFile	application/x-mach-o-binary- executable	.o	Mach-O executable program
LibraryMachOExeFile	application/x-mach-o-binary-library	.o, .dylib	Mach-O executable library
PeExeFile	application/x-pe	.pif, .bat, .com, .cpl, .exe, .scr, .cmd	PE executable
RarSfxPeExeFile	application/x-rar-sfx-pe	.exe	RAR SFX PE executable
ZipSfxPeExeFile	application/x-zip-sfx-pe	.exe	Zip SFX PE executable
SevenZipSfxPeExeFile	application/x-7zip-sfx-pe	.exe	7zip SFX PE executable
LastlineTestPeExeFile	application/x-lastline-test	.dll, .sys, .exe	Lastline PE test file
MachOFatUniversalExeFile	application/x-mach-o-fat-binary	.bundle, .o, .dylib	Mach-O fat file
TiffImageFile	image/tiff	.tif, .tiff	TIFF image data
SvgXmlImageFile	image/svg	.svg	SVG image data
AmsiJavascriptLogFile	text/javascript-amsi-log	.amsi_js	JavaScript amsi COM log
AmsiVBSLogFile	text/vbscript-amsi-log	.amsi_vbs	VBScript amsi COM log
OneNoteFile	application/onenote	.one	OneNote Document
HTAScriptFile	text/hta	.hta	HTA Script File text
VBAVisualBasicScriptFile	text/vba	.vba	Visual Basic for Applications text
VBSVisualBasicScriptFile	text/vbscript	.vbs	VBScript text
AmsiVBSVisualBasicScriptFile	text/vbscript-amsi	.amsi_vbs	VBScript amsi text
EncodedVBSVisualBasicScriptFile	application/encodedvbscript	.vbe	VBScript encoded script
BatchScriptFile	text/x-msdos-batch	.bat, .cmd	Batch script text
JavascriptScriptFile	application/javascript	.js	JavaScript text
AmsiJavascriptScriptFile	text/javascript-amsi	.amsi_js	JavaScript amsi text
EncodedJavascriptScriptFile	application/encodedjscript	.jse	JScript encoded script
PerlScriptFile	text/x-perl	.pm, .pl	Perl script text
PowershellScriptFile	text/x-powershell	.ps1, .psm1, .psd1	PowerShell text
AmsiPowershellScriptFile	text/x-powershell-amsi	.amsi_ps1	PowerShell amsi text
PythonScriptFile	text/x-python	.py	Python script text
RubyScriptFile	text/x-ruby	.rb	Ruby script text
ShellScriptFile	text/x-shellscript	.sh, .command	Shell script text
WindowsScriptFile	text/x-wsf	.wsf	Windows Script File text
InternetShortcutFile	text/x-internetshortcut	.website, .url	Internet Shortcut file
HtmlTextFile	text/html	.html, .htm	HTML document

* These file types are only supported if the Windows sandbox is configured for the requesting license. NOTE: In some cases, the Lastline mime types shown in the above list represent a unified, generalized version of standard mime types. This allows mapping different, semantically equivalent types into a single type.

The API supports the most common container formats. When submitting an container (archive or ISO, for example) file, the API will automatically attempt to extract and analyze the contained files. More precisely, the API will create a child analysis (for details, see Child Tasks) for files extracted from the container that have a supported file type. Additionally, for multi-file containers containing executables (such as programs or scripts) that should be analyzed as whole, the API attempts to generate program bundles (see Handling of Containers). For encrypted containers (such as encrypted archives), submit_file() allows you to specify a decryption password or list of potential passwords - if none is specified, the API attempts decryption using common industry-standard passwords (such as “infected”).

The API supports the following container types:

Lastline File Type	Lastline Mime Type	Typical Extensions	Description
AceArchiveFile	application/x-ace	.ace	ACE archive data
BzipArchiveFile	application/x-bzip	.tbz, .tbz2, .bz2, .bz	bzip2 compressed data
CabArchiveFile	application/vnd.ms-cab-compressed	.cab	Microsoft Cabinet archive data
DiagCabArchiveFile	application/vnd.ms-diagcab- compressed	.diagcab	Microsoft Diagnostic Cabinet archive data
OneNotePkgCabArchiveFile	application/vnd.ms-onepkg- compressed	.onepkg	Microsoft OneNote Package
GzipArchiveFile	application/x-gzip	.gz, .tgz	gzip compressed data
LhaArchiveFile	application/x-lha	.lzh, .lha	LHa archive data
LzmaArchiveFile	application/x-lzma	.lzma	LZMA compressed data
NugetArchiveFile	application/x-nuget	.nupkg	NuGet package archive
UDFISOArchiveFile	application/x-udf-image	.iso, .udf	UDF filesystem data
ISO9660ISOArchiveFile	application/x-iso9660-image	.iso	ISO 9660 CD-ROM filesystem data
RarArchiveFile	application/x-rar	.rar	RAR archive data
Rar5ArchiveFile	application/x-rar5	.rar	RAR archive data, version 5
TarArchiveFile	application/tar	.tar	POSIX tar archive data
XzArchiveFile	application/x-xz	.txz, .xz	XZ compressed data
ZipArchiveFile	application/zip	.zip	Zip archive data
SevenZipArchiveFile	application/x-7z-compressed	.7z	7-zip archive data
RarSfxPeExeFile	application/x-rar-sfx-pe	.exe	RAR SFX PE executable
ZipSfxPeExeFile	application/x-zip-sfx-pe	.exe	Zip SFX PE executable
SevenZipSfxPeExeFile	application/x-7zip-sfx-pe	.exe	7zip SFX PE executable

NOTE: In some cases, the Lastline mime types shown in the above list represent a unified, generalized version of standard mime types. This allows mapping different, semantically equivalent types into a single type.

Getting Started

The Analyst API is a web-based API. To get started using it, you will need to request an API key and API token from Lastline. These will act as your credentials for accessing the API.

For clients accessing the API hosted in a Lastline datacenter, the API is reachable at https://analysis.lastline.com. For clients using an On-Premises deployment, the API is reachable using the URL https://log.<fqdn>/analysis on Lastline Enterprise Manager or Pinbox appliances, and the URL https://<fqdn>/analysis for Lastline Analyst appliances.

In addition to the full API Reference, this documentation also provides two Sample API Clients for accessing this API. These are written in Python. One of them is also available as a self-contained Microsoft Windows executable.

API Concepts

The Lastline Analyst API is an asynchronous API, in the sense that, when a resource (a file or a URL) is submitted for analysis, the analysis results are typically not returned immediately in the response. Instead, a unique identifier (UUID) for the submitted analysis task is returned. This UUID can later be used in a separate request to get the analysis results for this task.

The reason for this approach is that analyzing a resource can take some time. For instance, analyzing an executable requires running it for several minutes in an analysis sandbox.

However, in some cases the submitted resource may have been already analyzed by the analysis platform. In these cases, the API is able to immediately return an analysis result.

Workflow

The expected usage of this API is to follow these steps:

1. Call submit_file() or submit_url() several times to submit a number of artifacts, and store the returned task UUIDs.

2. Call get_completed() to get the UUIDs of tasks completed since the last time get_completed() was called.

3. Call get_result() on returned UUIDs to obtain results.

4. Repeat steps 2 and 3 until results are available for all UUIDs.

Using the get_completed() function avoids polling for results for each submission individually by repeatedly calling the get_result() function until results are available, which is very inefficient and may be enforced by the API: if a client makes too many calls to get_result() on incomplete tasks, it may be blocked from making further calls due to violations of this protocol.

Note that the submit_file() and submit_url() functions may immediately return an analysis result, in which case the call to get_result() is not necessary (the UUID will still be returned by get_completed()). If a client does not require the detailed analysis results at time of the submission, specify the full_report_score parameter. Further, the API allows submitting a file by-hash if the file is already available in the analysis system, avoiding an unnecessary upload of the file-content; see submit_file() for details.

Handling of Containers

The API analyzes submissions of archives or other containers by treating these types of files as closely as possible to how a real user would: the system tries to understand how a real victim would behave when receiving the file.

For example, when the system finds a document inside an archive, this document is sent for deeper analysis “by itself”, as documents typically are self-contained elements.

A different example is when the API handles archives with multiple programs, or when a program is shipped with additional files (such as configuration files or program libraries). In this case, it is often not meaningful to analyze each program individually, as one would expect the first program to call the other, read the configuration file embedded in the archive, or load the program library. Thus, the program would most likely fail to run successfully if analyzed “by itself” (otherwise one would not expect these files to be distributed together in the same archive).

Thus, the API may analyze this type of container containing multiple files via program bundles: all files in the container are copied into the analysis system, and metadata embedded in the bundle describes how to launch these files. If more than one program is found and the system cannot identify which program to launch as “main” subject of the analysis, multiple bundle analysis runs are triggered.

For details on program bundles, see Application Bundle Module.