If you’ve ever attempted to run log2timeline on your local machine, you might be familiar with the error messages which happen at the worst time (when you need to use the tool for an investigation!).
Issues such as file permission errors, dependency conflicts, or an environment that’s misconfigured can can all break log2timeline. Right here in this post, you’re going to get a foolproof method to running log2timeline on demand without troubleshooting why the latest Ubuntu upgrades have broken the dependencies for log2timeline/plaso.
What is it? using Docker to containerise log2timeline.
Today we’ll walk you through how to set up Docker, run log2timeline using a container, and map your physical file system to make it easy to process images without having to load them into the docker container image.
Common Issues with Running log2timeline
Before we get started with Docker, let’s touch on some of the common issues when running log2timeline:
- File Permission Issues: If log2timeline doesn’t have the necessary permissions to access your evidence files or write to the output directory, it will fail. This often requires running commands as an administrator/root or adjusting file permissions.
- Missing or Corrupted Dependencies: The forensic tools you install locally often depend on various libraries. If these libraries are missing or corrupted, or if there are version conflicts, log2timeline may not work correctly.
- Environment Misconfiguration: Misconfigured Python environments can also be a roadblock. A Python package conflict or an incorrect Python version can easily disrupt your setup. Using virtual environments can help, but they aren’t always a perfect solution.
- Outdated Version: Finally, running an older version of log2timeline can lead to compatibility issues with modern file types or cause certain features to malfunction. Always ensure you have the latest version of the tool.
Luckily, running log2timeline moves past these. It’s a little different at first, but you’ll pick it up quickly.
Why Use Docker for log2timeline?
Docker allows you to containerise applications, including log2timeline, and run them in an isolated environment. This way, all the necessary dependencies and configurations are self-contained, and you won’t have to worry about conflicts or compatibility issues. Docker is virtual computing (think VMWare or VirtualBox virtual machines), but for applications and they run in a ‘container’.
Containers are something like a virtual machine (VM). It has its operating system and all, except that unlike virtual machines they don’t simulate the entire computer, but rather create a sand boxed environment that pretends to be a virtual machine.
Docker containers are a bit beyond the scope of this post, but I hope you get the basic idea. Really though, let’s just get processing some images!
Step-by-Step Guide to Running log2timeline in a Docker Container
1. Install Docker
First, you’ll need to install Docker on your system. Follow these steps:
- Download Docker:
- Visit Docker’s official website and download Docker Desktop for your operating system (Windows, macOS, or Linux).
- Install Docker:
- Run the installer and follow the on-screen instructions.
- On Windows, ensure you enable the necessary Windows features (like WSL 2) during installation.
- Verify the Installation:
- Open a terminal (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux) and run the following command to check if Docker is installed correctly:
docker –version
Now that Docker is up and running, let’s move on to using log2timeline.
Understanding the Command
Here’s a command to run log2timeline using Docker:
docker run -v E:/Forensic_tests/USBImage:/data log2timeline/plaso log2timeline –storage-file /data/usbimage.plaso /data/E01_test.E01
Let’s break down what’s happening here:
- docker run: Starts a new Docker container.
- -v E:/Forensic_tests/USBImage:/data: This flag maps a directory on your host system (E:\Forensic_tests) to a directory in the Docker container (/data).
This is called a bridge. The bridge ensures the container has access to your evidence files.
- log2timeline/plaso: The Docker image name. Yes, I’m not being flippant about calling it log2timeline OR plaso. The image name is literally log2timeline/plaso
- log2timeline –storage-file /data/usbimage.plaso /data/E01_test.E01: This runs log2timeline inside the container. The –storage-file option specifies the output file, and /data/E01_test.E01 points to the input evidence file.
Steps to Execute
- Prepare Your Evidence:
- Make sure your evidence file (E01_test.E01) is stored in E:\Forensic_tests (update this to what makes sense for you. If you want to use C:\temp then use that as your storage location and update the command accordingly.) on your host system.
- Run the Command:
- For the first time after installing Docker, open a terminal and run docker pull log2timeline/plaso
- Then run:
- docker run -v E:/Forensic_tests/USBImage:/data log2timeline/plaso log2timeline –storage-file /data/usbimage.plaso /data/E01_test.E01
Remember: E:/Forensic_tests/USBImage is where I am storing my image file. If you have a different place to store your data, change it in the command, and make sure you have the directory created on your system.
In this command, E:/Forensic_tests is being mapped to “/data” in the docker instance.
TROUBLESHOOTING: I want to give you an example of troubleshooting. When I was writing this up and running through my commands again, I got an error message that the file couldn’t be found.
I forgot I had the image file in a subdirectory called ‘USBImage’. It’s easy to get frustrated when the commands don’t work. If you’re in the thick of an investigation and time is precious, it’s a good opportunity to take a moment to step back and go through it slowly.
Taking your time to read the error messages and go through what is happening in a logical and methodical way helps to identify issues. This is why it’s so important to practice using your tools often. Get them to become like second nature so when you’re working with a live incident these errors and issues are already ironed out.
- Check the Output:
- The output file (usbimage.plaso) will be saved in E:\Forensic_tests\USBImage on your host machine.
- Generate the timeline:
- Using the plaso PSORT command generate a timeline in an output file. The PSORT command processes extracted events, merging detected duplicate events. All date and time values will be in UTC.
docker run -v E:/Forensic_tests/USBImage:/data log2timeline/plaso psort -o l2tcsv -w /data/timeline.csv /data/usbimage_l2tcsvtest.plaso
MORE TROUBLESHOOTING
When typing the command out, I got an error message saying the file couldn’t be found.
See if you can spot the difference here:
docker run -v E:/Forensic_tests/USBImage:/data/ log2timeline/plaso psort -o l2tcsv -w /data/timeline.csv /data/usbimage_l2tcsvtest.plaso
docker run -v E:/Forensic_tests/USBImage:/data log2timeline/plaso psort -o l2tcsv -w /data/timeline.csv /data/usbimage_l2tcsvtest.plaso
It’s subtle, but I had put a trailing / on the path for the bridge. Removing this got psort working and successfully processed my timeline.
I’ve shared these ‘gotchas’ with you in the hope that you can see where it’s easy to go wrong, and to stick it out with running the commands and troubleshooting as you go. It’s such a win after you work through the errors and you get to see the output of your forensic processing!
