Application Bundle Module¶

The Lastline Analyst API allows detailed customization of the analysis environment via so-called application bundles. These bundles consist of one or more artifacts plus analysis metadata that describes the analysis environment and how to invoke the analysis subject.

The analysis system currently supports three types of bundles:

Program bundles allow specifying the exact command line, with which the analysis is invoked.
Web replay bundles allow replaying captured network traffic during the analysis of a web subject.
Document bundles allow customizing the way Microsoft Office opens a document and allows providing a set of password candidates. While the module allows creating this type of bundles manually, it is more convenient to set the password_candidates parameter as part of the file submission in a call to submit_file() to achieve the same result.

A Python module for creating bundles is available for download as ZIP archive and contains files

which can be used via the command-line tool lastline_appbundle_create.py.

Specifying custom command line arguments¶

The API allows a user to specify command line arguments or to load/invoke an analysis subject through another application. This can be achieved using application bundles.

To create a simple application bundle, use the command-line tool:

$ python lastline_appbundle_create.py -a /path/to/subject 'C:\virtual\path\to\subject.exe' -- 'C:\virtual\path\to\subject.exe' arg1 arg2

The command-line tool provides the same options as the Python helper module, but the latter can be used directly to automate application bundle creation when using the Python API client:

import logging
import llappbundle.helper

# Create a logger object to be used by the appbundle creator
log = logging.getLogger()

# In all examples, the output of the create_appbundle function is a
# binary stream like object, similar to what you get when using the 'open' function
# filenames must be utf-8 encodable str type.

# Example 1: Launch an application in a specific folder
#
# To launch a program with a specific working directory, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "main_subject" parameter to specify the virtual filename of the main analysis
#   subject (one of the elements in the "files" dictionary), and the
# * "run_directory" parameter (optional) to specify the working directory in which
#   to launch the analysis.
example1 = llappbundle.helper.create_appbundle(
    files={r"C:\virtual\path\to\subject.exe": open("/path/to/subject", 'rb')},
    main_subject=r"C:\virtual\path\to\subject.exe",
    run_directory=r"C:\path\to\run\in",
    logger=log)

# Example 2: Launch an application with specific command-line arguments.
#
# To launch a program with specific arguments, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "main_subject" parameter to specify the virtual filename of the main analysis
#   subject (one of the elements in the "files" dictionary),
# * "run_directory" parameter (optional) to specify the working directory in which
#   to launch the analysis,
# * "executable" parameter, pointing to the main_subject, and the
# * "arguments" parameter specifying the arguments to pass to the analysis subject.
example2 = llappbundle.helper.create_appbundle(
    files={r"C:\virtual\path\to\subject.exe": open("/path/to/subject", 'rb')},
    main_subject=r"C:\virtual\path\to\subject.exe",
    executable=r"C:\virtual\path\to\subject.exe",
    arguments=["--arg1", "--arg2"],
    logger=log)

# Example 3: Start the anaylsis subject via the command shell (cmd.exe).
#
# To launch a program via cmd.exe, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "main_subject" parameter to specify the virtual filename of the main analysis
#   subject (one of the elements in the "files" dictionary),
# * "run_directory" parameter (optional) to specify the working directory in which
#   to launch the analysis,
# * "executable" parameter pointing to cmd.exe, and the
# * "arguments" parameter specifying the arguments to pass to executable ("cmd.exe").
example3 = llappbundle.helper.create_appbundle(
    files={r"C:\virtual\path\to\subject.exe": open("/path/to/subject", 'rb')},
    main_subject=r"C:\virtual\path\to\subject.exe",
    executable=r"C:\Windows\system32\cmd.exe",
    arguments=["/c", "C:\\virtual\\path\\to\\subject.exe", "arg"],
    logger=log)

# Example 4: Invoke a specific function inside a DLL (via rundll32.exe).
#
# To launch a program via rundll32.exe, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "main_subject" parameter to specify the virtual filename of the main analysis
#   subject (one of the elements in the "files" dictionary),
# * "executable" parameter, and use "rundll32.exe" to indicate that this is the
#   program to launch, and the
# * "arguments" parameter specifying the command-line for rundll32.exe, providing
#   the function to invoke/use as entrypoint ("function1") as well as the arguments
#   to pass to the function ("arg1" and "arg2").
example4 = llappbundle.helper.create_appbundle(
    files={r"C:\virtual\path\subject.dll": open("/path/to/subject", 'rb')},
    main_subject=r"C:\virtual\path\subject.dll",
    executable=r"C:\Windows\system32\rundll32.exe",
    arguments=[r"C:\virtual\path\subject.dll,function1", "arg1", "arg2"],
    logger=log)

# Example 5: Provide additional files
#
# To launch a program and provide an additional file as parameter, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#    inside the analysis system) to the file-content (a local file-stream),
# * "main_subject" parameter to specify the virtual filename of the main analysis
#    subject (one of the elements in the "files" dictionary),
# * "executable" parameter. As above, the template could be used but it can also be
#    defined as full path since we specified it with *filename*
# * "arguments" parameter specifying the arguments to pass to the analysis subject,
#    and the
# * "additional_files" parameter specifying additional files that should be copied
#    to the analysis environment
example5 = llappbundle.helper.create_appbundle(
    files={
        r"C:\virtual\path\to\subject.exe": open("/path/to/subject", 'rb'),
        r"C:\somewhere\else.ini": open("/path/to/config", 'rb')
    },
    executable=r"C:\virtual\path\to\subject.exe",
    main_subject=r"C:\virtual\path\to\subject.exe",
    arguments=["--read", "C:\\somewhere\\else.ini"],
    logger=log)

# Example 6: A WScript file set as main subject launching it with wscript.exe
#
# In this example we have the following set up:
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "test.vbs" is the VBS file we want to analyze
# * "executable" is the name of the executable that will launch the main subject
# * "main_subject" parameter to specify the virtual filename of the main analysis
#    subject (one of the elements in the "files" dictionary),
# * "arguments" is the arguments that will be used when launching the executable
#   in the system
example6 = llappbundle.helper.create_appbundle(
    files={r'test.vbs': open('test.vbs', 'r')},
    main_subject=r'test.vbs',
    executable=r'C:\Windows\system32\wscript.exe',
    arguments=[r'test.vbs'],
)

# Example 7: Setting environment variables in the system that will run the analysis
# of the bundle
#
# In this example we have the following set up:
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "test.vbs" is the VBS file we want to analyze
# * "executable" is the name of the executable that will launch the main subject
# * "main_subject" parameter to specify the virtual filename of the main analysis
#    subject (one of the elements in the "files" dictionary),
# * "arguments" is the arguments that will be used when launching the executable
#   in the system
# * "registry_values" is a list with registry values to set in the environment
#   before running the analysis.
reg_to_set = llappbundle.RegistryValue(
    path=r'HKEY_CURRENT_USER\Environment',
    name='Lastline',
    type='REG_SZ',
    value='test'
)
example7 = llappbundle.helper.create_appbundle(
    files={
        r"test.vbs": open('test.vbs', 'r')
    },
    main_subject=r'test.vbs',
    executable=r'C:\Windows\system32\wscript.exe',
    arguments=[r'test.vbs'],
    registry_values=[reg_to_set],
)

# Example 8: Executing command in the system that will run the analysis of the
# bundle after some additional commands
#
# In this example we have the following set up:
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames
#   inside the analysis system) to the file-content (a local file-stream),
# * "test.vbs" is the VBS file we want to analyze
# * "executable" is the name of the executable that will launch the main subject
# * "main_subject" parameter to specify the virtual filename of the main analysis
#    subject (one of the elements in the "files" dictionary),
# * "arguments" is the arguments that will be used when launching the executable
#   in the system
# * "preparation_commands" is a list with commands to run in the environment
#   before running the analysis.
set_date = llappbundle.Command(
    filename=None,
    executable='C:\windows\system32\cmd.exe',
    parameters=['/c', 'date', '11-19-2019'],
    run_directory=r'C:\Windows'
)
example8 = llappbundle.helper.create_appbundle(
    files={
        r"test.vbs": open('test.vbs', 'r')
    },
    main_subject=r'test.vbs',
    executable=r'C:\Windows\system32\wscript.exe',
    arguments=[r'test.vbs'],
    preparation_commands=[set_date],
)

Replaying traffic of pcaps for web analysis runs¶

Web replay bundles combine a traffic capture file (pcap) and a web subject, i.e. an URL or a HTML/JavaScript file. When a web replay bundle is submitted, the analysis engine requests the analysis subject specified in the bundle; if the subject references any external resource (e.g., scripts, stylesheets, or images), they are extracted from the capture file (instead of fetching them from their original location). This allows one to “replay” a web session that was recorded in a pcap file. Notice that web replay bundles are handled only by the instrumented browser engine.

To create a web replay bundle, use the python helper module:

import logging
import llappbundle.helper

# Create a logger object to be used by the appbundle creator
log = logging.getLogger()

# In all examples, the output of the create_web_replay* functions is a
# binary stream like object, similar to what you get when using the 'open' function

# Example 1: Create an appbundle with URL subject
#
# To create an web replay appbundle, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames inside the
#   analysis system) to the file-content (a local file-stream),
# * "pcap" parameter to specify the virtual filename of the pcap (one of the elements in the
#    "files" dictionary)
# * "main_subject" parameter to specify the subject URL as a string
example1 = llappbundle.helper.create_web_replay_bundle_with_url(
    files={r"traffic.pcap": open("/path/to/pcap", "rb")},
    pcap=r"traffic.pcap",
    main_subject=r"http://example.com",
    logger=log)

# Example 2: Create an appbundle with a file subject
#
# To create an web replay appbundle, provide the
# * "files" parameter (providing a dictionary), mapping virtual filenames (filenames inside the
#   analysis system) to the file-content (a local file-stream),
# * "pcap" parameter to specify the virtual filename of the pcap (one of the elements in the
#    "files" dictionary)
# * "main_subject" parameter to specify the virtual filename of the main analysis subject (one
#    of the elements in the "files" dictionary),
example2 = llappbundle.helper.create_web_replay_bundle_with_file(
    files={
        r"traffic.pcap": open("/path/to/pcap", "rb"),
        r"subject.html": open(r"/path/to/subject", "rb")},
    pcap="traffic.pcap",
    main_subject="subject.html",
    logger=log)

Application Bundle Module¶

Specifying custom command line arguments¶

Replaying traffic of pcaps for web analysis runs¶

Table of Contents

Previous topic