From ee4c9520cc1e83380b44fa2f560709d710edd8af Mon Sep 17 00:00:00 2001
From: Brian Carrier <carrier@sleuthkit.org>
Date: Mon, 22 Jan 2018 17:10:17 -0500
Subject: [PATCH] Added comm mgr comments
---
bindings/java/doxygen/communications.dox | 43 ++++++++++++-
.../datamodel/AccountDeviceInstance.java | 6 +-
.../datamodel/AccountFileInstance.java | 21 +++----
.../datamodel/CommunicationsManager.java | 62 ++++++++++---------
4 files changed, 88 insertions(+), 44 deletions(-)
diff --git a/bindings/java/doxygen/communications.dox b/bindings/java/doxygen/communications.dox
index 9ed28479b..add62f93f 100644
--- a/bindings/java/doxygen/communications.dox
+++ b/bindings/java/doxygen/communications.dox
@@ -1,8 +1,49 @@
/*! \page mod_compage Communications
+
+
+NOTE: This is a work in progress
+
+
\section jni_com_overview Overview
-Work in progress
+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).
+
+\section jni_com_types Terminology
+
+First, lets cover the terminology that we use.
+
+
+An <b>Account</b> 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 forensics when parsing structured data (such as email messages) or keyword searching.
+
+
+Two accounts have a <b>relationship</b> 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 <b>relationship source</b> is where we learned about the relationship. This typically comes from Blackboard Artifacts, but may come from generic files in the future.
+
+\section jni_com_add Adding Communication Information to Database
+
+Now lets 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.
+
+When you encounter a message, the first thing to do is store information about the accounts. TSK wants to know about each <i>file</i> that had a reference of the account. You should call X…..
+
+
+
+
+\section OTHER ……
+
Things to cover:
- What to do when you encounter an Account.
diff --git a/bindings/java/src/org/sleuthkit/datamodel/AccountDeviceInstance.java b/bindings/java/src/org/sleuthkit/datamodel/AccountDeviceInstance.java
index 896b7676f..226e524a5 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/AccountDeviceInstance.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/AccountDeviceInstance.java
@@ -19,7 +19,7 @@
package org.sleuthkit.datamodel;
/**
- * Encapsulates an Account existing on a given device.
+ * Encapsulates an Account existing on a specific device.
*
* There is a 1:M:N relationship between
* Account, AccountDeviceInstance & AccountFileInstance
@@ -34,7 +34,7 @@ public class AccountDeviceInstance {
}
/**
- * Returns the underlying account
+ * Returns the underlying Account
*
* @return account
*/
@@ -43,7 +43,7 @@ public Account getAccount(){
}
/**
- * Returns the device Id
+ * Returns the device Id the Account existed on
*
* @return device id
*/
diff --git a/bindings/java/src/org/sleuthkit/datamodel/AccountFileInstance.java b/bindings/java/src/org/sleuthkit/datamodel/AccountFileInstance.java
index 683c79c1f..d2ee87ba5 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/AccountFileInstance.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/AccountFileInstance.java
@@ -22,11 +22,12 @@
/**
* An instance of an Account in a specific file.
- * An account may be found in multiple content
- * objects, so there can be up to one account instance per content object,
- * and there is a 1:N relationship between Account objects and AccountFileInstance
- * objects. Currently, there is an underlying TSK_ACCOUNT artifact for every
- * account instance. This may change in the future.
+ * An Account may be found in multiple Content
+ * objects (such as different databases) on a single device.
+ * There is a 1:N relationship between Account objects and AccountFileInstance
+ * objects. A TSK_ACCOUNT artifact is created for every account file instance.
+ *
+ * AccountFileInstances can optionally have BlackboardAttributes to store more details.
*/
public class AccountFileInstance {
private final BlackboardArtifact artifact;
@@ -38,8 +39,7 @@ public class AccountFileInstance {
}
/**
- * Gets the first occurrence of an attribute of the account instance
- * of a given type.
+ * Gets the first occurrence of an attribute by type.
*
* @param attrType The attribute type.
*
@@ -52,8 +52,7 @@ public BlackboardAttribute getAttribute(BlackboardAttribute.ATTRIBUTE_TYPE attrT
}
/**
- * Adds an attribute to the account instance. It is faster to
- * add them as part of a list.
+ * Adds an attribute. It is faster to add them as part of a list.
*
* @param bbatr The attribute to add.
*
@@ -64,7 +63,7 @@ public void addAttribute(BlackboardAttribute bbatr) throws TskCoreException {
}
/**
- * Adds a collection of attributes to the account instance
+ * Adds a collection of attributes
*
* @param bbatrs The collection of attributes to add.
*
@@ -75,7 +74,7 @@ public void addAttributes(Collection<BlackboardAttribute> bbatrs) throws TskCore
}
/**
- * Gets the account of which this object is an instance.
+ * Gets the underlying Account for this instance.
*
* @return The account.
*
diff --git a/bindings/java/src/org/sleuthkit/datamodel/CommunicationsManager.java b/bindings/java/src/org/sleuthkit/datamodel/CommunicationsManager.java
index ccf840d53..d3134e5a0 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/CommunicationsManager.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/CommunicationsManager.java
@@ -173,9 +173,11 @@ SleuthkitCase getSleuthkitCase() {
}
/**
- * Add an account type. Returns the type if it is already defined.
+ * Add a custom account type that is not already defined in Account.Type.
+ * Will not allow duplicates and will return existing type if the name is
+ * already defined.
*
- * @param accountTypeName account type name
+ * @param accountTypeName account type that must be unique
* @param displayName account type display name
*
* @return Account.Type
@@ -340,13 +342,13 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
// return accountInstance;
// }
/**
- * Add relationships between the sender and recipient account instances. All
- * accounts the relationship must be from the same data source.
+ * Add one or more relationships between the sender and recipient account instances. All
+ * account instances must be from the same data source.
*
* @param sender sender account
* @param recipients list of recipients
- * @param relationshipArtifact relationship artifact
- * @param relationshipType The type of relationship to be created
+ * @param sourceArtifact Artifact that relationships were derived from
+ * @param relationshipType The type of relationships to be created
* @param dateTime Date of communications/relationship, as epoch
* seconds
*
@@ -356,20 +358,20 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
* and the relationship are
* not from the same data
* source, or if the
- * relationshipArtifact and
+ * sourceArtifact and
* relationshipType are not
* compatible.
*/
public void addRelationships(AccountFileInstance sender, List<AccountFileInstance> recipients,
- BlackboardArtifact relationshipArtifact, Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
+ BlackboardArtifact sourceArtifact, Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
- if (relationshipType.isCreatableFrom(relationshipArtifact) == false) {
+ if (relationshipType.isCreatableFrom(sourceArtifact) == false) {
throw new TskDataException("Can not make a " + relationshipType.getDisplayName()
- + " relationship from a" + relationshipArtifact.getDisplayName());
+ + " relationship from a" + sourceArtifact.getDisplayName());
}
/*
- * Enforce that all accounts and the relationship between them on from
+ * Enforce that all accounts and the relationship between them are from
* the same 'source'. This is required for the queries to work
* correctly.
*/
@@ -378,17 +380,17 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
if (null != sender) {
accountIDs.add(sender.getAccount().getAccountID());
- if (sender.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+ if (sender.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
throw new TskDataException("Sender and relationship are from different data sources :"
- + "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+ + "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
}
}
for (AccountFileInstance recipient : recipients) {
accountIDs.add(recipient.getAccount().getAccountID());
- if (recipient.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+ if (recipient.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
throw new TskDataException("Recipient and relationship are from different data sources :"
- + "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+ + "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
}
}
@@ -399,12 +401,12 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
try {
UnorderedAccountPair accountPair = iter.next();
addAccountsRelationship(accountPair.getFirst(), accountPair.getSecond(),
- relationshipArtifact, relationshipType, dateTime);
+ sourceArtifact, relationshipType, dateTime);
} catch (TskCoreException ex) {
- LOGGER.log(Level.WARNING, "Could not get timezone for image", ex); //NON-NLS
+ // @@@ This should probably not be caught and instead we stop adding
+ LOGGER.log(Level.WARNING, "Error adding relationship", ex); //NON-NLS
}
}
-
}
/**
@@ -464,14 +466,14 @@ private Account getOrCreateAccount(Account.Type accountType, String accountUniqu
/**
* Get the blackboard artifact for the given account type, account ID, and
- * source file. Create an artifact and return that, of a matching doesn't
- * exists
+ * source file. Create an artifact if it doesn't already exist.
*
* @param accountType account type
- * @param accountUniqueID accountID
+ * @param accountUniqueID Unique account ID (such as email address)
+ * @param moduleName module name that found this instance (for the artifact)
* @param sourceFile Source file (for the artifact)
*
- * @return blackboard artifact, returns NULL is no matching account found
+ * @return blackboard artifact for the instance
*
* @throws TskCoreException exception thrown if a critical error occurs
* within TSK core
@@ -569,6 +571,7 @@ public Account.Type getAccountType(String accountTypeName) throws TskCoreExcepti
if (this.typeNameToAccountTypeMap.containsKey(accountTypeName)) {
return this.typeNameToAccountTypeMap.get(accountTypeName);
}
+
CaseDbConnection connection = db.getConnection();
db.acquireSingleUserCaseReadLock();
Statement s = null;
@@ -689,7 +692,8 @@ private void addAccountsRelationship(long account1_id, long account2_id, Blackbo
}
/**
- * Returns a list of AccountDeviceInstances that have any relationships.
+ * Returns a list of AccountDeviceInstances that at least one relationship that meets
+ * the criteria listed in the filters.
*
* Applicable filters: DeviceFilter, AccountTypeFilter, DateRangeFilter,
* RelationshipTypeFilter
@@ -794,12 +798,12 @@ public List<AccountDeviceInstance> getAccountDeviceInstancesWithRelationships(Co
}
/**
- * Get the number of unique relationship sources found for the given account
- * device instance.
- *
+ * Get the number of unique relationship sources (such as EMAIL artifacts) associated with
+ * an account on a given device (AccountDeviceInstance) that meet the filter criteria.
+ *
* Applicable filters: RelationshipTypeFilter, DateRangeFilter
*
- * @param accountDeviceInstance Account Device.
+ * @param accountDeviceInstance Account of interest
* @param filter Filters to apply.
*
* @return number of account relationships found for this account.
@@ -852,8 +856,8 @@ public long getRelationshipSourcesCount(AccountDeviceInstance accountDeviceInsta
}
/**
- * Get the unique relationship sources found for the given account device
- * instances.
+ * Get the unique relationship sources (such as EMAIL artifacts) associated with an
+ * account on a given device (AccountDeviceInstance) that meet the filter criteria.
*
* Applicable filters: RelationshipTypeFilter, DateRangeFilter
*
--
GitLab