Autopsy  4.19.1
Graphical digital forensics platform for The Sleuth Kit and other tools.
VcardParser.java
Go to the documentation of this file.
1 /*
2  * Autopsy Forensic Browser
3  *
4  * Copyright 2019 Basis Technology Corp.
5  * Contact: carrier <at> sleuthkit <dot> org
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19 package org.sleuthkit.autopsy.thunderbirdparser;
20 
21 import ezvcard.Ezvcard;
22 import ezvcard.VCard;
23 import ezvcard.parameter.EmailType;
24 import ezvcard.parameter.TelephoneType;
25 import ezvcard.property.Email;
26 import ezvcard.property.Organization;
27 import ezvcard.property.Photo;
28 import ezvcard.property.Telephone;
29 import ezvcard.property.Url;
30 import java.io.File;
31 import java.io.FileOutputStream;
32 import java.io.IOException;
33 import java.nio.file.Paths;
34 import java.util.ArrayList;
35 import java.util.Arrays;
36 import java.util.Collection;
37 import java.util.HashMap;
38 import java.util.List;
39 import java.util.Map;
40 import java.util.logging.Level;
41 import org.apache.commons.lang3.StringUtils;
42 import org.openide.util.NbBundle;
51 import static org.sleuthkit.autopsy.thunderbirdparser.ThunderbirdMboxFileIngestModule.getRelModuleOutputPath;
52 import org.sleuthkit.datamodel.AbstractFile;
53 import org.sleuthkit.datamodel.Account;
54 import org.sleuthkit.datamodel.AccountFileInstance;
55 import org.sleuthkit.datamodel.Blackboard;
56 import org.sleuthkit.datamodel.Blackboard.BlackboardException;
57 import org.sleuthkit.datamodel.BlackboardArtifact;
58 import org.sleuthkit.datamodel.BlackboardAttribute;
59 import org.sleuthkit.datamodel.Content;
60 import org.sleuthkit.datamodel.DataSource;
61 import org.sleuthkit.datamodel.ReadContentInputStream;
62 import org.sleuthkit.datamodel.Relationship;
63 import org.sleuthkit.datamodel.SleuthkitCase;
64 import org.sleuthkit.datamodel.TskCoreException;
65 import org.sleuthkit.datamodel.TskData;
66 import org.sleuthkit.datamodel.TskDataException;
67 import org.sleuthkit.datamodel.TskException;
68 
73 final class VcardParser {
74  private static final String VCARD_HEADER = "BEGIN:VCARD";
75  private static final long MIN_FILE_SIZE = 22;
76 
77  private static final String PHOTO_TYPE_BMP = "bmp";
78  private static final String PHOTO_TYPE_GIF = "gif";
79  private static final String PHOTO_TYPE_JPEG = "jpeg";
80  private static final String PHOTO_TYPE_PNG = "png";
81  private static final Map<String, String> photoTypeExtensions;
82  static {
83  photoTypeExtensions = new HashMap<>();
84  photoTypeExtensions.put(PHOTO_TYPE_BMP, ".bmp");
85  photoTypeExtensions.put(PHOTO_TYPE_GIF, ".gif");
86  photoTypeExtensions.put(PHOTO_TYPE_JPEG, ".jpg");
87  photoTypeExtensions.put(PHOTO_TYPE_PNG, ".png");
88  }
89 
90  private static final Logger logger = Logger.getLogger(VcardParser.class.getName());
91 
92  private final IngestServices services = IngestServices.getInstance();
93  private final FileManager fileManager;
94  private final IngestJobContext context;
95  private final Blackboard blackboard;
96  private final Case currentCase;
97  private final SleuthkitCase tskCase;
98 
102  VcardParser(Case currentCase, IngestJobContext context) {
103  this.context = context;
104  this.currentCase = currentCase;
105  tskCase = currentCase.getSleuthkitCase();
106  blackboard = tskCase.getBlackboard();
107  fileManager = currentCase.getServices().getFileManager();
108  }
109 
117  static boolean isVcardFile(Content content) {
118  try {
119  if (content.getSize() > MIN_FILE_SIZE) {
120  byte[] buffer = new byte[VCARD_HEADER.length()];
121  int byteRead = content.read(buffer, 0, VCARD_HEADER.length());
122  if (byteRead > 0) {
123  String header = new String(buffer);
124  return header.equalsIgnoreCase(VCARD_HEADER);
125  }
126  }
127  } catch (TskException ex) {
128  logger.log(Level.WARNING, String.format("Exception while detecting if the file '%s' (id=%d) is a vCard file.",
129  content.getName(), content.getId())); //NON-NLS
130  }
131 
132  return false;
133  }
134 
146  void parse(AbstractFile abstractFile) throws IOException, NoCurrentCaseException {
147  for (VCard vcard: Ezvcard.parse(new ReadContentInputStream(abstractFile)).all()) {
148  addContactArtifact(vcard, abstractFile);
149  }
150  }
151 
152 
153 
164  @NbBundle.Messages({"VcardParser.addContactArtifact.indexError=Failed to index the contact artifact for keyword search."})
165  private BlackboardArtifact addContactArtifact(VCard vcard, AbstractFile abstractFile) throws NoCurrentCaseException {
166  List<BlackboardAttribute> attributes = new ArrayList<>();
167  List<AccountFileInstance> accountInstances = new ArrayList<>();
168 
169  String name = "";
170  if (vcard.getFormattedName() != null) {
171  name = vcard.getFormattedName().getValue();
172  } else {
173  if (vcard.getStructuredName() != null) {
174  // Attempt to put the name together if there was no formatted version
175  for (String prefix:vcard.getStructuredName().getPrefixes()) {
176  name += prefix + " ";
177  }
178  if (vcard.getStructuredName().getGiven() != null) {
179  name += vcard.getStructuredName().getGiven() + " ";
180  }
181  if (vcard.getStructuredName().getFamily() != null) {
182  name += vcard.getStructuredName().getFamily() + " ";
183  }
184  for (String suffix:vcard.getStructuredName().getSuffixes()) {
185  name += suffix + " ";
186  }
187  if (! vcard.getStructuredName().getAdditionalNames().isEmpty()) {
188  name += "(";
189  for (String addName:vcard.getStructuredName().getAdditionalNames()) {
190  name += addName + " ";
191  }
192  name += ")";
193  }
194  }
195  }
196  ThunderbirdMboxFileIngestModule.addArtifactAttribute(name, BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME, attributes);
197 
198  for (Telephone telephone : vcard.getTelephoneNumbers()) {
199  addPhoneAttributes(telephone, abstractFile, attributes);
200  addPhoneAccountInstances(telephone, abstractFile, accountInstances);
201  }
202 
203  for (Email email : vcard.getEmails()) {
204  addEmailAttributes(email, abstractFile, attributes);
205  addEmailAccountInstances(email, abstractFile, accountInstances);
206  }
207 
208  for (Url url : vcard.getUrls()) {
209  ThunderbirdMboxFileIngestModule.addArtifactAttribute(url.getValue(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_URL, attributes);
210  }
211 
212  for (Organization organization : vcard.getOrganizations()) {
213  List<String> values = organization.getValues();
214  if (values.isEmpty() == false) {
215  ThunderbirdMboxFileIngestModule.addArtifactAttribute(values.get(0), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_ORGANIZATION, attributes);
216  }
217  }
218 
219  AccountFileInstance deviceAccountInstance = addDeviceAccountInstance(abstractFile);
220 
221  BlackboardArtifact artifact = null;
222  org.sleuthkit.datamodel.Blackboard tskBlackboard = tskCase.getBlackboard();
223  try {
224  // Create artifact if it doesn't already exist.
225  if (!tskBlackboard.artifactExists(abstractFile, BlackboardArtifact.ARTIFACT_TYPE.TSK_CONTACT, attributes)) {
226  artifact = abstractFile.newDataArtifact(new BlackboardArtifact.Type(BlackboardArtifact.ARTIFACT_TYPE.TSK_CONTACT), attributes);
227 
228  extractPhotos(vcard, abstractFile, artifact);
229 
230  // Add account relationships.
231  if (deviceAccountInstance != null) {
232  try {
233  currentCase.getSleuthkitCase().getCommunicationsManager().addRelationships(
234  deviceAccountInstance, accountInstances, artifact, Relationship.Type.CONTACT, abstractFile.getCrtime());
235  } catch (TskDataException ex) {
236  logger.log(Level.SEVERE, String.format("Failed to create phone and e-mail account relationships (fileName='%s'; fileId=%d; accountId=%d).",
237  abstractFile.getName(), abstractFile.getId(), deviceAccountInstance.getAccount().getAccountID()), ex); //NON-NLS
238  }
239  }
240 
241  // Index the artifact for keyword search.
242  try {
243  blackboard.postArtifact(artifact, EmailParserModuleFactory.getModuleName());
244  } catch (Blackboard.BlackboardException ex) {
245  logger.log(Level.SEVERE, "Unable to index blackboard artifact " + artifact.getArtifactID(), ex); //NON-NLS
246  MessageNotifyUtil.Notify.error(Bundle.VcardParser_addContactArtifact_indexError(), artifact.getDisplayName());
247  }
248  }
249  } catch (TskCoreException ex) {
250  logger.log(Level.SEVERE, String.format("Failed to create contact artifact for vCard file '%s' (id=%d).",
251  abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
252  }
253 
254  return artifact;
255  }
256 
265  private void extractPhotos(VCard vcard, AbstractFile abstractFile, BlackboardArtifact artifact) throws NoCurrentCaseException {
266  String parentFileName = getUniqueName(abstractFile);
267  // Skip files that already have been extracted.
268  try {
269  String outputPath = getOutputFolderPath(parentFileName);
270  if (new File(outputPath).exists()) {
271  List<Photo> vcardPhotos = vcard.getPhotos();
272  List<AbstractFile> derivedFilesCreated = new ArrayList<>();
273  for (int i=0; i < vcardPhotos.size(); i++) {
274  Photo photo = vcardPhotos.get(i);
275 
276  if (photo.getUrl() != null) {
277  // Skip this photo since its data is not embedded.
278  continue;
279  }
280 
281  String type = photo.getType();
282  if (type == null) {
283  // Skip this photo since no type is defined.
284  continue;
285  }
286 
287  // Get the file extension for the subtype.
288  type = type.toLowerCase();
289  if (type.startsWith("image/")) {
290  type = type.substring(6);
291  }
292  String extension = photoTypeExtensions.get(type);
293 
294  // Read the photo data and create a derived file from it.
295  byte[] data = photo.getData();
296  String extractedFileName = String.format("photo_%d%s", i, extension == null ? "" : extension);
297  String extractedFilePath = Paths.get(outputPath, extractedFileName).toString();
298  try {
299  writeExtractedImage(extractedFilePath, data);
300  derivedFilesCreated.add(fileManager.addDerivedFile(extractedFileName, getFileRelativePath(parentFileName, extractedFileName), data.length,
301  abstractFile.getCtime(), abstractFile.getCrtime(), abstractFile.getAtime(), abstractFile.getAtime(),
302  true, artifact, null, EmailParserModuleFactory.getModuleName(), EmailParserModuleFactory.getModuleVersion(), "", TskData.EncodingType.NONE));
303  } catch (IOException | TskCoreException ex) {
304  logger.log(Level.WARNING, String.format("Could not write image to '%s' (id=%d).", extractedFilePath, abstractFile.getId()), ex); //NON-NLS
305  }
306  }
307  if (!derivedFilesCreated.isEmpty()) {
308  services.fireModuleContentEvent(new ModuleContentEvent(abstractFile));
309  context.addFilesToJob(derivedFilesCreated);
310  }
311  }
312  else {
313  logger.log(Level.INFO, String.format("Skipping photo extraction for file '%s' (id=%d), because it has already been processed.",
314  abstractFile.getName(), abstractFile.getId())); //NON-NLS
315  }
316  } catch (SecurityException ex) {
317  logger.log(Level.WARNING, String.format("Could not create extraction folder for '%s' (id=%d).", parentFileName, abstractFile.getId()));
318  }
319  }
320 
328  private void writeExtractedImage(String outputPath, byte[] data) throws IOException {
329  File outputFile = new File(outputPath);
330  FileOutputStream outputStream = new FileOutputStream(outputFile);
331  outputStream.write(data);
332  }
333 
342  private String getUniqueName(AbstractFile file) {
343  return file.getName() + "_" + file.getId();
344  }
345 
355  private String getFileRelativePath(String parentFileName, String fileName) throws NoCurrentCaseException {
356  // Used explicit FWD slashes to maintain DB consistency across operating systems.
357  return Paths.get(getRelModuleOutputPath(), parentFileName, fileName).toString();
358  }
359 
370  private String getOutputFolderPath(String parentFileName) throws NoCurrentCaseException {
371  String outputFolderPath = ThunderbirdMboxFileIngestModule.getModuleOutputPath() + File.separator + parentFileName;
372  File outputFilePath = new File(outputFolderPath);
373  if (!outputFilePath.exists()) {
374  outputFilePath.mkdirs();
375  }
376  return outputFolderPath;
377  }
378 
387  private void addPhoneAttributes(Telephone telephone, AbstractFile abstractFile, Collection<BlackboardAttribute> attributes) {
388  String telephoneText = telephone.getText();
389 
390  if (telephoneText == null || telephoneText.isEmpty()) {
391  if (telephone.getUri() == null) {
392  return;
393  }
394  telephoneText = telephone.getUri().getNumber();
395  if (telephoneText == null || telephoneText.isEmpty()) {
396  return;
397  }
398  }
399 
400  // Add phone number to collection for later creation of TSK_CONTACT.
401  List<TelephoneType> telephoneTypes = telephone.getTypes();
402  if (telephoneTypes.isEmpty()) {
403  ThunderbirdMboxFileIngestModule.addArtifactAttribute(telephone.getText(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_PHONE_NUMBER, attributes);
404  } else {
405  TelephoneType type = telephoneTypes.get(0);
406  /*
407  * Unfortunately, if the types are lower-case, they don't
408  * get separated correctly into individual TelephoneTypes by
409  * ez-vcard. Therefore, we must read them manually
410  * ourselves.
411  */
412  List<String> splitTelephoneTypes = Arrays.asList(
413  type.getValue().toUpperCase().replaceAll("\\s+","").split(","));
414 
415  if (splitTelephoneTypes.size() > 0) {
416  String splitType = splitTelephoneTypes.get(0);
417  String attributeTypeName = "TSK_PHONE_NUMBER";
418  if (splitType != null && !splitType.isEmpty()) {
419  attributeTypeName = "TSK_PHONE_NUMBER_" + splitType;
420  }
421 
422  try {
423  BlackboardAttribute.Type attributeType = tskCase.getAttributeType(attributeTypeName);
424  if (attributeType == null) {
425  try{
426  // Add this attribute type to the case database.
427  attributeType = tskCase.getBlackboard().getOrAddAttributeType(attributeTypeName,
428  BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.STRING,
429  String.format("Phone Number (%s)", StringUtils.capitalize(splitType.toLowerCase())));
430 
431  ThunderbirdMboxFileIngestModule.addArtifactAttribute(telephoneText, attributeType, attributes);
432  }catch (BlackboardException ex) {
433  logger.log(Level.WARNING, String.format("Unable to retrieve attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
434  }
435  }
436 
437  } catch (TskCoreException ex) {
438  logger.log(Level.WARNING, String.format("Unable to retrieve attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
439  }
440  }
441  }
442  }
443 
452  private void addEmailAttributes(Email email, AbstractFile abstractFile, Collection<BlackboardAttribute> attributes) {
453  String emailValue = email.getValue();
454  if (emailValue == null || emailValue.isEmpty()) {
455  return;
456  }
457 
458  // Add phone number to collection for later creation of TSK_CONTACT.
459  List<EmailType> emailTypes = email.getTypes();
460  if (emailTypes.isEmpty()) {
461  ThunderbirdMboxFileIngestModule.addArtifactAttribute(email.getValue(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_EMAIL, attributes);
462  } else {
463  EmailType type = emailTypes.get(0); /*
464  * Unfortunately, if the types are lower-case, they don't
465  * get separated correctly into individual EmailTypes by
466  * ez-vcard. Therefore, we must read them manually
467  * ourselves.
468  */
469  List<String> splitEmailTypes = Arrays.asList(
470  type.getValue().toUpperCase().replaceAll("\\s+","").split(","));
471 
472  if (splitEmailTypes.size() > 0) {
473  String splitType = splitEmailTypes.get(0);
474  String attributeTypeName = "TSK_EMAIL_" + splitType;
475  if(splitType.isEmpty()) {
476  attributeTypeName = "TSK_EMAIL";
477  }
478  try {
479  BlackboardAttribute.Type attributeType = tskCase.getAttributeType(attributeTypeName);
480  if (attributeType == null) {
481  // Add this attribute type to the case database.
482  attributeType = tskCase.getBlackboard().getOrAddAttributeType(attributeTypeName,
483  BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.STRING,
484  String.format("Email (%s)", StringUtils.capitalize(splitType.toLowerCase())));
485  }
486  ThunderbirdMboxFileIngestModule.addArtifactAttribute(email.getValue(), attributeType, attributes);
487  } catch (TskCoreException ex) {
488  logger.log(Level.SEVERE, String.format("Unable to retrieve attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
489  } catch (BlackboardException ex) {
490  logger.log(Level.SEVERE, String.format("Unable to add custom attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
491  }
492  }
493  }
494  }
495 
505  private void addPhoneAccountInstances(Telephone telephone, AbstractFile abstractFile, Collection<AccountFileInstance> accountInstances) {
506  String telephoneText = telephone.getText();
507  if (telephoneText == null || telephoneText.isEmpty()) {
508  if (telephone.getUri() == null) {
509  return;
510  }
511  telephoneText = telephone.getUri().getNumber();
512  if (telephoneText == null || telephoneText.isEmpty()) {
513  return;
514  }
515 
516  }
517 
518  // Add phone number as a TSK_ACCOUNT.
519  try {
520  AccountFileInstance phoneAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.PHONE,
521  telephoneText, EmailParserModuleFactory.getModuleName(), abstractFile);
522  accountInstances.add(phoneAccountInstance);
523  }
524  catch(TskCoreException ex) {
525  logger.log(Level.WARNING, String.format(
526  "Failed to create account for phone number '%s' (content='%s'; id=%d).",
527  telephoneText, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
528  }
529  }
530 
540  private void addEmailAccountInstances(Email email, AbstractFile abstractFile, Collection<AccountFileInstance> accountInstances) {
541  String emailValue = email.getValue();
542  if (emailValue == null || emailValue.isEmpty()) {
543  return;
544  }
545 
546  // Add e-mail as a TSK_ACCOUNT.
547  try {
548  AccountFileInstance emailAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.EMAIL,
549  emailValue, EmailParserModuleFactory.getModuleName(), abstractFile);
550  accountInstances.add(emailAccountInstance);
551  }
552  catch(TskCoreException ex) {
553  logger.log(Level.WARNING, String.format(
554  "Failed to create account for e-mail address '%s' (content='%s'; id=%d).",
555  emailValue, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
556  }
557  }
558 
566  private AccountFileInstance addDeviceAccountInstance(AbstractFile abstractFile) {
567  // Add 'DEVICE' TSK_ACCOUNT.
568  AccountFileInstance deviceAccountInstance = null;
569  String deviceId = null;
570  try {
571  long dataSourceObjId = abstractFile.getDataSourceObjectId();
572  DataSource dataSource = tskCase.getDataSource(dataSourceObjId);
573  deviceId = dataSource.getDeviceId();
574  deviceAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.DEVICE,
575  deviceId, EmailParserModuleFactory.getModuleName(), abstractFile);
576  }
577  catch (TskCoreException ex) {
578  logger.log(Level.WARNING, String.format(
579  "Failed to create device account for '%s' (content='%s'; id=%d).",
580  deviceId, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
581  }
582  catch (TskDataException ex) {
583  logger.log(Level.WARNING, String.format(
584  "Failed to get the data source from the case database (id=%d).",
585  abstractFile.getId()), ex); //NON-NLS
586  }
587 
588  return deviceAccountInstance;
589  }
590 }

Copyright © 2012-2021 Basis Technology. Generated on: Thu Sep 30 2021
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.