Request class¶

The Request object is the parameter received by the service execute function. It holds information about the task to be processed by the service.

You can view the source for the class here: Request class source

Class variables¶

The following table describes all of the Request object variables which the service can use.

Variable name	Description
deep_scan	Returns whether the file should be deep-scanned or not. Deep-scanning usually takes more time and is better suited for files that are sent manually.
file_contents	Returns the raw byte contents of the file to be scanned.
file_name	Returns the name of the file (as submitted by the user) to be scanned.
file_path	Returns the path to the file to be scanned. The service can use this path directly to access the file.
file_type	Returns the Assemblyline-style file type of the file to be scanned.
max_extracted	Returns the maximum number of files that are allowed to be extracted by a service. By default this is set to 500.
md5	Returns the MD5 hash of the file to be scanned.
result	Used to get and set the current result.
sha1	Returns the SHA1 hash of the file to be scanned.
sha256	Returns the SHA256 hash of the file to be scanned.
sid	ID of the submission being scanned.
task	The original task object used to create this request. You can find more information there about the request (metadata submitted, files already extracted by other services, tags already generated by other services and more...)
temp_submission_data	Can be used to get and set temporary submission data which is passed onto subsequent tasks resulting from adding extracted files.

Class functions¶

The following table describes the Request object functions which the service can use.

add_extracted()¶

This function adds a file extracted by the service to the result. The extracted file will also be scanned through a set of services, as if it had been originally submitted. For example with a ZIP file, Extract is going to send back as an extracted file anything that came out of the ZIP file.

This function can take the following parameters:

path: Complete path to the file
name: Display name of the file
description: Descriptive text about the file
classification: Optional classification of the file

Example

Excerpt from Assemblyline ResultSample service: result_sample.py

...
# ==================================================================
# Re-submitting files to the system
#     Adding extracted files will have them resubmitted to the system for analysis
...
fd, temp_path = tempfile.mkstemp(dir=self.working_directory)
with os.fdopen(fd, "wb") as myfile:
    myfile.write(b"CLASSIFIED!!!__"+data.encode())
request.add_extracted(temp_path, "classified.doc", "Classified file ... don't look",
                      classification=cl_engine.RESTRICTED)
...

add_supplementary()¶

This function adds a supplementary file generated by the service to the result. The supplementary file is uploaded for the user's informational use only and is not scanned. For example, Extract may add a supplementary file for the list of passwords it tried on a password-protected file if it failed to extract it. Supplementary files make more sense if there is a bigger and more complex file, like a JSON file.

This function can take the following parameters:

path: Complete path to the file
name: Display name of the file
description: Descriptive text about the file
classification: Optional classification of the file

Example

Excerpt from Assemblyline ResultSample service: result_sample.py

...
# ==================================================================
# Supplementary files
#     Adding supplementary files will save them on the datastore for future
#      reference but won't reprocess those files.
fd, temp_path = tempfile.mkstemp(dir=self.working_directory)
with os.fdopen(fd, "w") as myfile:
    myfile.write(json.dumps(urls))
request.add_supplementary(temp_path, "urls.json", "These are urls as a JSON file")
...

drop()¶

When called, the task will be dropped and will not be processed further by other remaining service(s).

Example

Excerpt from Assemblyline Safelist service: safelist.py

...
# Stop processing, the file is safe
request.drop()
...

get_param()¶

Retrieve a submission parameter for the task.

This function can take the following parameter:

name: name of the submission parameter to retrieve

Example

Excerpt from Assemblyline Extract service: extract.py

...
def execute(self, request: ServiceRequest):
    ...
    continue_after_extract = request.get_param('continue_after_extract')
    ...

These submission parameters are also defined with default values in the service manifest. A system administrator can change the default values at /admin/services and any user can overwrite these values when they create a submission.

Users can also set their preferred default values for submission parameters in their profile at /settings. For example, in the Extract service, I always want to try the password "mycustompassword" whenever I upload a password-protected ZIP file because that is my personal favourite password to use when password-protecting ZIP files.

set_service_context()¶

Set the context of the service which ran the file. For example, if the service ran an AntiVirus engine on the file, then the AntiVirus definition version would be the service context.

This function can take the following parameters:

context: Service context as string

Example

Excerpt from Assemblyline Metadefender service: metadefender.py

...
def execute(self, request: ServiceRequest):
    ...
    request.set_service_context(f"Definition Time Range: {self.nodes[self.current_node]['oldest_dat']} - "
                                f"{self.nodes[self.current_node]['newest_dat']}")
    ...