Persona.java

Go to the documentation of this file.

/*
 * Central Repository
 *
 * Copyright 2020 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.centralrepository.datamodel;

import java.sql.ResultSet;
import java.sql.SQLException;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
import java.util.UUID;
import org.apache.commons.lang3.StringUtils;
import org.openide.util.NbBundle;

public class Persona {

    public enum Confidence {
        LOW(1, "Low confidence"),
        MODERATE(2, "Moderate confidence"),
        HIGH(3, "High confidence");

        private final String name;
        private final int level_id;

        Confidence(int level, String name) {
            this.name = name;
            this.level_id = level;

        }

        @Override
        public String toString() {
            return name;
        }

        public int getLevelId() {
            return this.level_id;
        }

        static Confidence fromId(int value) {
            for (Confidence confidence : Confidence.values()) {
                if (confidence.getLevelId() == value) {
                    return confidence;
                }
            }
            return Confidence.LOW;
        }

    }

    public enum PersonaStatus {

        UNKNOWN(1, "Unknown"),
        ACTIVE(2, "Active"),
        MERGED(3, "Merged"),
        SPLIT(4, "Split"),
        DELETED(5, "Deleted");

        private final String description;
        private final int status_id;

        PersonaStatus(int status, String description) {
            this.status_id = status;
            this.description = description;
        }

        @Override
        public String toString() {
            return description;
        }

        public int getStatusId() {
            return this.status_id;
        }

        static PersonaStatus fromId(int value) {
            for (PersonaStatus status : PersonaStatus.values()) {
                if (status.getStatusId() == value) {
                    return status;
                }
            }
            return PersonaStatus.UNKNOWN;
        }
    }

    // primary key in the Personas table in CR database
    private final long id;
    private final String uuidStr;
    private final String name;
    private final String comment;
    private final long createdDate;
    private final long modifiedDate;
    private final PersonaStatus status;
    private final CentralRepoExaminer examiner;

    @NbBundle.Messages("Persona.defaultName=Unnamed")
    public static String getDefaultName() {
        return Bundle.Persona_defaultName();
    }

    public long getId() {
        return id;
    }

    public String getUuidStr() {
        return uuidStr;
    }

    public String getName() {
        return name;
    }

    public String getComment() {
        return comment;
    }

    public long getCreatedDate() {
        return createdDate;
    }

    public long getModifiedDate() {
        return modifiedDate;
    }

    public PersonaStatus getStatus() {
        return status;
    }

    public CentralRepoExaminer getExaminer() {
        return examiner;
    }

    Persona(long id, String uuidStr, String name, String comment, long created_date, long modified_date, PersonaStatus status, CentralRepoExaminer examiner) {
        this.id = id;
        this.uuidStr = uuidStr;
        this.name = name;
        this.comment = comment;
        this.createdDate = created_date;
        this.modifiedDate = modified_date;
        this.status = status;
        this.examiner = examiner;
    }

    @Override
    public int hashCode() {
        int hash = 7;
        hash = 67 * hash + (int) (this.id ^ (this.id >>> 32));
        hash = 67 * hash + Objects.hashCode(this.uuidStr);
        return hash;
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final Persona other = (Persona) obj;
        if (this.id != other.getId()) {
            return false;
        }
        return this.uuidStr.equalsIgnoreCase(other.getUuidStr());
    }

    public static Persona createPersonaForAccount(String personaName, String comment, PersonaStatus status, CentralRepoAccount account, String justification, Persona.Confidence confidence) throws CentralRepoException {
        Persona persona = createPersona(personaName, comment, status);
        persona.addAccount(account, justification, confidence);
        return persona;
    }

    private static Persona createPersona(String name, String comment, PersonaStatus status) throws CentralRepoException {
        // generate a UUID for the persona
        String uuidStr = UUID.randomUUID().toString();
        CentralRepoExaminer examiner = getCRInstance().getOrInsertExaminer(System.getProperty("user.name"));

        Instant instant = Instant.now();
        Long timeStampMillis = instant.toEpochMilli();

        String insertPersonaSQL = "INSERT INTO personas (uuid, comment, name, created_date, modified_date, status_id, examiner_id ) " //NON-NLS
                + " VALUES (?, ?, ?, ?, ?, ?, ?)";
        List<Object> params = new ArrayList<>();
        params.add(uuidStr);
        params.add(StringUtils.isBlank(comment) ? "" : comment);
        params.add(StringUtils.isBlank(name) ? getDefaultName() : name);
        params.add(timeStampMillis);
        params.add(timeStampMillis);
        params.add(status.getStatusId());
        params.add(examiner.getId());

        getCRInstance().executeCommand(insertPersonaSQL, params);
        return getPersonaByUUID(uuidStr);
    }

    public void setComment(String comment) throws CentralRepoException {
        String updateSQL = "UPDATE personas SET comment = ? WHERE id = ?";
        CentralRepository cr = CentralRepository.getInstance();
        if (cr != null) {
            List<Object> params = new ArrayList<>();
            params.add(StringUtils.isBlank(comment) ? "" : comment);
            params.add(id);

            getCRInstance().executeCommand(updateSQL, params);
        }
    }

    public void setName(String name) throws CentralRepoException {
        String updateSQL = "UPDATE personas SET name = ? WHERE id = ?";
        CentralRepository cr = CentralRepository.getInstance();
        if (cr != null) {
            List<Object> params = new ArrayList<>();
            params.add(StringUtils.isBlank(name) ? getDefaultName() : name);
            params.add(id);

            getCRInstance().executeCommand(updateSQL, params);
        }
    }

    public PersonaAccount addAccount(CentralRepoAccount account, String justification, Persona.Confidence confidence) throws CentralRepoException {
        return PersonaAccount.addPersonaAccount(this, account, justification, confidence);
    }

    public void removeAccount(PersonaAccount account) throws CentralRepoException {
        PersonaAccount.removePersonaAccount(account.getId());
    }

    public void modifyAccount(PersonaAccount account, Confidence confidence, String justification) throws CentralRepoException {
        PersonaAccount.modifyPersonaAccount(account.getId(), confidence, justification);
    }

    public void delete() throws CentralRepoException {
        String deleteSQL = "UPDATE personas SET status_id = ? WHERE id = ?";
        CentralRepository cr = CentralRepository.getInstance();
        if (cr != null) {
            List<Object> params = new ArrayList<>();
            params.add(PersonaStatus.DELETED.getStatusId());
            params.add(id);

            getCRInstance().executeCommand(deleteSQL, params);
        }
    }

    private static class PersonaQueryCallback implements CentralRepositoryDbQueryCallback {

        private final Collection<Persona> personaList = new ArrayList<>();

        @Override
        public void process(ResultSet rs) throws SQLException {

            while (rs.next()) {
                CentralRepoExaminer examiner = new CentralRepoExaminer(
                        rs.getInt("examiner_id"),
                        rs.getString("login_name"));

                PersonaStatus status = PersonaStatus.fromId(rs.getInt("status_id"));
                Persona persona = new Persona(
                        rs.getInt("id"),
                        rs.getString("uuid"),
                        rs.getString("name"),
                        rs.getString("comment"),
                        Long.parseLong(rs.getString("created_date")),
                        Long.parseLong(rs.getString("modified_date")),
                        status,
                        examiner
                );

                personaList.add(persona);
            }
        }

        Collection<Persona> getPersonas() {
            return Collections.unmodifiableCollection(personaList);
        }
    };

    // Partial query string to select from personas table, 
    // just supply the where clause.
    private static final String PERSONA_QUERY
            = "SELECT p.id, p.uuid, p.name, p.comment, p.created_date, p.modified_date, p.status_id, p.examiner_id, e.login_name, e.display_name "
            + "FROM personas as p "
            + "INNER JOIN examiners as e ON e.id = p.examiner_id ";

    private static Persona getPersonaByUUID(String uuid) throws CentralRepoException {

        String queryClause
                = PERSONA_QUERY
                + "WHERE p.uuid = ?";

        List<Object> params = new ArrayList<>();
        params.add(uuid);

        PersonaQueryCallback queryCallback = new PersonaQueryCallback();
        getCRInstance().executeQuery(queryClause, params, queryCallback);

        Collection<Persona> personas = queryCallback.getPersonas();

        return personas.isEmpty() ? null : personas.iterator().next();
    }

    public static Collection<Persona> getPersonaByName(String partialName) throws CentralRepoException {

        String queryClause = PERSONA_QUERY
                + "WHERE p.status_id != ? "
                + " AND LOWER(p.name) LIKE LOWER(?) ESCAPE '!'";

        List<Object> params = new ArrayList<>();
        params.add(PersonaStatus.DELETED.getStatusId());
        params.add("%" + getLikeEscaped(partialName) + "%"); // partial substring search

        PersonaQueryCallback queryCallback = new PersonaQueryCallback();
        getCRInstance().executeQuery(queryClause, params, queryCallback);

        return queryCallback.getPersonas();
    }

    private static String getLikeEscaped(String initial) {
        if (initial == null) {
            return null;
        }

        return initial
                .replace("!", "!!")
                .replace("%", "!%")
                .replace("_", "!_");
    }

    public static Collection<Persona> getPersonaByAccountIdentifierLike(String partialName) throws CentralRepoException {
        String queryClause = "SELECT p.id, p.uuid, p.name, p.comment, p.created_date, p.modified_date, p.status_id, p.examiner_id, e.login_name\n"
                + "FROM personas p\n"
                + "LEFT JOIN examiners e ON e.id = p.examiner_id\n"
                + "WHERE p.status_id <> ?\n"
                + "AND p.id IN (\n"
                + "     SELECT pa.persona_id\n"
                + "     FROM persona_accounts pa\n"
                + "     INNER JOIN accounts a ON a.id = pa.account_id\n"
                + "     WHERE LOWER(a.account_unique_identifier) LIKE LOWER(?) ESCAPE '!'\n"
                + ")";

        PersonaQueryCallback queryCallback = new PersonaQueryCallback();

        List<Object> params = new ArrayList<>();
        params.add(PersonaStatus.DELETED.getStatusId());
        params.add("%" + getLikeEscaped(partialName) + "%"); // partial substring search

        getCRInstance().executeQuery(queryClause, params, queryCallback);
        return queryCallback.getPersonas();
    }

    public PersonaAlias addAlias(String alias, String justification, Persona.Confidence confidence) throws CentralRepoException {
        return PersonaAlias.addPersonaAlias(this, alias, justification, confidence);
    }

    public void removeAlias(PersonaAlias alias) throws CentralRepoException {
        PersonaAlias.removePersonaAlias(alias);
    }

    public void modifyAlias(PersonaAlias key, Confidence confidence, String justification) throws CentralRepoException {
        PersonaAlias.modifyPersonaAlias(key, confidence, justification);
    }

    public Collection<PersonaAlias> getAliases() throws CentralRepoException {
        return PersonaAlias.getPersonaAliases(this.getId());
    }

    public PersonaMetadata addMetadata(String name, String value, String justification, Persona.Confidence confidence) throws CentralRepoException {
        return PersonaMetadata.addPersonaMetadata(this.getId(), name, value, justification, confidence);
    }

    public void removeMetadata(PersonaMetadata metadata) throws CentralRepoException {
        PersonaMetadata.removePersonaMetadata(metadata);
    }

    public void modifyMetadata(PersonaMetadata key, Confidence confidence, String justification) throws CentralRepoException {
        PersonaMetadata.modifyPersonaMetadata(key, confidence, justification);
    }

    public Collection<PersonaMetadata> getMetadata() throws CentralRepoException {
        return PersonaMetadata.getPersonaMetadata(this.getId());
    }

    public Collection<PersonaAccount> getPersonaAccounts() throws CentralRepoException {
        return PersonaAccount.getPersonaAccountsForPersona(this.getId());
    }

    private static class CaseForAccountInstanceQueryCallback implements CentralRepositoryDbQueryCallback {

        Collection<CorrelationCase> correlationCases = new ArrayList<>();

        @Override
        public void process(ResultSet resultSet) throws CentralRepoException, SQLException {

            while (resultSet.next()) {
                // get Case for case_id
                CorrelationCase correlationCase = getCRInstance().getCaseById(resultSet.getInt("case_id"));
                correlationCases.add(correlationCase);
            }
        }

        Collection<CorrelationCase> getCases() {
            return Collections.unmodifiableCollection(correlationCases);
        }
    };

    public Collection<CorrelationCase> getCases() throws CentralRepoException {

        Collection<CorrelationCase> casesForPersona = new ArrayList<>();

        // get all accounts for this persona
        Collection<CentralRepoAccount> accounts = PersonaAccount.getAccountsForPersona(this.getId());
        for (CentralRepoAccount account : accounts) {
            int corrTypeId = account.getAccountType().getCorrelationTypeId();
            CorrelationAttributeInstance.Type correlationType = getCRInstance().getCorrelationTypeById(corrTypeId);

            String tableName = CentralRepoDbUtil.correlationTypeToInstanceTableName(correlationType);
            String querySql = "SELECT DISTINCT case_id FROM " + tableName
                    + " WHERE account_id = ?"; // param 1

            List<Object> params = new ArrayList<>();
            params.add(account.getId());

            CaseForAccountInstanceQueryCallback queryCallback = new CaseForAccountInstanceQueryCallback();
            getCRInstance().executeQuery(querySql, params, queryCallback);

            // Add any cases that aren't already on the list.
            for (CorrelationCase corrCase : queryCallback.getCases()) {
                if (!casesForPersona.stream().anyMatch(p -> p.getCaseUUID().equalsIgnoreCase(corrCase.getCaseUUID()))) {
                    casesForPersona.add(corrCase);
                }
            }
        }

        return casesForPersona;
    }

    private static class DatasourceForAccountInstanceQueryCallback implements CentralRepositoryDbQueryCallback {

        Collection<CorrelationDataSource> correlationDataSources = new ArrayList<>();

        @Override
        public void process(ResultSet resultSet) throws CentralRepoException, SQLException {

            while (resultSet.next()) {
                // get Case for case_id

                CorrelationCase correlationCase = getCRInstance().getCaseById(resultSet.getInt("case_id"));
                CorrelationDataSource correlationDatasource = getCRInstance().getDataSourceById(correlationCase, resultSet.getInt("data_source_id"));

                // Add data source to list if not already on it.
                if (!correlationDataSources.stream().anyMatch(p -> Objects.equals(p.getDataSourceObjectID(), correlationDatasource.getDataSourceObjectID()))) {
                    correlationDataSources.add(correlationDatasource);
                }
            }
        }

        Collection<CorrelationDataSource> getDataSources() {
            return Collections.unmodifiableCollection(correlationDataSources);
        }
    };

    public Collection<CorrelationDataSource> getDataSources() throws CentralRepoException {
        Collection<CorrelationDataSource> correlationDataSources = new ArrayList<>();

        Collection<CentralRepoAccount> accounts = PersonaAccount.getAccountsForPersona(this.getId());
        for (CentralRepoAccount account : accounts) {
            int corrTypeId = account.getAccountType().getCorrelationTypeId();
            CorrelationAttributeInstance.Type correlationType = getCRInstance().getCorrelationTypeById(corrTypeId);

            String tableName = CentralRepoDbUtil.correlationTypeToInstanceTableName(correlationType);
            String querySql = "SELECT case_id, data_source_id FROM " + tableName
                    + " WHERE account_id = ?";  // param 1

            List<Object> params = new ArrayList<>();
            params.add(account.getId());

            DatasourceForAccountInstanceQueryCallback queryCallback = new DatasourceForAccountInstanceQueryCallback();
            getCRInstance().executeQuery(querySql, params, queryCallback);

            // Add any data sources that aren't already on the list.
            for (CorrelationDataSource correlationDatasource : queryCallback.getDataSources()) {
                if (!correlationDataSources.stream().anyMatch(p -> Objects.equals(p.getDataSourceObjectID(), correlationDatasource.getDataSourceObjectID()))) {
                    correlationDataSources.add(correlationDatasource);
                }
            }
        }

        return correlationDataSources;
    }

    private static class PersonaFromAccountInstanceQueryCallback implements CentralRepositoryDbQueryCallback {

        Collection<Persona> personasList = new ArrayList<>();

        @Override
        public void process(ResultSet resultSet) throws CentralRepoException, SQLException {

            while (resultSet.next()) {

                // examiner that created the persona
                CentralRepoExaminer personaExaminer = new CentralRepoExaminer(
                        resultSet.getInt("persona_examiner_id"),
                        resultSet.getString("persona_examiner_login_name"));

                // create persona
                PersonaStatus status = PersonaStatus.fromId(resultSet.getInt("status_id"));
                Persona persona = new Persona(
                        resultSet.getInt("persona_id"),
                        resultSet.getString("uuid"),
                        resultSet.getString("name"),
                        resultSet.getString("comment"),
                        Long.parseLong(resultSet.getString("created_date")),
                        Long.parseLong(resultSet.getString("modified_date")),
                        status,
                        personaExaminer
                );

                personasList.add(persona);
            }
        }

        Collection<Persona> getPersonasList() {
            return Collections.unmodifiableCollection(personasList);
        }
    };

    private static String getPersonaFromInstanceTableQueryTemplate(CentralRepoAccount.CentralRepoAccountType crAccountType) throws CentralRepoException {

        int corrTypeId = crAccountType.getCorrelationTypeId();
        CorrelationAttributeInstance.Type correlationType = getCRInstance().getCorrelationTypeById(corrTypeId);

        String instanceTableName = CentralRepoDbUtil.correlationTypeToInstanceTableName(correlationType);
        return "SELECT " + instanceTableName + ".account_id, case_id, data_source_id, "
                + " personas.id as persona_id, personas.uuid, personas.name, personas.comment, personas.created_date, personas.modified_date, personas.status_id, "
                + " personas.examiner_id as persona_examiner_id, persona_examiner.login_name as persona_examiner_login_name, persona_examiner.display_name as persona_examiner_display_name "
                + " FROM " + instanceTableName
                + " JOIN persona_accounts as pa on pa.account_id = " + instanceTableName + ".account_id"
                + " JOIN personas as personas on personas.id = pa.persona_id"
                + " JOIN examiners as persona_examiner ON persona_examiner.id = personas.examiner_id ";

    }

    public static Collection<Persona> getPersonasForCase(CorrelationCase correlationCase) throws CentralRepoException {
        Collection<Persona> personaList = new ArrayList<>();

        Collection<CentralRepoAccount.CentralRepoAccountType> accountTypes = getCRInstance().getAllAccountTypes();
        for (CentralRepoAccount.CentralRepoAccountType crAccountType : accountTypes) {

            String querySql = getPersonaFromInstanceTableQueryTemplate(crAccountType)
                    + " WHERE case_id = ?" // param 1
                    + " AND personas.status_id != ?"; // param 2

            List<Object> params = new ArrayList<>();
            params.add(correlationCase.getID());
            params.add(Persona.PersonaStatus.DELETED.getStatusId());

            PersonaFromAccountInstanceQueryCallback queryCallback = new PersonaFromAccountInstanceQueryCallback();
            getCRInstance().executeQuery(querySql, params, queryCallback);

            // Add persona that aren't already on the list.
            for (Persona persona : queryCallback.getPersonasList()) {
                if (!personaList.stream().anyMatch(p -> Objects.equals(p.getUuidStr(), persona.getUuidStr()))) {
                    personaList.add(persona);
                }
            }

        }
        return personaList;
    }

    public static Collection<Persona> getPersonasForDataSource(CorrelationDataSource dataSource) throws CentralRepoException {
        Collection<Persona> personaList = new ArrayList<>();

        Collection<CentralRepoAccount.CentralRepoAccountType> accountTypes = getCRInstance().getAllAccountTypes();
        for (CentralRepoAccount.CentralRepoAccountType crAccountType : accountTypes) {

            String querySql = getPersonaFromInstanceTableQueryTemplate(crAccountType)
                    + " WHERE data_source_id = ?"
                    + " AND personas.status_id != ?";

            List<Object> params = new ArrayList<>();
            params.add(dataSource.getID());
            params.add(Persona.PersonaStatus.DELETED.getStatusId());

            PersonaFromAccountInstanceQueryCallback queryCallback = new PersonaFromAccountInstanceQueryCallback();
            getCRInstance().executeQuery(querySql, params, queryCallback);

            // Add persona that aren't already on the list.
            for (Persona persona : queryCallback.getPersonasList()) {
                if (!personaList.stream().anyMatch(p -> Objects.equals(p.getUuidStr(), persona.getUuidStr()))) {
                    personaList.add(persona);
                }
            }

        }
        return personaList;
    }

    private static CentralRepository getCRInstance() throws CentralRepoException {
        CentralRepository instance = CentralRepository.getInstance();

        if (instance == null) {
            throw new CentralRepoException("Failed to get instance of CentralRespository, CR was null");
        }

        return instance;
    }
}