NOTE: This is a work in progress

Overview

The Java code and database in Sleuth Kit contain special classes and tables to deal with communications between two parties. This page outlines what a developer should do when they are parsing communications data so that it can be properly displayed and used by other code (such as the Autopsy Communications UI).

Terminology

First, let's cover the terminology that we use.

Accounts

An Account is an entity with a type and an identifier that is unique to the type. Common examples of types include:

Credit Card (and the unique identifier is the credit card number)
Email (and the unique identifier is the email address)
Phone (and the unique identifier is the phone number)
Twitter (with a unique identifier of the login)
...

Accounts are found in a digital investigation when parsing structured data (such as email messages) or keyword searching.

Relationships

Two accounts have a relationship if they are believed to have communicated in some way. Examples of interactions that cause a relationship are:

Being part of the same email message
Being in a call log
Being in an address book

When there are multiple people involved with an email message, a relationship is made between each of them. For example, if A sends a message to B and CC:s C, then there will be relationships between A <-> B, A <-> C, and B <-> C. Relationships in The Sleuth Kit are not directional.

A relationship source is where we learned about the relationship. This typically comes from Blackboard Artifacts, but may come from generic files in the future.

Device Accounts

In some situations, we may not know a specific account that a relationship exists with. For example, when we find a contact book a thumb drive, we want to make a relationship between the accounts in the contact book and the accounts associated with the owner of that thumb drive. But, we may not know which accounts are for that owner. The contacts could be just a bunch of vCards and not tied to a specific email or phone number.

In this situation, we make a device account that is associated with the data source or device being analyzed. You should make an account of type Account.Type.DEVICE (instead of something like EMAIL) and the identifier is the device id of the data source where the other accounts were located.

Adding Communication Information to Database

Now let's cover what you should do when you are parsing some communications data and want to store it in the TSK database. Let's assume we are parsing a smart phone app that has messages.

Adding Account Instances

When you encounter a message, the first thing to do is store information about the accounts. TSK wants to know about each file that had a reference of the account. You should call org.sleuthkit.datamodel.CommunicationsManager.createAccountFileInstance() for each file that you encounter a given account.

To make a device account, you'd have logic similar to:

AccountFileInstance deviceAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.DEVICE,

abstractFile.getDataSource().getDeviceId(), "Module Name", abstractFile);

Behind the scenes, createAccountFileInstance will make an entry in the accounts table for each unique account on a given device and will make a org.sleuthkit.datamodel.BlackboardArtifact for each unique account in a given file.

If you want to create a custom account type, call org.sleuthkit.datamodel.CommunicationsManager.addAccountType().

Adding The Message (Relationship Source)

You also need to make sure that you store the org.sleuthkit.datamodel.BlackboardArtifact that used the accounts and had the relationship. You can do this before or after calling createAccountFileInstance(). The order does not matter.

For a messaging app, you would make org.sleuthkit.datamodel.BlackboardArtifact objects with a type of org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE.TSK_MESSAGE. That artifact would store various name and value pairs using org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE values. There is nothing communication-specific about this step. It is the same Blackboard artifacts and attributes that are used in many other places.

Adding the Relationship

The final step is to store the relationships between the accounts. You can do this via org.sleuthkit.datamodel.CommunicationsManager.addRelationships(). This method will require you to pass in the org.sleuthkit.datamodel.AccountInstance objects that you created and the org.sleuthkit.datamodel.BlackboardArtifact that you created for the message or other source.

The source of the relationship can be a device account (for things like call logs and contacts) if you are unsure about the specific account (such as phone number) associated with the device.

As an example, you can refer to some code in Autopsy. Such as:

Database Schema

For details of how this is stored in the database, refer to the wiki.