VcardParser.java

Go to the documentation of this file.

/*
 * Autopsy Forensic Browser
 *
 * Copyright 2019 Basis Technology Corp.
 * Contact: carrier <at> sleuthkit <dot> org
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.sleuthkit.autopsy.thunderbirdparser;

import ezvcard.Ezvcard;
import ezvcard.VCard;
import ezvcard.parameter.EmailType;
import ezvcard.parameter.TelephoneType;
import ezvcard.property.Email;
import ezvcard.property.Organization;
import ezvcard.property.Photo;
import ezvcard.property.Telephone;
import ezvcard.property.Url;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.logging.Level;
import org.apache.commons.lang3.StringUtils;
import org.openide.util.NbBundle;
import org.sleuthkit.autopsy.casemodule.Case;
import org.sleuthkit.autopsy.casemodule.NoCurrentCaseException;
import org.sleuthkit.autopsy.casemodule.services.Blackboard;
import org.sleuthkit.autopsy.casemodule.services.FileManager;
import org.sleuthkit.autopsy.coreutils.Logger;
import org.sleuthkit.autopsy.coreutils.MessageNotifyUtil;
import org.sleuthkit.autopsy.ingest.IngestJobContext;
import org.sleuthkit.autopsy.ingest.IngestServices;
import org.sleuthkit.autopsy.ingest.ModuleContentEvent;
import org.sleuthkit.autopsy.ingest.ModuleDataEvent;
import static org.sleuthkit.autopsy.thunderbirdparser.ThunderbirdMboxFileIngestModule.getRelModuleOutputPath;
import org.sleuthkit.datamodel.AbstractFile;
import org.sleuthkit.datamodel.Account;
import org.sleuthkit.datamodel.AccountFileInstance;
import org.sleuthkit.datamodel.BlackboardArtifact;
import org.sleuthkit.datamodel.BlackboardAttribute;
import org.sleuthkit.datamodel.Content;
import org.sleuthkit.datamodel.DataSource;
import org.sleuthkit.datamodel.Relationship;
import org.sleuthkit.datamodel.SleuthkitCase;
import org.sleuthkit.datamodel.TskCoreException;
import org.sleuthkit.datamodel.TskData;
import org.sleuthkit.datamodel.TskDataException;
import org.sleuthkit.datamodel.TskException;

final class VcardParser {
    private static final String VCARD_HEADER = "BEGIN:VCARD";
    private static final long MIN_FILE_SIZE = 22;
    
    private static final String PHOTO_TYPE_BMP = "bmp";
    private static final String PHOTO_TYPE_GIF = "gif";
    private static final String PHOTO_TYPE_JPEG = "jpeg";
    private static final String PHOTO_TYPE_PNG = "png";
    private static final Map<String, String> photoTypeExtensions;
    static {
        photoTypeExtensions = new HashMap<>();
        photoTypeExtensions.put(PHOTO_TYPE_BMP, ".bmp");
        photoTypeExtensions.put(PHOTO_TYPE_GIF, ".gif");
        photoTypeExtensions.put(PHOTO_TYPE_JPEG, ".jpg");
        photoTypeExtensions.put(PHOTO_TYPE_PNG, ".png");
    }
    
    private static final Logger logger = Logger.getLogger(VcardParser.class.getName());
    
    private final IngestServices services = IngestServices.getInstance();
    private final FileManager fileManager;
    private final IngestJobContext context;
    private final Blackboard blackboard;
    private final Case currentCase;
    private final SleuthkitCase tskCase;
    
    VcardParser(Case currentCase, IngestJobContext context) {
        this.context = context;
        this.currentCase = currentCase;
        tskCase = currentCase.getSleuthkitCase();
        blackboard = currentCase.getServices().getBlackboard();
        fileManager = currentCase.getServices().getFileManager();
    }

    static boolean isVcardFile(Content content) {
        try {
            if (content.getSize() > MIN_FILE_SIZE) {
                byte[] buffer = new byte[VCARD_HEADER.length()];
                int byteRead = content.read(buffer, 0, VCARD_HEADER.length());
                if (byteRead > 0) {
                    String header = new String(buffer);
                    return header.equalsIgnoreCase(VCARD_HEADER);
                }
            }
        } catch (TskException ex) {
            logger.log(Level.WARNING, String.format("Exception while detecting if the file '%s' (id=%d) is a vCard file.",
                    content.getName(), content.getId())); //NON-NLS
        }
        
        return false;
    }
    
    void parse(File vcardFile, AbstractFile abstractFile) throws IOException, NoCurrentCaseException {
        VCard vcard = Ezvcard.parse(vcardFile).first();
        addContactArtifact(vcard, abstractFile);
    }
    
    
    
    @NbBundle.Messages({"VcardParser.addContactArtifact.indexError=Failed to index the contact artifact for keyword search."})
    private BlackboardArtifact addContactArtifact(VCard vcard, AbstractFile abstractFile) throws NoCurrentCaseException {
        List<BlackboardAttribute> attributes = new ArrayList<>();
        List<AccountFileInstance> accountInstances = new ArrayList<>();
        
        extractPhotos(vcard, abstractFile);
       
        String name = "";
        if (vcard.getFormattedName() != null) {
            name = vcard.getFormattedName().getValue();
        } else {
            if (vcard.getStructuredName() != null) {
                // Attempt to put the name together if there was no formatted version
                for (String prefix:vcard.getStructuredName().getPrefixes()) {
                    name += prefix + " ";
                }
                if (vcard.getStructuredName().getGiven() != null) {
                    name += vcard.getStructuredName().getGiven() + " ";
                }
                if (vcard.getStructuredName().getFamily() != null) {
                    name += vcard.getStructuredName().getFamily() + " ";
                }
                for (String suffix:vcard.getStructuredName().getSuffixes()) {
                    name += suffix + " ";
                }
                if (! vcard.getStructuredName().getAdditionalNames().isEmpty()) {
                    name += "(";
                    for (String addName:vcard.getStructuredName().getAdditionalNames()) {
                        name += addName + " ";
                    }
                    name += ")";
                }
            }
        }
        ThunderbirdMboxFileIngestModule.addArtifactAttribute(name, BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME_PERSON, attributes);
        
        for (Telephone telephone : vcard.getTelephoneNumbers()) {
            addPhoneAttributes(telephone, abstractFile, attributes);
            addPhoneAccountInstances(telephone, abstractFile, accountInstances);
        }
        
        for (Email email : vcard.getEmails()) {
            addEmailAttributes(email, abstractFile, attributes);
            addEmailAccountInstances(email, abstractFile, accountInstances);
        }
        
        for (Url url : vcard.getUrls()) {
            ThunderbirdMboxFileIngestModule.addArtifactAttribute(url.getValue(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_URL, attributes);
        }
        
        for (Organization organization : vcard.getOrganizations()) {
            List<String> values = organization.getValues();
            if (values.isEmpty() == false) {
                ThunderbirdMboxFileIngestModule.addArtifactAttribute(values.get(0), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_ORGANIZATION, attributes);
            }
        }
        
        AccountFileInstance deviceAccountInstance = addDeviceAccountInstance(abstractFile);
   
        BlackboardArtifact artifact = null;
        org.sleuthkit.datamodel.Blackboard tskBlackboard = tskCase.getBlackboard();
        try {
            // Create artifact if it doesn't already exist.
            if (!tskBlackboard.artifactExists(abstractFile, BlackboardArtifact.ARTIFACT_TYPE.TSK_CONTACT, attributes)) {
                artifact = abstractFile.newArtifact(BlackboardArtifact.ARTIFACT_TYPE.TSK_CONTACT);
                artifact.addAttributes(attributes);
                List<BlackboardArtifact> blackboardArtifacts = new ArrayList<>();
                blackboardArtifacts.add(artifact);
                
                // Add account relationships.
                if (deviceAccountInstance != null) {
                    try {
                        currentCase.getSleuthkitCase().getCommunicationsManager().addRelationships(
                                deviceAccountInstance, accountInstances, artifact, Relationship.Type.CONTACT, abstractFile.getCrtime());
                    } catch (TskDataException ex) {
                        logger.log(Level.SEVERE, String.format("Failed to create phone and e-mail account relationships (fileName='%s'; fileId=%d; accountId=%d).",
                                abstractFile.getName(), abstractFile.getId(), deviceAccountInstance.getAccount().getAccountID()), ex); //NON-NLS
                    }
                }
                
                // Index the artifact for keyword search.
                try {
                    blackboard.indexArtifact(artifact);
                } catch (Blackboard.BlackboardException ex) {
                    logger.log(Level.SEVERE, "Unable to index blackboard artifact " + artifact.getArtifactID(), ex); //NON-NLS
                    MessageNotifyUtil.Notify.error(Bundle.VcardParser_addContactArtifact_indexError(), artifact.getDisplayName());
                }
                
                // Fire event to notify UI of this new artifact.
                IngestServices.getInstance().fireModuleDataEvent(new ModuleDataEvent(
                        EmailParserModuleFactory.getModuleName(), BlackboardArtifact.ARTIFACT_TYPE.TSK_CONTACT,
                        blackboardArtifacts));
            }
        } catch (TskCoreException ex) {
            logger.log(Level.SEVERE, String.format("Failed to create contact artifact for vCard file '%s' (id=%d).",
                    abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
        }

        return artifact;
    }
    
    private void extractPhotos(VCard vcard, AbstractFile abstractFile) throws NoCurrentCaseException {
        String parentFileName = getUniqueName(abstractFile);
        // Skip files that already have been extracted.
        try {
            String outputPath = getOutputFolderPath(parentFileName);
            if (new File(outputPath).exists()) {
                List<Photo> vcardPhotos = vcard.getPhotos();
                List<AbstractFile> derivedFilesCreated = new ArrayList<>();
                for (int i=0; i < vcardPhotos.size(); i++) {
                    Photo photo = vcardPhotos.get(i);

                    if (photo.getUrl() != null) {
                        // Skip this photo since its data is not embedded.
                        continue;
                    }

                    String type = photo.getType();
                    if (type == null) {
                        // Skip this photo since no type is defined.
                        continue;
                    }

                    // Get the file extension for the subtype.
                    type = type.toLowerCase();
                    if (type.startsWith("image/")) {
                        type = type.substring(6);
                    }
                    String extension = photoTypeExtensions.get(type);

                    // Read the photo data and create a derived file from it.
                    byte[] data = photo.getData();
                    String extractedFileName = String.format("photo_%d%s", i, extension == null ? "" : extension);
                    String extractedFilePath = Paths.get(outputPath, extractedFileName).toString();
                    try {
                        writeExtractedImage(extractedFilePath, data);
                        derivedFilesCreated.add(fileManager.addDerivedFile(extractedFileName, getFileRelativePath(parentFileName, extractedFileName), data.length,
                                abstractFile.getCtime(), abstractFile.getCrtime(), abstractFile.getAtime(), abstractFile.getAtime(),
                                true, abstractFile, null, EmailParserModuleFactory.getModuleName(), null, null, TskData.EncodingType.NONE));
                    } catch (IOException | TskCoreException ex) {
                        logger.log(Level.WARNING, String.format("Could not write image to '%s' (id=%d).", extractedFilePath, abstractFile.getId()), ex); //NON-NLS
                    }
                }
                if (!derivedFilesCreated.isEmpty()) {
                    services.fireModuleContentEvent(new ModuleContentEvent(abstractFile));
                    context.addFilesToJob(derivedFilesCreated);
                }
            }
            else {
                logger.log(Level.INFO, String.format("Skipping photo extraction for file '%s' (id=%d), because it has already been processed.",
                        abstractFile.getName(), abstractFile.getId())); //NON-NLS
            }
        } catch (SecurityException ex) {
            logger.log(Level.WARNING, String.format("Could not create extraction folder for '%s' (id=%d).", parentFileName, abstractFile.getId()));
        }
    }
    
    private void writeExtractedImage(String outputPath, byte[] data) throws IOException {
        File outputFile = new File(outputPath);
        FileOutputStream outputStream = new FileOutputStream(outputFile);
        outputStream.write(data);
    }
    
    private String getUniqueName(AbstractFile file) {
        return file.getName() + "_" + file.getId();
    }
    
    private String getFileRelativePath(String parentFileName, String fileName) throws NoCurrentCaseException {
        // Used explicit FWD slashes to maintain DB consistency across operating systems.
        return Paths.get(getRelModuleOutputPath(), parentFileName, fileName).toString();
    }
    
    private String getOutputFolderPath(String parentFileName) throws NoCurrentCaseException {
        String outputFolderPath = ThunderbirdMboxFileIngestModule.getModuleOutputPath() + File.separator + parentFileName;
        File outputFilePath = new File(outputFolderPath);
        if (!outputFilePath.exists()) {
            outputFilePath.mkdirs();
        }
        return outputFolderPath;
    }
    
    private void addPhoneAttributes(Telephone telephone, AbstractFile abstractFile, Collection<BlackboardAttribute> attributes) {
        String telephoneText = telephone.getText();
        if (telephoneText == null || telephoneText.isEmpty()) {
            return;
        }

        // Add phone number to collection for later creation of TSK_CONTACT.
        List<TelephoneType> telephoneTypes = telephone.getTypes();
        if (telephoneTypes.isEmpty()) {
            ThunderbirdMboxFileIngestModule.addArtifactAttribute(telephone.getText(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_PHONE_NUMBER, attributes);
        } else {
            for (TelephoneType type : telephoneTypes) {
                /*
                 * Unfortunately, if the types are lower-case, they don't
                 * get separated correctly into individual TelephoneTypes by
                 * ez-vcard. Therefore, we must read them manually
                 * ourselves.
                 */
                List<String> splitTelephoneTypes = Arrays.asList(
                        type.getValue().toUpperCase().replaceAll("\\s+","").split(","));

                for (String splitType : splitTelephoneTypes) {
                    String attributeTypeName = "TSK_PHONE_" + splitType;
                    try {
                        BlackboardAttribute.Type attributeType = tskCase.getAttributeType(attributeTypeName);
                        if (attributeType == null) {
                            // Add this attribute type to the case database.
                            attributeType = tskCase.addArtifactAttributeType(attributeTypeName,
                                    BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.STRING,
                                    String.format("Phone (%s)", StringUtils.capitalize(splitType.toLowerCase())));
                        }
                        ThunderbirdMboxFileIngestModule.addArtifactAttribute(telephone.getText(), attributeType, attributes);
                    } catch (TskCoreException ex) {
                        logger.log(Level.SEVERE, String.format("Unable to retrieve attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
                    } catch (TskDataException ex) {
                        logger.log(Level.SEVERE, String.format("Unable to add custom attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
                    }
                }
            }
        }
    }
    
    private void addEmailAttributes(Email email, AbstractFile abstractFile, Collection<BlackboardAttribute> attributes) {
        String emailValue = email.getValue();
        if (emailValue == null || emailValue.isEmpty()) {
            return;
        }

        // Add phone number to collection for later creation of TSK_CONTACT.
        List<EmailType> emailTypes = email.getTypes();
        if (emailTypes.isEmpty()) {
            ThunderbirdMboxFileIngestModule.addArtifactAttribute(email.getValue(), BlackboardAttribute.ATTRIBUTE_TYPE.TSK_EMAIL, attributes);
        } else {
            for (EmailType type : emailTypes) {
                /*
                 * Unfortunately, if the types are lower-case, they don't
                 * get separated correctly into individual EmailTypes by
                 * ez-vcard. Therefore, we must read them manually
                 * ourselves.
                 */
                List<String> splitEmailTypes = Arrays.asList(
                        type.getValue().toUpperCase().replaceAll("\\s+","").split(","));

                for (String splitType : splitEmailTypes) {
                    String attributeTypeName = "TSK_EMAIL_" + splitType;
                    try {
                        BlackboardAttribute.Type attributeType = tskCase.getAttributeType(attributeTypeName);
                        if (attributeType == null) {
                            // Add this attribute type to the case database.
                            attributeType = tskCase.addArtifactAttributeType(attributeTypeName, 
                                    BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.STRING, 
                                    String.format("Email (%s)", StringUtils.capitalize(splitType.toLowerCase())));
                        }
                        ThunderbirdMboxFileIngestModule.addArtifactAttribute(email.getValue(), attributeType, attributes);
                    } catch (TskCoreException ex) {
                        logger.log(Level.SEVERE, String.format("Unable to retrieve attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
                    } catch (TskDataException ex) {
                        logger.log(Level.SEVERE, String.format("Unable to add custom attribute type '%s' for file '%s' (id=%d).", attributeTypeName, abstractFile.getName(), abstractFile.getId()), ex);
                    }
                }
            }
        }
    }
    
    private void addPhoneAccountInstances(Telephone telephone, AbstractFile abstractFile, Collection<AccountFileInstance> accountInstances) {
        String telephoneText = telephone.getText();
        if (telephoneText == null || telephoneText.isEmpty()) {
            return;
        }

        // Add phone number as a TSK_ACCOUNT.
        try {
            AccountFileInstance phoneAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.PHONE,
                    telephoneText, EmailParserModuleFactory.getModuleName(), abstractFile);
            accountInstances.add(phoneAccountInstance);
        }
        catch(TskCoreException ex) {
             logger.log(Level.WARNING, String.format(
                     "Failed to create account for phone number '%s' (content='%s'; id=%d).",
                     telephoneText, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
        }
    }
    
    private void addEmailAccountInstances(Email email, AbstractFile abstractFile, Collection<AccountFileInstance> accountInstances) {
        String emailValue = email.getValue();
        if (emailValue == null || emailValue.isEmpty()) {
            return;
        }

        // Add e-mail as a TSK_ACCOUNT.
        try {
            AccountFileInstance emailAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.EMAIL,
                    emailValue, EmailParserModuleFactory.getModuleName(), abstractFile);
            accountInstances.add(emailAccountInstance);
        }
        catch(TskCoreException ex) {
             logger.log(Level.WARNING, String.format(
                     "Failed to create account for e-mail address '%s' (content='%s'; id=%d).",
                     emailValue, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
        }
    }
    
    private AccountFileInstance addDeviceAccountInstance(AbstractFile abstractFile) {
        // Add 'DEVICE' TSK_ACCOUNT.
        AccountFileInstance deviceAccountInstance = null;
        String deviceId = null;
        try {
            long dataSourceObjId = abstractFile.getDataSourceObjectId();
            DataSource dataSource = tskCase.getDataSource(dataSourceObjId);
            deviceId = dataSource.getDeviceId();
            deviceAccountInstance = tskCase.getCommunicationsManager().createAccountFileInstance(Account.Type.DEVICE,
                    deviceId, EmailParserModuleFactory.getModuleName(), abstractFile);
        }
        catch (TskCoreException ex) {
            logger.log(Level.WARNING, String.format(
                    "Failed to create device account for '%s' (content='%s'; id=%d).",
                    deviceId, abstractFile.getName(), abstractFile.getId()), ex); //NON-NLS
        }
        catch (TskDataException ex) {
            logger.log(Level.WARNING, String.format(
                    "Failed to get the data source from the case database (id=%d).",
                    abstractFile.getId()), ex); //NON-NLS
        }
        
        return deviceAccountInstance;
    }
}