<commit_before>=================
Analysis Packages
=================

The **analysis packages** are a core component of Cuckoo Sandbox.
They consist in structured Python classes which, executed in the guest machines,
describe how Cuckoo's analyzer component should conduct the analysis.

Cuckoo provides some default analysis packages that you can use, but you are
able to create your own or eventually modify the existing ones.
You can find them located at *analyzer/windows/modules/packages/*.

As described in :doc:`../usage/submit`, you can specify some options to the
analysis packages in the form of ``key1=value1,key2=value2``. The existing analysis
packages already include some default options that can be enabled.

Following is the list of existing packages in alphabetical order:

    * ``applet``: used to analyze **Java applets**.

                  **Options**:
                     * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                     * ``class``: specify the name of the class to be executed. This option is mandatory for a correct execution.

    * ``bin``: used to analyze generic binary data, such as **shellcodes**.

    * ``dll``: used to run and analyze **Dinamically Linked Libraries**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``function``: specify the function to be executed. If none is specified, Cuckoo will try to run ``DllMain``.

    * ``doc``: used to run and analyze **Microsoft Word documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``exe``: default analysis package used to analyze generic **Windows executables**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``arguments``: specify any command line argument to pass to the initial process of the submitted malware.

    * ``ie``: used to analyze **Internet Explorer**'s behavior when opening the given URL.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``jar``: used to analyze **Java JAR** containers.

                  **Options**:
                     * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                     * ``class``: specify the path of the class to be executed. If none is specified, Cuckoo will try to execute the main function specified in the Jar's MANIFEST file.

    * ``pdf``: used to run and analyze **PDF documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``xls``: used to run and analyze **Microsoft Excel documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``zip``: used to run and analyze **Zip archives**. The archive must be either password-less or the password must be "*infected*".

               **Options**:
                   * ``file``: specify the name of the file contained in the archive to execute. If none is specified, Cuckoo will try to execute *sample.exe*.
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``arguments``: specify any command line argument to pass to the initial process of the submitted malware.

You can find more details on how to start creating new analysis packages in the
:doc:`../customization/packages` customization chapter.

As you already know, you can select which analysis package to use by specifying
its name at submission time (see :doc:`submit`) like following::

    $ ./utils/submit.py --package <package name> /path/to/malware

If none is specified, Cuckoo will try to detect the file type and select
the correct analysis package accordingly. If the file type is not supported by
default the analysis will be aborted, therefore you are always invited to
specify the package name whenever it's possible.

For example, to launch a malware and specify some options you can do::

    $ ./utils/submit.py --package dll --options function=FunctionName /path/to/malware.dll
<commit_msg>Update zip package doc with password option<commit_after>=================
Analysis Packages
=================

The **analysis packages** are a core component of Cuckoo Sandbox.
They consist in structured Python classes which, executed in the guest machines,
describe how Cuckoo's analyzer component should conduct the analysis.

Cuckoo provides some default analysis packages that you can use, but you are
able to create your own or eventually modify the existing ones.
You can find them located at *analyzer/windows/modules/packages/*.

As described in :doc:`../usage/submit`, you can specify some options to the
analysis packages in the form of ``key1=value1,key2=value2``. The existing analysis
packages already include some default options that can be enabled.

Following is the list of existing packages in alphabetical order:

    * ``applet``: used to analyze **Java applets**.

                  **Options**:
                     * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                     * ``class``: specify the name of the class to be executed. This option is mandatory for a correct execution.

    * ``bin``: used to analyze generic binary data, such as **shellcodes**.

    * ``dll``: used to run and analyze **Dinamically Linked Libraries**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``function``: specify the function to be executed. If none is specified, Cuckoo will try to run ``DllMain``.

    * ``doc``: used to run and analyze **Microsoft Word documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``exe``: default analysis package used to analyze generic **Windows executables**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``arguments``: specify any command line argument to pass to the initial process of the submitted malware.

    * ``ie``: used to analyze **Internet Explorer**'s behavior when opening the given URL.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``jar``: used to analyze **Java JAR** containers.

                  **Options**:
                     * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                     * ``class``: specify the path of the class to be executed. If none is specified, Cuckoo will try to execute the main function specified in the Jar's MANIFEST file.

    * ``pdf``: used to run and analyze **PDF documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``xls``: used to run and analyze **Microsoft Excel documents**.

               **Options**:
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.

    * ``zip``: used to run and analyze **Zip archives**.

               **Options**:
                   * ``file``: specify the name of the file contained in the archive to execute. If none is specified, Cuckoo will try to execute *sample.exe*.
                   * ``free`` *[yes/no]*: if enabled, no behavioral logs will be produced and the malware will be executed freely.
                   * ``arguments``: specify any command line argument to pass to the initial process of the submitted malware.
                   * ``password``: specify the password of the archive. If none is specified, Cuckoo will try to extract the archive without password or use the password "*infected*".

You can find more details on how to start creating new analysis packages in the
:doc:`../customization/packages` customization chapter.

As you already know, you can select which analysis package to use by specifying
its name at submission time (see :doc:`submit`) like following::

    $ ./utils/submit.py --package <package name> /path/to/malware

If none is specified, Cuckoo will try to detect the file type and select
the correct analysis package accordingly. If the file type is not supported by
default the analysis will be aborted, therefore you are always invited to
specify the package name whenever it's possible.

For example, to launch a malware and specify some options you can do::

    $ ./utils/submit.py --package dll --options function=FunctionName /path/to/malware.dll

{'fraction_non_alphanumeric': 0.09822086535424782, 'fraction_numerical': 0.0008421939151489631, 'mean_word_length': 2.8337368845843423, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2468473', 'n_tokens_mistral': 2333, 'n_tokens_neox': 2151, 'n_words': 1213}