Skip to content

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.

Submission Parameters for the Extract service

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.

Setting a custom password for the Extract service

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']}")
    ...