Commands — Viper 1.2 documentation

# Commands

Viper provides a set of core commands used to interact repositories of files you want to collect. In order to see which commands are available, type `help`:

    shell > help
    Commands:
    +------------+-----------------------------------------------+
    | Command    | Description                                   |
    +------------+-----------------------------------------------+
    | about      | Show information about this Viper instance    |
    | analysis   | View the stored analysis                      |
    | clear      | Clear the console                             |
    | close      | Close the current session                     |
    | copy       | Copy opened file(s) into another project      |
    | delete     | Delete the opened file                        |
    | exit, quit | Exit Viper                                    |
    | export     | Export the current session to file or zip     |
    | find       | Find a file                                   |
    | help       | Show this help message                        |
    | info       | Show information on the opened file           |
    | new        | Create new file                               |
    | notes      | View, add and edit notes on the opened file   |
    | open       | Open a file                                   |
    | parent     | Add or remove a parent file                   |
    | projects   | List or switch existing projects              |
    | rename     | Rename the file in the database               |
    | sessions   | List or switch sessions                       |
    | stats      | Viper Collection Statistics                   |
    | store      | Store the opened file to the local repository |
    | tags       | Modify tags of the opened file                |
    +----------+-------------------------------------------------+

Following are details for all the currently available commands.

## about

The about command can be used to display some useful information regarding the Viper instance you are currently running. This includes the versions of both Viper itself and of your Python installation. Additionally the path of the active configuration file is shown:

    viper > about
    +----------------+-------------------------------------------------+
    | About          |                                                 |
    +----------------+-------------------------------------------------+
    | Viper Version  | 1.3-dev                                         |
    | Python Version | 3.4.3                                           |
    | Homepage       | https://viper.li                                |
    | Issue Tracker  | https://github.com/viper-framework/viper/issues |
    +----------------+-------------------------------------------------+
    +--------------------------+------------------------------------------------+
    | Configuration            |                                                |
    +--------------------------+------------------------------------------------+
    | Configuration File       | /home/user/.viper/viper.conf                   |
    | Storage Path             | /home/user/.viper                              |
    | Current Project Database | Engine(sqlite:////home/user/.viper/viper.db)   |
    +--------------------------+------------------------------------------------+

## projects

As anticipated in the Concepts section, Viper provides a way to create multiple projects which represent isolated collections of files. You can create a project by simply specifying a value to the `--project` argument at launch of `viper-cli`.

From within the Viper shell, you can list the existing projects and switch from one to another by simply using the `projects` command. Following is the help message:

    usage: projects [-h] [-l] [-s=project]

    Options:
        --help (-h) Show this help message
        --list (-l) List all existing projects
        --switch (-s)   Switch to the specified project

Each project will have its own local file repository, its own `viper.db` SQLite database and its own `.viperhistory` file, which is used to record the history of commands you entered in the terminal.

For example, this is how to launch Viper with a specific project:

    nex@nex:$ viper-cli --project test1
             _
            (_)
       _   _ _ ____  _____  ____
      | | | | |  _ \| ___ |/ ___)
       \ V /| | |_| | ____| |
        \_/ |_|  __/|_____)_| v1.1
              |_|

    You have 0 files in your test1 repository
    test1 shell >

From within the terminal, you can see which projects exist:

    test1 shell > projects -l
    [*] Projects Available:
    +--------------+--------------------------+---------+
    | Project Name | Creation Time            | Current |
    +--------------+--------------------------+---------+
    | test1        | Sat Jul 12 00:53:06 2014 | Yes     |
    +--------------+--------------------------+---------+

You can eventually switch to a different one:

    test1 shell > projects --switch test2
    [*] Switched to project test2
    test2 shell >

Note that if you specify a name of a project that doesn’t exist to the `--switch` parameter, Viper will create that project and open it nevertheless.

## open

As explained in the Concepts chapter, Viper supports the concept of session, which is an execution context created when a specific file is opened and closed only when requested by the user. In order to create a session, you need to issue an `open` command. Following is the help message:

    usage: open [-h] [-f] [-u] [-l] [-t] <target|md5|sha256>

    Options:
        --help (-h) Show this help message
        --file (-f) The target is a file
        --url (-u)  The target is a URL
        --last (-l) Open file from the results of the last find command
        --tor (-t)  Download the file through Tor

    You can also specify a MD5 or SHA256 hash to a previously stored
    file in order to open a session on it.

You can fundamentally open:

> - A file available in the local repository
> - Any file available on the local filesystem
> - Any URL

If you don’t specify any option, Viper will interpret the value you provided as an hash it has to look up in the local database, for example:

    shell > open 22f77c113cc6d43d8c12ed3c9fb39825
    [*] Session opened on ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26
    shell poisonivy.exe >

If you want to open a file elsewhere on the filesystem, you need to specify the `--file` (or `-f`) flag:

    shell > open -f /tmp/poisonivy.exe
    [*] Session opened on /tmp/poisonivy.exe

If you want to open an URL you can use the `--url` flag:

    shell > open --url http://malicious.tld/path/to/file.exe
    [*] Session opened on /tmp/tmpcuIOIj
    shell tmpcuIOIj >

If you have Tor running, you can fetch the file through it by additionally specifying `--tor`.

Through the `open` command you can also directly open one of the entries from the results of the last executed `find` command, for example:

    shell > find all
    +---+---------------+-----------------------+----------------------------------+
    | # | Name          | Mime                  | MD5                              |
    +---+---------------+-----------------------+----------------------------------+
    | 1 | poisonivy.exe | application/x-dosexec | 22f77c113cc6d43d8c12ed3c9fb39825 |
    +---+---------------+-----------------------+----------------------------------+
    shell > open --last 1
    [*] Session opened on ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26
    shell poisonivy.exe >

## sessions

You can see which sessions are currently active and eventually switch from one to another through the `sessions` command. Following is the help message:

    usage: sessions [-h] [-l] [-s=session]

    Options:
        --help (-h) Show this help message
        --list (-l) List all existing sessions
        --switch (-s)   Switch to the specified session

An example of execution is the following:

    shell poisonivy.exe > sessions --list
    [*] Opened Sessions:
    +---+---------------+----------------------------------+---------------------+---------+
    | # | Name          | MD5                              | Created At          | Current |
    +---+---------------+----------------------------------+---------------------+---------+
    | 1 | poisonivy.exe | 22f77c113cc6d43d8c12ed3c9fb39825 | 2014-07-12 01:36:14 | Yes     |
    | 2 | zeus.exe      | 9b2de8b062a5538d2a126ba93835d1e9 | 2014-07-12 01:36:19 |         |
    | 3 | darkcomet.exe | 9f2520a3056543d49bb0f822d85ce5dd | 2014-07-12 01:36:23 |         |
    +---+---------------+----------------------------------+---------------------+---------+
    shell poisonivy.exe > sessions --switch 2
    [*] Switched to session #2 on ~/viper/binaries/6/7/6/a/676a818365c573e236245e8182db87ba1bc021c5d8ee7443b9f673f26e7fd7d1
    shell zeus.exe >

## export

The `export` command is used to export the currently opened file to the target path or archive name. You can zip up the file in a new archive too:

    usage: export [-h] [-z] <path or archive name>

    Options:
        --help (-h) Show this help message
        --zip (-z)  Export session in a zip archive

## close

This command simply abandon a session that was previously opened. Note that the session will actually remain available in case you want to re-open it later.

## store

The `store` command is used to store the currently opened file to the local repository. There are many options and filters you can apply, as shown in the following help message:

    usage: store [-h] [-d] [-f <path>] [-s <size>] [-y <type>] [-n <name>] [-t]

    Options:
        --help (-h) Show this help message
        --delete (-d)   Delete the original file
        --folder (-f)   Specify a folder to import
        --file-size (-s)    Specify a maximum file size
        --file-type (-y)    Specify a file type pattern
        --file-name (-n)    Specify a file name pattern
        --tags (-t) Specify a list of comma-separated tags

If you specify `--delete` it will instruct Viper to delete the original copy of the file you want to store in the local repository, for example:

    shell > open -f /tmp/poisonivy.exe
    [*] Session opened on /tmp/poisonivy.exe
    shell poisonivy.exe > store --delete
    [+] Stored file "poisonivy.exe" to ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26
    [*] Session opened on ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26
    shell poisonivy.exe >

If you want, you can store the content of an entire folder by specifying its path to the `--folder` parameter. In case the folder contains a large variety of files, you can filter which ones you’re particularly interested in: with `--file-size` you can specify a maximum size in bytes, with `--file-type` you can specify a pattern of magic file type (e.g. PE32) and with `--file-name` you can specify a wildcard-enabled pattern to be matched with the file names (e.g. apt_*).

If you want, you can already specify a list of comma separated tags to apply to all files stored through the given command.

Following is an example:

    shell > store --folder /tmp/malware --file-type PE32 --file-size 10000000 --file-name apt_* --tags apt,trojan

## find

In order to quickly recover files you previously stored in the local repository, you can use the `find` command. Following is its help message:

    usage: find [-h] [-t] <all|latest|name|md5|sha256|tag|note> <value>

    Options:
        --help (-h) Show this help message
        --tags (-t) List tags

This command expects a key and eventually a value. As shown by the help message, these are the available keys:

> - all: this will simply return all available files.
> - latest (optional limit value): this will return the latest 5 (or whichever limit you specified) files added to the local repository.
> - name (required value): this will find files matching the given name pattern (you can use wildcards).
> - md5 (required value): search by md5 hash.
> - sha256 (required value): search by sha256 hash.
> - tag (required value): search by tag name.
> - note (required value): find files that possess notes matching the given pattern.

For example:

    shell > find tag rat
    +---+---------------+-----------------------+----------------------------------+
    | # | Name          | Mime                  | MD5                              |
    +---+---------------+-----------------------+----------------------------------+
    | 1 | poisonivy.exe | application/x-dosexec | 22f77c113cc6d43d8c12ed3c9fb39825 |
    +---+---------------+-----------------------+----------------------------------+

## info

The `info` command will return you some basic information on the file you currently have opened, for example:

    shell poisonivy.exe > info
    +--------+----------------------------------------------------------------------------------------------------------------------------------+
    | Key    | Value                                                                                                                            |
    +--------+----------------------------------------------------------------------------------------------------------------------------------+
    | Name   | poisonivy.exe                                                                                                                    |
    | Tags   | rat, poisonivy                                                                                                                   |
    | Path   | ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26                                        |
    | Size   | 133007                                                                                                                           |
    | Type   | PE32 executable (GUI) Intel 80386, for MS Windows                                                                                |
    | Mime   | application/x-dosexec                                                                                                            |
    | MD5    | 22f77c113cc6d43d8c12ed3c9fb39825                                                                                                 |
    | SHA1   | dd639a7f682e985406256468d6df8a717e77b7f3                                                                                         |
    | SHA256 | 50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26                                                                 |
    | SHA512 | 6743b06e8b243d513457949ad407d80992254c99b9835eb1ed03fbc0e88a062f0bb09bfd4dd9c0d43093b2a5419ecdb689574c2d2b0d72720080acf9af1b0a84 |
    | SSdeep | 3072:I4lRkAehGfzmuqTPryFm8le+ZNX2TpF3Vb:I4lRkAehaKuqT+FDl7NXs7B                                                                  |
    | CRC32  | 4090D32C                                                                                                                         |
    +--------+----------------------------------------------------------------------------------------------------------------------------------+

## notes

During an analysis you might want to keep track of your discoveries and results. Instead of having unorganized text files lying around, Viper allows you to create notes directly linked to the relevant files and even search across them. When you have a file opened, you can add any number of text notes associated to it through the `notes` command. This is the help message:

    usage: notes [-h] [-l] [-a] [-e <note id>] [-d <note id>]

    Options:
        --help (-h) Show this help message
        --list (-h) List all notes available for the current file
        --add (-a)  Add a new note to the current file
        --view (-v) View the specified note
        --edit (-e) Edit an existing note
        --delete (-d)   Delete an existing note

As shown in the help message, you can list add a note:

    shell poisonivy.exe > notes --add
    Enter a title for the new note:

Now you should enter a title, when you proceed Viper will open your default editor to edit the body of the note. Once done and the editor is closed, the new note will be stored:

    [*] New note with title "Domains" added to the current file

Now you can see the new note in the list and view its content:

    shell poisonivy.exe > notes --list
    +----+---------+
    | ID | Title   |
    +----+---------+
    | 1  | Domains |
    +----+---------+
    shell poisonivy.exe > notes --view 1
    [*] Title: Domains
    [*] Body:
    - poisonivy.malicious.tld
    - poisonivy2.malicious.tld

## tags

In order to easily group and identify files, Viper allows you to create one or more tags to be associated with them. This is the help message:

    usage: tags [-h] [-a=tags] [-d=tag]

    Options:
        --help (-h) Show this help message
        --add (-a)  Add tags to the opened file (comma separated)
        --delete (-d)   Delete a tag from the opened file

Once you have a file opened, you can add one ore more tags separated by a comma:

    shell poisonivy.exe > tags --add rat,poisonivy
    [*] Tags added to the currently opened file
    [*] Refreshing session to update attributes...
    [*] Session opened on ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26

Once added, the session will be refreshed so that the new attributes will be visible as you can see from the output of an `info` command:

    shell poisonivy.exe > info
    +--------+----------------------------------------------------------------------------------------------------------------------------------+
    | Key    | Value                                                                                                                            |
    +--------+----------------------------------------------------------------------------------------------------------------------------------+
    | Name   | poisonivy.exe                                                                                                                    |
    | Tags   | rat, poisonivy                                                                                                                   |
    | Path   | ~/viper/binaries/5/0/8/5/50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26                                        |
    | Size   | 133007                                                                                                                           |
    | Type   | PE32 executable (GUI) Intel 80386, for MS Windows                                                                                |
    | Mime   | application/x-dosexec                                                                                                            |
    | MD5    | 22f77c113cc6d43d8c12ed3c9fb39825                                                                                                 |
    | SHA1   | dd639a7f682e985406256468d6df8a717e77b7f3                                                                                         |
    | SHA256 | 50855f9321de846f6a02b264e25e4c59983badb912c3c51d8c71fcd517205f26                                                                 |
    | SHA512 | 6743b06e8b243d513457949ad407d80992254c99b9835eb1ed03fbc0e88a062f0bb09bfd4dd9c0d43093b2a5419ecdb689574c2d2b0d72720080acf9af1b0a84 |
    | SSdeep | 3072:I4lRkAehGfzmuqTPryFm8le+ZNX2TpF3Vb:I4lRkAehaKuqT+FDl7NXs7B                                                                  |
    | CRC32  | 4090D32C                                                                                                                         |
    +--------+----------------------------------------------------------------------------------------------------------------------------------+

## copy

The `copy` command let’s you copy the opened file into another project. By default the stored analysis results, notes and tags will also be copied. If the file has children related to it then these will not be copied by default. Also copying all children (recursively) can be enabled by passing the `--children` or `-c` flag.

If the `--delete` or `-d` is passed then the files will be copied to the specified project and then deleted from the local project:

    viper foo.txt > copy -h
    usage: copy [-h] [-d] [--no-analysis] [--no-notes] [--no-tags] [-c] project

    Copy opened file into another project

    positional arguments:
      project         Project to copy file(s) to

    optional arguments:
      -h, --help      show this help message and exit
      -d, --delete    delete original file(s) after copy ('move')
      --no-analysis   do not copy analysis details
      --no-notes      do not copy notes
      --no-tags       do not copy tags
      -c, --children  also copy all children - if --delete was selected also the
                      children will be deleted from current project after copy

    viper foo.txt > copy -d foobar
    [+] Copied: e2c94230decedbf4174ac3e35c6160a4c9324862c37cf45124920e63627624c1 (foo.txt)
    [*] Deleted: e2c94230decedbf4174ac3e35c6160a4c9324862c37cf45124920e63627624c1
    [+] Successfully copied sample(s)

## delete

The `delete` command you simply remove the currently opened file from the local repository:

    shell poisonivy.exe > delete
    Are you sure you want to delete this binary? Can't be reverted! [y/n] y
    [+] File deleted
    shell >