django-lasuite/documentation/how-to-use-malware-detection-backend.md

Using malware detection backend

If you are developing a service where users can upload files, you will probably want to check if these files are safe or not.

The malware detection app is here to give you several backend implementations and others can be added to match your requirements.

Global idea

A backend should inherit from lasuite.malware_detection.backends.base.BaseBackend class and implement the abstract methods declared in it. The backend service then is responsible to analyse the file and give an answer by calling a defined callback.

Abstract methods

• def analyse_file(self, file_path: str, **kwargs) -> None:: it is the entrypoint to analyse a file. This method returns nothing and can analyse the file by using a celery task. The parameters to use:
  • file_path: the path to access the file. This path must be accessible with the django default storage.
  • kwargs: arbitrary kwargs usable by the user using the library. These kwargs will be used by the callback. You can for example pass a resource id or whatever useful for you.

How to use a backend

We provide a handler responsible to instantiate and configure a backend. You have to declare in your settings the backend to use with their needed parameters.

The settings to use is settings.MALWARE_DETECTION. It is a dict containing two keys: BACKEND and PARAMETERS. The BACKEND is the full path to the backend class and the PARAMETERS is a dict containing all the parameters needed to instantiate the backend class.

Example:

settings.MALWARE_DETECTION = {
    "BACKEND": "lasuite.malware_detection.backends.dummy.DummyBackend",
    "PARAMETERS": {
        "callback_path": "path.to.your.callback",
    },
}

Every backend has at least the callback_path parameter. The callback is explained just before.

Then to use the backend in your code, you have to import the lasuite.malware_detection.malware_detection and call the analyse_file method.

Example:

from lasuite.malware_detection import malware_detection

malware_detection.analyse_file("path/to/your/file.txt")

Callback

In order to know the detection status, as it can be asynchronous, you have to create your own callback. This callback is a function that will be called once the analysis is done.

This function receives these parameters: - file_path the file_path used in the analyse_file method - status the analysis status (see lasuite.malware_detection.enums.ReportStatus). It can be safe, unsafe and unknown. In case of unknown you are responsible to determine what you should do - error_info a dict containing error and error_code properties. - kwargs the kwargs you pass to the analyse_file method

Existing implementations

Dummy

path: lasuite.malware_detection.backends.dummy.DummyBackend parameters: - callback_path: the full path to the callback.

The dummy backend does nothing. It calls the callback with always the safe status. It can be useful in a test context or to deactivate analysis.

Example:

settings.MALWARE_DETECTION = {
    "BACKEND": "lasuite.malware_detection.backends.dummy.DummyBackend",
    "PARAMETERS": {
        "callback_path": "path.to.your.callback",
    },
}

JCOP

JCOP means for Je Clique Ou Pas. To use it you need the url and the api token provided by them.

path: lasuite.malware_detection.backends.jcop.JCOPBackend parameters:

• api_key: The API key provided by JCOP
• base_url: The base URL provided by JCOP (including the /api/v1 base path)
• callback_path: the full path to the callback.
• result_timeout: The timeout for the result request. Default: 30 (optional)
• submit_timeout: The timeout for the submit request. Default: 600 (optional)

Example:

settings.MALWARE_DETECTION = {
    "BACKEND": "lasuite.malware_detection.backends.jcop.JCOPBackend",
    "PARAMETERS": {
        "callback_path": "path.to.your.callback",
        "api_key": "xxx",
        "base_url": "https://malware_detection.tld/api/v1"
    },
}