API

The API is using the same endpoints as the web application.

Authentication

In order to authenticate, you should add your API key to the X-API-KEY header. This is needed for all requests made through the API.

Error Codes

The API can return the following HTTP codes:

  • 302: this means that you are not properly authenticated.
  • 403: this means that your permissions are not sufficient.
  • 404: this means that you tried to access an object that could not be found.

Reference

Resource Operation Description
Analysis GET /analyses/ Get the list of analyses
  POST /analyses/ Create an analysis
  POST /analyses/(id)/submit_iocs/(module) Submit observables to a threat intelligence module
  GET /analyses/(id)/download/(filename) Download a support file.
  GET /analyses/(id) Get an analysis
File GET /files/ Get the list of objects
  POST /files/(id)/submit_to_av/(module) Submit file to an antivirus module
  GET /files/download/(id) Download a file
  GET /files/(id) Get an object
Malware Configurations GET /configs/show/ Get a timeline
  GET /configs/ Get the index
Module POST /modules/repository/new Add repository
  GET /modules/repository/new  
  POST /modules/reload Reload workers
  GET /modules/list/ List enabled Processing modules
  GET /modules/ Get the list of modules
  POST /modules/repository/(id)/delete Delete repository
  POST /modules/repository/(id)/update Update repository
  POST /modules/(id)/configuration Configure a named configuration
  GET /modules/(id)/configuration  
  POST /modules/(id)/configure Configure a module
  GET /modules/(id)/configure  
  POST /modules/(id)/disable Disable a module
  POST /modules/(id)/enable Enable a module
User POST /users/create Create new user
  GET /users/ Get the list of users
  POST /users/(id)/default_sharing Change default sharing
  POST /users/(id)/reset_api Reset API key
  POST /users/(id)/disable Disable a user
  POST /users/(id)/enable Enable a user
  POST /users/(id)/update Update existing user
  GET /users/(id) Get a user
POST /modules/repository/new

Add a repository

Requires the manage_modules permission.

If successful, will return the repository in repository. Otherwise, errors will be available in errors.

Form Parameters:
 
  • name – name of the repository (should be a valid package name).
  • address – HTTPs or SSH address of the repository.
  • private – boolean specifying if the repository is private. See Administration Guide for more details on private repositories.
GET /modules/repository/new

Add a repository

Requires the manage_modules permission.

If successful, will return the repository in repository. Otherwise, errors will be available in errors.

Form Parameters:
 
  • name – name of the repository (should be a valid package name).
  • address – HTTPs or SSH address of the repository.
  • private – boolean specifying if the repository is private. See Administration Guide for more details on private repositories.
POST /modules/reload

Reload the workers

Requires the manage_modules permission.

Returns “ok”.

GET /modules/list/

List enabled Processing modules

Response JSON Object:
 
  • modules (list) – list of enabled modules.
GET /configs/show/

Get a malware configuration timeline.

Requires the config permission.

You can get the timeline of your choice by conbining several filters.

Query Parameters:
 
  • monitor – (optional) filter by monitor.
  • target – (optional) filter by target.
  • botnet – (optional) filter by botnet.
  • type – (optional) filter by type.
Response JSON Object:
 
  • botnets (list) – the list of available botnets.
  • monitors (list) – the list of available monitors.
  • targets (list) – the list of available targets.
  • types (list) – the list of available configuration block types.
  • config_blocks (list) –

    a sorted list of configuration blocks matching this query. Each configuration block has the following format:

    {
        "_id": {
            "$oid": "CONFIG_BLOCK_ID"
        },
        "action": "CONFIG_BLOCK_ACTION", # new, update, removed or added
        "additional": null,
        "analyses": [
            {
                "$oid": "ANALYSIS_ID"
            }
        ],
        "botnet": "FAMILY:BOTNETID",
        "content": "CONFIG_BLOCK_CONTENT",
        "created": {
            "$date": CREATION_DATE
        },
        "monitor": "MATCHING_MONITOR",
        "target": "TARGET",
        "type": "CONFIG_BLOCK_TYPE",
        "updated": {
            "$date": MODIFICATION_DATE
        }
    }
    
POST /users/create

Create a user.

Requires the manage_users permission.

When succesful, the new user will be returned in the user field. Otherwise, an errors field will list errors.

Form Parameters:
 
  • name – full name
  • email – email address
  • groups – comma-delimited list of groups
  • permission_VALUE – specify a value different than 0 or False for all permissions the user should have.
GET /analyses/

Get the list of analyses.

Response is paginated and will only contain 25 results. The most recent analyses appear first.

Query Parameters:
 
  • page – page number.
Response JSON Object:
 
  • analyses (list) – list of analyses (see GET /analyses/(id) for details on the format of an analysis).
POST /analyses/

Create a new analysis.

Launch a new analysis. You have to specify on which object this analysis will be made, by specifying one of:

  • file_id for an existing object
  • file for file uploads
  • url
  • hash if VirusTotal sample retrieval is enabled.

You should also supply all enabled analysis options with the name options[OPTION_NAME]. For boolean options, any value different than 0 or False means the option is enabled.

If the submitted object already exists (and file_id was not specified), the response will be a file object. When a new analysis was successfuly created, the analysis object will be returned, in the analysis field.

If there was error in your submission, they will be returned in the errors field.

Example request:

headers = {
    'Accept': "application/json",
    'X-API-KEY': FAME_API_KEY
}

with open(filepath, 'rb') as f:
    params = {
        'options[allow_internet_access]':  "on",
        'options[analysis_time]': "300",
        'groups': "cert"
    }

    files = {
        'file': f
    }

    r = requests.post(ENDPOINT, data=params, files=files, headers=headers)
Form Parameters:
 
  • string file_id – (optional) the id of the object on which this analysis should run.
  • file file – (optional) file to analyze.
  • string url – (optional) url to analyze.
  • string hash – (optional) hash to analyze.
  • string module – (optional) the name of the target module.
  • string groups – a comma-separated list of groups that will have access to this analysis.
  • string option[*] – value of each enabled option.
GET /modules/

Get the list of modules.

Requires the manage_modules permission.

The response is a dict with several elements:

  • modules, which is a list of modules, sorted by type:

    "modules": {
        "Antivirus": [
            ...
        ],
        "Processing": [
            {
                "_id": {
                    "$oid": "MODULE_ID"
                },
                "acts_on": [
                    ACTS_ON_FAME_TYPES
                ],
                "class": "CLASS_NAME",
                "config": [ CONFIG_OPTIONS ],
                "description": "DESCRIPTION",
                "enabled": false,
                "generates": [GENERATES],
                "name": "NAME",
                "path": "MODULE_PATH",
                "queue": "QUEUE",
                "triggered_by": [
                    TRIGGERS
                ],
                "type": "Processing"
            },
            ...
        ],
        "Reporting": [
            ...
        ],
        "Threat Intelligence": [
            ...
        ]
    }
    
  • repositories: list of configured repositories:

    "repositories": [
        {
            "_id": {
                "$oid": "ID"
            },
            "address": "git@github.com:certsocietegenerale/fame_modules.git",
            "name": "community",
            "private": false,
            "status": "active"
        },
        ...
    ]
    
  • configs: list of named configurations:

    "configs": [
        {
            "_id": {
                "$oid": "ID"
            },
            "config": [
                {
                    "description": "List of patterns (strings) to look for in malware configurations. There should be one pattern per line.",
                    "name": "monitor",
                    "type": "text",
                    "value": null
                }
            ],
            "description": "Needed in order to be able to track malware targets",
            "name": "malware_config"
        },
        ...
    ]
    
GET /configs/

Get the index of malware configurations.

Requires the config permission.

The response is a dict with the following format:

{
    "MONITOR1": {
        "active_botnets": [
            "FAMILY:BOTNETID"
        ],
        "botnets": [
            "FAMILY:BOTNETID"
        ],
        "count": 1,
        "targets": {
            "TARGET1": {
                "active_botnets": [
                    "FAMILY:BOTNETID"
                ],
                "botnets": [
                    "FAMILY:BOTNETID"
                ],
                "count": 1
            },
            "TARGET2": {
                ...
            }
        }
    },
    "MONITOR2": {
        ...
    }
}
GET /files/

Get the list of objects.

Response is paginated and will only contain 25 results. The most recent objects appear first.

Query Parameters:
 
  • page – page number.
Response JSON Object:
 
  • files (list) – list of files (see GET /files/(id) for details on the format of a file).
GET /users/

Get all users.

Requires the manage_users permission. The result is in the users field.

Response JSON Array of Objects:
 
  • _id (ObjectId) – user’s ObjectId.
  • name (string) – full name.
  • string – email address.
  • enabled (boolean) – True if the user is enabled.
  • groups (list) – list of groups the user belongs to.
  • default_sharing (list) – list of groups used by the user as default sharing preferences.
  • permissions (list) – list of user’s permissions
POST /analyses/(id)/submit_iocs/(module)

Submit observables to a Threat Intelligence module.

If succesful, the response will be "ok".

Parameters:
  • id – id of the analysis.
  • module – name of the module to submit the file to.
Request JSON Array of Objects:
 
  • value (string) – the value of the observable.
  • tags (list) – a list of tags associated to it.
GET /analyses/(id)/download/(filename)

Download a support file.

Parameters:
  • id – id of the analysis.
  • filename – name of the file to download.
POST /modules/repository/(id)/delete

Delete a repository

Requires the manage_modules permission. Returns “ok”.

Parameters:
  • id – id of the repository.
POST /modules/repository/(id)/update

Update a repository

Requires the manage_modules permission.

Parameters:
  • id – id of the repository.
Response JSON Object:
 
  • repository (Repository) – the repository.
POST /files/(id)/submit_to_av/(module)

Submit a file to an Antivirus module.

If succesful, the response will be "ok". Otherwise, it will be an error message.

Parameters:
  • id – id of the file to submit.
  • module – name of the module to submit the file to.
POST /modules/(id)/configuration

Configure a named configuration.

Requires the manage_modules permission.

For each configuration available, you should set the value in a form parameter named config_NAME. For boolean values, any value not 0 or False is considered to be True.

If successful, will return the named configuration in config. Otherwise, errors will be available in errors.

Parameters:
  • id – id of the named configuration.
GET /modules/(id)/configuration

Configure a named configuration.

Requires the manage_modules permission.

For each configuration available, you should set the value in a form parameter named config_NAME. For boolean values, any value not 0 or False is considered to be True.

If successful, will return the named configuration in config. Otherwise, errors will be available in errors.

Parameters:
  • id – id of the named configuration.
POST /modules/(id)/configure

Configure a module.

Requires the manage_modules permission.

For each configuration available, you should set the value in a form parameter named config_NAME. For boolean values, any value not 0 or False is considered to be True.

If the setting should be an option (be available per analysis), you have to set config_NAME_option to any value but 0 or False.

If successful, will return the module in module. Otherwise, errors will be available in errors.

Parameters:
  • id – id of the named configuration.
Form Parameters:
 
  • acts_on – comma-delimited list of FAME types this module can act on (only for Processing modules).
  • triggered_by – comma-delimited list of triggers (only for Processing modules).
  • queue – name of the queue to use for this module (only for Processing modules).
GET /modules/(id)/configure

Configure a module.

Requires the manage_modules permission.

For each configuration available, you should set the value in a form parameter named config_NAME. For boolean values, any value not 0 or False is considered to be True.

If the setting should be an option (be available per analysis), you have to set config_NAME_option to any value but 0 or False.

If successful, will return the module in module. Otherwise, errors will be available in errors.

Parameters:
  • id – id of the named configuration.
Form Parameters:
 
  • acts_on – comma-delimited list of FAME types this module can act on (only for Processing modules).
  • triggered_by – comma-delimited list of triggers (only for Processing modules).
  • queue – name of the queue to use for this module (only for Processing modules).
POST /modules/(id)/disable

Disable a module

Requires the manage_modules permission.

Parameters:
  • id – id of the module to disable.
Response JSON Object:
 
  • module (Module) – resulting module.
POST /modules/(id)/enable

Enable a module

Requires the manage_modules permission.

If successful, will return the module in module. Otherwise, errors will be available in errors.

Parameters:
  • id – id of the module to enable.
GET /files/download/(id)

Download the file with id.

Parameters:
  • id – id of the file to download.
POST /users/(id)/default_sharing

Change a user’s default sharing.

When used on another user account, requires the manage_users permission.

Parameters:
  • id – user id.
Response JSON Object:
 
  • user (User) – modified user.
POST /users/(id)/reset_api

Reset a user’s API key.

When used on another user account, requires the manage_users permission.

Parameters:
  • id – user id.
Response JSON Object:
 
  • user (User) – modified user.
POST /users/(id)/disable

Disable a user.

Requires the manage_users permission.

Parameters:
  • id – user id.
Response JSON Object:
 
  • user (User) – modified user.
POST /users/(id)/enable

Enable a user.

Requires the manage_users permission.

Parameters:
  • id – user id.
Response JSON Object:
 
  • user (User) – modified user.
POST /users/(id)/update

Update a user.

Requires the manage_users permission.

When succesful, the new user will be returned in the user field. Otherwise, an errors field will list errors.

Form Parameters:
 
  • name – full name
  • email – email address
  • groups – comma-delimited list of groups
  • permission_VALUE – specify a value different than 0 or False for all permissions the user should have.
GET /analyses/(id)

Get the analysis with id.

Resulting object is in the analysis field.

Parameters:
  • id – id of the analysis.
Response JSON Object:
 
  • _id (dict) – ObjectId dict.
  • analyst (dict) – analyst’s ObjectId.
  • date (dict) – date dict.
  • executed_modules (list) – list of executed modules.
  • pending_modules (list) – list of pending modules.
  • waiting_modules (list) – list of waiting modules.
  • canceled_modules (list) – list of canceled modules.
  • executed_modules – list of executed modules.
  • module (string) – the name of the target module.
  • status (string) – status of the analysis (one of pending, running, finished or error).
  • tags (list) – the list of tags.
  • probable_names (list) – the list of probable names.
  • iocs (list) – list of dict describing observables.
  • results (dict) – detailed results for each module, with the module name being the key.
  • generated_files (dict) – a dict of generated files, the key being the file type.
  • extracted_files (list) – a list of extracted files.
  • support_files (dict) – a dict of support files, the key being the module name.
GET /files/(id)

Get the object with id.

Resulting object is in the file field.

Parameters:
  • id – id of the object.
Response JSON Object:
 
  • _id (dict) – ObjectId dict.
  • md5 (string) – MD5 hash.
  • sha1 (string) – SHA1 hash.
  • sha256 (string) – SHA256 hash.
  • type (string) – FAME type.
  • mime (string) – mime type.
  • detailed_type (string) – detailed type.
  • groups (list) – list of groups (as strings) that have access to this file.
  • owners (list) – list of groups (as strings) that submitted this file.
  • probable_names (list) – list of probable names (as strings).
  • analysis (list) – list of analyses’ ObjectIds.
  • parent_analyses (list) – list of analyses (as ObjectIds) that extracted this object.
  • antivirus (dict) – dict with antivirus names as keys.
GET /users/(id)

Get a user.

The user is returned in the user field.

Parameters:
  • id – user id
Response JSON Object:
 
  • _id (ObjectId) – user’s ObjectId.
  • name (string) – full name.
  • string – email address.
  • enabled (boolean) – True if the user is enabled.
  • groups (list) – list of groups the user belongs to.
  • default_sharing (list) – list of groups used by the user as default sharing preferences.
  • permissions (list) – list of user’s permissions