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 .tbz2, .tbz, .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 .smi, .dmg Apple disk image
Rfc2822EmailArchiveFile data/email-rfc2822 .eml RFC2822-formatted Email file
GzipArchiveFile application/x-gzip .tgz, .gz 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 .udf, .iso 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 .llappbundle, .llapp, .tar Lastline Application Bundle Document Type
WindowsExecutableLLAppBundleTarArchiveFile application/llappbundle-windows- executable .llappbundle, .llapp, .tar Lastline Application Bundle Windows Executable Type
WebReplayLLAppBundleTarArchiveFile application/llappbundle-web-replay .llappbundle, .llapp, .tar Lastline Application Bundle Web Replay Type
TnefArchiveFile application/vnd.ms-tnef .dat Transport Neutral Encapsulation Format
XarArchiveFile application/x-xar .xar, .pkg XAR archive data
XzArchiveFile application/x-xz .xz, .txz 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 .doc, .docx Microsoft Office Word document (with password)
PowerpointMsDocFile application/msoffice-ppt .pps, .ppt 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 .odp, .ods, .odt, .otg, .otp, .ott, .odg 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 .url, .lnk 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 .bat, .exe, .cpl, .cmd, .pif, .com, .scr 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 .sys, .exe, .dll Lastline PE test file
MachOFatUniversalExeFile application/x-mach-o-fat-binary .bundle, .o, .dylib Mach-O fat file
TiffImageFile image/tiff .tiff, .tif TIFF image data
SvgXmlImageFile * image/svg .svg SVG image data
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 application/javascript-amsi .amsi_js JavaScript amsi text
EncodedJavascriptScriptFile application/encodedjscript .jse JScript encoded script
PerlScriptFile text/x-perl .pl, .pm Perl script text
PowershellScriptFile text/x-powershell .psm1, .psd1, .ps1 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 .url, .website Internet Shortcut file
HtmlTextFile text/html .htm, .html 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 .tbz2, .tbz, .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 .tgz, .gz 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 .udf, .iso 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 .xz, .txz 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.