When it comes to multi-stage investigative routines that are regularly applied to evidence drives coming into a lab, automation is king. It allows creating workflows and setting up particular procedures so that a sequence of multiple tasks is launched with a single click and demands no further control by the operator. 

The key benefits of automation are: 

  1. Saves an investigator’s time: Automation allows users to focus on the parts of their jobs that require human attention, while entrusting routine tasks to a fine-tuned system. 
  2. Reduces processing time: There is no or minimal downtime between the different stages of acquisition and analysis.
  3. Streamlines the process and eliminates human error: When you have a predictable workflow and want to make sure every piece of evidence goes through the same stages. No exceptions.

A growing number of organizations create in-house automation solutions. Not to mention commercially available tools like Magnet Automate or Bismart OrchSight that provide investigators with highly customizable solutions for workflow automation. And any of such solutions can have Atola TaskForce integrated into its workflows as long as they use Web API for communication between the tools.  

Web API in TaskForce 

The use of TaskForce within an automation solution is possible via Web API (Application Programming Interface). It can also be used in scripts, via CLI (Command-Line Interface) tools like curl, as well as by simply typing commands in the browser address bar. 

These days, API is ubiquitous and is easily employed by any third-party tool. With Web API you do not need GUI (Graphical User Interface) to interact with forensic tools/products. All you need to effectively manage the most sophisticated devices in the forensic markets is code.  Through API commands you can launch, track and stop imaging in TaskForce. This way, you can effectively use TaskForce in exercising full control over the process and add it to a task sequence in third-party automation tools. 

Web API enables communication between the external software and the device: API determines the type of commands and queries sent to the unit, device behavior and the type of responses it sends back to the automation software. 

TaskForce API is based on HTTP GET requests and JSON-encoded responses as described in API documentation.  

Finding available sources

When an automation software sends /scan-devices command via API requesting the list of available source drives (Get available source drives), TaskForce does the following:

  1. automatically powers on all devices plugged into ports set to source mode (including those previously powered off due to being idle) 
  2. identifies all the source devices 
  3. checks which of them are available for imaging (are not engaged in other tasks) 

  The request then returns a JSON response with 

  • the number of scannedSourcePorts. This stands for the number of ports that have devices plugged in and identified. 
  • that of totalSourcePorts. i.e the total number of ports currently in Source mode. If scannedSourcePorts equals to totalSourcePorts, it means TaskForce has powered up and checked all currently available Source ports for devices before scanning those:
  • The foundSourceDrives list of identified drives on the source ports
{
    "scannedSourcePorts": 5,
    "totalSourcePorts": 13,
    "foundSourceDevices": 
    [
        "SATA4 SanDisk SDSSDA120G 171108456213",
        "SATA2 Samsung SSD 840 PRO Series S1AXNSAF106001H",
        "SATA5 ST500LM012 HN-M500MBB S2RWJ9CD415935",
        "SAS1 DG0146BARTP HPD0 D0A2P9602JFL0923",
        "USB4 WDC WD10JMVW-11AJGS4 WD-WXA1AA6PTY1K"
    ]
}

When this command is sent for the first time, TaskForce starts powering up all drives connected to the source ports one by one and attempting to identify them. Therefore it is recommended that a series of such commands are sent within 30 seconds for successful identification and count of all source devices.  

Starting an imaging session

Now let’s take a look at the ways to launch an imaging session using API’s /start-image command.  Once the evidence drive is identified and listed among the sources, you can start an imaging session to a specified network target folder: 

  • http://TASKFORCE_IP/api/start-image?source=SATA4&targetFolder=//Server/Share
  • http://TASKFORCE_IP/api/start-image?source=SATA4 SDSSDA120G Z32081RL&targetFolder=//10.0.0.14/Share

Both examples above will result in the same action. You can be more specific with your request giving both the port and the drive’s model and serial number to be more specific, as shown in the second example.

By default, the target image is a compressed E01, although the file format can be changed in the parameters. The two mandatory parameters are the source drive and target folder. Other settings have default values and can be adjusted.  

Launching multiple imaging sessions in one go

Web API allows TaskForce to launch up to 18 simultaneous imaging. All of TaskForce’s ports can be used for these purposes. 

Python script utilizes /start-image API request and prints task keys of all started imaging sessions.

Let’s see the process of launching 12 parallel imaging sessions with TaskForce API:  

import sys
 
if sys.version_info[0] < 3:
    raise Exception("Please use Python 3 to run this script")
 
import urllib.request
 
ports = ["SATA1", "SATA2", "SATA3", "SATA4", "SATA5", "SATA6", "SAS1", "SAS2", "SAS3", "SAS4", "SAS5", "SAS6"]
tasks = []
errors = {}
 
for port in ports:
    try:
        res = urllib.request.urlopen("http://10.0.0.4/api/start-image?source=%s&targetFolder=//Vitaliy/Share" % (port))
        tasks.append(res.read().decode('utf-8'))
    except urllib.error.HTTPError as e:
        errors[port] = e.read()
 
print("IDs of started imaging tasks:")
print('\n'.join(tasks))

Just as it would be in the case of the direct launch of imaging sessions via TaskForce interface, the cumulative imaging speed can achieve 15 TB/hour. The speed of individual sessions is normally limited only by the throughput of data on the source and the target. 

Eliminating downtime between imaging and analysis 

Web API enables tracking of the status of an imaging session in TaskForce via /check-task API request. 

When the request is received by TaskForce, it returns a response about the imaging’s progress or completion. Once the notification of completion is received, the automation tool or script may start the forensic analysis of the target image. Thus eliminating any pauses between acquisition and subsequent analysis. 

Here is the Powershell script that allows creating this type of automation flow:  

try {
    $r = Invoke-WebRequest "http://10.0.0.65/api/start-image?source=SATA4&targetFolder=\\10.0.0.4\Share"
}
catch {
    Write-Output "$($_.Exception.Message)"
    exit $_.Exception.Response.StatusCode
}
 
$taskKey = $r.Content
do {
    $check = (Invoke-WebRequest "http://10.0.0.65/api/check-task?taskKey=$taskKey").Content | ConvertFrom-Json
    Start-Sleep -s 1
} while ($check.state -eq "progress")
 
$windowsPath = "C:\Share\" + ($check.target -replace '[\/]', '\' | Split-Path -leaf)
$caseName = "Case123"
$autopsyArguments = '--inputPath="' + $windowsPath + '" --caseName=' + $caseName + ' --runFromCommandLine=true'
Start-Process -FilePath "C:\Program Files\Autopsy-4.11.0\bin\autopsy64.exe" -ArgumentList $autopsyArguments

Please note that Autopsy Ingest v4.11 does not operate with network file paths from the command line. That is why this example shows a shared PC folder where PowerShell script is executed: \\10.0.0.4\Share points to C:\Share folder.  

 

For a large lab with a high throughput of data or a one-man-band unit, API automation is a way to simplify and streamline the processing of evidence, receive fast and reliable results, and avoid man-made errors. 

Just entrust multiple operations to a reliable device enhanced with Web API, and focus on urgent tasks that really require human assistance. 

Yulia Samoteykina
Categories: Atola TaskForce

Yulia Samoteykina

Director of Marketing Yulia believes that with a product that is exceptionally good at solving tasks of forensic experts, marketing is about explaining its capabilities to the users and advocating on the users' behalf to ensure Atola keeps on adding value and raising the bar for the industry.