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/(id)/download/(module)/(filename)	Download a support file.
	GET /analyses/(id)/	Get an analysis
	GET /analyses/	Get the list of analyses
	POST /analyses/is_safe_url	Check if a provided URL is considered internal or fully trusted.
	POST /analyses/	Create an analysis
	GET /analyses/(id)/refresh-iocs	Refresh IOCs with Threat Intel modules.
	POST /analyses/(id)/submit_iocs/(module)	Submit observables to a threat intelligence module
File	DELETE /files/(id)	Anonymize (soft delete) an object.
	GET /files/download/(id)/	Download a file
	GET /files/(id)/	Get an object
	GET /files/hash/(file_hash)	Get an object by a hash
	GET /files/md5/(md5)	Get an object by MD5
	GET /files/sha1/(sha1)	Get an object by SHA1
	GET /files/sha256/(sha256)	Get an object by SHA256
	GET /files/	Get the list of objects
	POST /files/(id)/review	set review state
	POST /files/(id)/submit_to_av/(module)	Submit file to an antivirus module
Malware Configurations	GET /configs/	Get the index
	GET /configs/show/	Get a timeline
Module	GET /modules/(id)/configuration	Configure a named configuration
	POST /modules/(id)/configuration
	GET /modules/(id)/configure	Configure a module
	POST /modules/(id)/configure
	POST /modules/(id)/disable	Disable a module
	POST /modules/(id)/enable	Enable a module
	GET /modules/	Get the list of modules
	GET /modules/list/	List enabled Processing and Preloading modules
	POST /modules/reload	Reload workers
	POST /modules/repository/(id)/delete	Delete repository
	GET /modules/repository/new	Add repository
	POST /modules/repository/new
	POST /modules/repository/(id)/update	Update repository
User	POST /users/create	Create new user
	POST /users/(id)/default_sharing	Change default sharing
	POST /users/(id)/disable	Disable a user
	POST /users/(id)/enable	Enable a user
	GET /users/(id)/	Get a user
	GET /users/	Get the list of users
	POST /users/(id)/reset_api	Reset API key
	POST /users/(id)/update	Update existing user

DELETE /files/(id)¶

Anonymize (soft delete) a file from FAME disk. Support files from associated analyses are also removed, if any.

Parameters:

id – id of the file to anonymize.

Response JSON Object:

response (string) – Contain information on the deletion status.

GET /files/download/(id)/¶

Download the file with id.

Parameters:

id – id of the file to download.

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.
reviewed (user) – analyst’s ObjectId if review has been performed
exists_on_disk (bool) – True if the file still exists on disk, False otherwise

GET /files/hash/(file_hash)¶

Get the object with file_hash.

Parameters:

hash – hash of the object.

Response JSON Object:

file (file) – list of files (see GET /files/(id) for details on the format of a file).

GET /files/md5/(md5)¶

Get the object with md5.

Parameters:

md5 – md5 of the object.

Response JSON Object:

file (file) – list of files (see GET /files/(id) for details on the format of a file).

GET /files/sha1/(sha1)¶

Get the object with sha1.

Parameters:

sha1 – sha1 of the object.

Response JSON Object:

file (file) – list of files (see GET /files/(id) for details on the format of a file).

GET /files/sha256/(sha256)¶

Get the object with sha256.

Parameters:

sha256 – sha256 of the object.

Response JSON Object:

file (file) – list of files (see GET /files/(id) for details on the format of a file).

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.
filter – (optional) set filter. can be “to_review” or “reviewed”

Response JSON Object:

files (list) – list of files (see GET /files/(id) for details on the format of a file).

POST /files/(id)/review¶

Set review value state of a file

Set the review state of a file.

Form Parameters:

bool reviewed – if the file has been reviewed or not

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.

GET /analyses/(id)/download/(module)/(filename)¶

Download a support file.

Parameters:

id – id of the analysis.
module – name of the module.
filename – name of the file to download.

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.
reviewed (dict) – analyst’s ObjectId if review has been performed
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 /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.
filter – (optional) set filter. can be “to_review” or “reviewed”

Response JSON Object:

analyses (list) – list of analyses (see GET /analyses/(id) for details on the format of an analysis).

POST /analyses/is_safe_url¶

Check if an URL is considered safe

Form Parameters:

string url – URL to check.

Response JSON Object:

is_safe (bool) – True if the URL is considered safe, False otherwise.

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 comment – comment to add to this object.
string option[*] – value of each enabled option.

GET /analyses/(id)/refresh-iocs¶

Refresh IOCs with Threat Intel modules

Parameters:

id – id of the analysis.

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 /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)/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)/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 (for Processing and Preloading modules).

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 (for Processing and Preloading 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 /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": [
        ...
    ],
    "Preloading": [
        ...
    ],
    "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": [
        ...
    ],
    "Filetype": [
        ...
    ]
}

repositories: list of configured repositories:

"repositories": [
    {
        "_id": {
            "$oid": "ID"
        },
        "address": "git@github.com:certsocietegenerale/fame_modules.git",
        "name": "community",
        "private": false,
        "status": "active",
        "branch": "master"
    },
    ...
]

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 /modules/list/¶

List enabled Processing and Preloading modules

Response JSON Object:

modules (list) – list of enabled modules.

POST /modules/reload¶

Reload the workers

Requires the manage_modules permission.

Returns “ok”.

POST /modules/repository/(id)/delete¶

Delete a repository

Requires the manage_modules permission. Returns “ok”.

Parameters:

id – id of the repository.

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.
branch – branch of the repository
private – boolean specifying if the repository is private. See Administration Guide for more details on private repositories.

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.
branch – branch of the repository
private – boolean specifying if the repository is private. See Administration Guide for more details on private repositories.

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.

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 /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.

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)/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.

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

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 /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)/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.