The Sleuth Kit Framework  4.1
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
TskImgDB Class Referenceabstract

Interface for class that implments database storage for an image. More...

#include <TskImgDB.h>

Inheritance diagram for TskImgDB:
TskImgDBPostgreSQL TskImgDBSqlite

Public Types

enum  FILE_STATUS {
  IMGDB_FILES_STATUS_CREATED = 0, IMGDB_FILES_STATUS_READY_FOR_ANALYSIS, IMGDB_FILES_STATUS_ANALYSIS_IN_PROGRESS, IMGDB_FILES_STATUS_ANALYSIS_COMPLETE,
  IMGDB_FILES_STATUS_ANALYSIS_FAILED, IMGDB_FILES_STATUS_ANALYSIS_SKIPPED
}
 File analysis statuses used by the framework.
 
enum  FILE_TYPES { IMGDB_FILES_TYPE_FS = 0, IMGDB_FILES_TYPE_CARVED, IMGDB_FILES_TYPE_DERIVED, IMGDB_FILES_TYPE_UNUSED }
 File type classifications used by the framework.
 
enum  HASH_TYPE { MD5 = 0, SHA1, SHA2_256, SHA2_512 }
 Hash types supported by framework. More...
 
enum  KNOWN_STATUS { IMGDB_FILES_KNOWN = 0, IMGDB_FILES_KNOWN_GOOD, IMGDB_FILES_KNOWN_BAD, IMGDB_FILES_UNKNOWN }
 Files have a 'known' status that is updated with the use of hash databases. More...
 
enum  UNALLOC_IMG_STATUS {
  IMGDB_UNALLOC_IMG_STATUS_CREATED = 0, IMGDB_UNALLOC_IMG_STATUS_SCHEDULE_OK, IMGDB_UNALLOC_IMG_STATUS_SCHEDULE_ERR, IMGDB_UNALLOC_IMG_STATUS_CARVED_OK,
  IMGDB_UNALLOC_IMG_STATUS_CARVED_ERR, IMGDB_UNALLOC_IMG_STATUS_CARVED_NOT_NEEDED
}
 Unallocated sectors file statuses used by the framework.
 
enum  VALUE_TYPE {
  BB_VALUE_TYPE_BYTE = 0, BB_VALUE_TYPE_STRING, BB_VALUE_TYPE_INT32, BB_VALUE_TYPE_INT64,
  BB_VALUE_TYPE_DOUBLE
}
 Data types that can be stored in blackboard. More...
 

Public Member Functions

virtual int addAllocUnallocMapInfo (int a_volID, int unallocImgID, uint64_t unallocImgStart, uint64_t length, uint64_t origImgStart)=0
 Add information about how the unallocated images were created so that we can later map where data was recovered from. More...
 
virtual int addCarvedFileInfo (int vol_id, const char *name, uint64_t size, uint64_t *runStarts, uint64_t *runLengths, int numRuns, uint64_t &fileId)=0
 
virtual int addDerivedFileInfo (const std::string &name, const uint64_t parentId, const bool isDirectory, const uint64_t size, const std::string &details, const int ctime, const int crtime, const int atime, const int mtime, uint64_t &fileId, std::string path)=0
 
virtual int addFsBlockInfo (int fsID, uint64_t a_mFileId, int count, uint64_t blk_addr, uint64_t len)=0
 
virtual int addFsFileInfo (int fileSystemID, const TSK_FS_FILE *fileSystemFile, const char *fileName, int fileSystemAttrType, int fileSystemAttrID, uint64_t &fileID, const char *filePath)=0
 Add data for a file system file to the image database. More...
 
virtual int addFsInfo (int volId, int fsId, const TSK_FS_INFO *fs_info)=0
 
virtual int addImageInfo (int type, int sectorSize)=0
 
virtual int addImageName (char const *imgPath)=0
 Add the path to the image to the image database. More...
 
virtual int addModule (const std::string &name, const std::string &description, int &moduleId)=0
 
virtual int addToolInfo (const char *name, const char *version)=0
 
virtual int addUnallocImg (int &unallocImgId)=0
 Used when a new unallocated image file is created for carving. More...
 
virtual int addUnusedSectors (int unallocImgId, std::vector< TskUnusedSectorsRecord > &unusedSectorsList)=0
 
virtual int addVolumeInfo (const TSK_VS_PART_INFO *vs_part)=0
 
virtual int begin ()=0
 
virtual int close ()=0
 Close the database. More...
 
virtual int commit ()=0
 
virtual bool dbExist () const =0
 
virtual int getAllUnallocImgStatus (std::vector< TskUnallocImgStatusRecord > &unallocImgStatusList) const =0
 
virtual std::vector< uint64_t > getCarvedFileIds () const =0
 
virtual std::string getCfileName (const uint64_t a_file_id) const =0
 
virtual int getFileCount (const std::string &condition) const =0
 
virtual uint64_t getFileId (int fsId, uint64_t fs_file_id) const =0
 
virtual int getFileIds (char *a_fileName, uint64_t *a_outBuffer, int a_buffSize) const =0
 
virtual std::vector< uint64_t > getFileIds (const std::string &condition) const =0
 
virtual std::vector< uint64_t > getFileIds () const =0
 
virtual int getFileInfoSummary (std::list< TskFileTypeRecord > &fileTypeInfoList) const =0
 
virtual int getFileInfoSummary (FILE_TYPES fileType, std::list< TskFileTypeRecord > &fileTypeInfoList) const =0
 
virtual std::string getFileName (uint64_t file_id) const =0
 
virtual int getFileRecord (const uint64_t fileId, TskFileRecord &fileRecord) const =0
 Queries the blackboard for raw information about a specific file. More...
 
virtual const std::vector
< TskFileRecord
getFileRecords (const std::string &condition) const =0
 
virtual SectorRunsgetFileSectors (uint64_t fileId) const =0
 
virtual int getFileUniqueIdentifiers (uint64_t a_fileId, uint64_t &a_fsOffset, uint64_t &a_fsFileId, int &a_attrType, int &a_attrId) const =0
 
virtual SectorRunsgetFreeSectors () const =0
 Returns a list of the sectors that are not used by files and that are in unpartitioned space. More...
 
virtual int getFsInfo (std::list< TskFsInfoRecord > &fsInfoList) const =0
 
virtual std::string getImageBaseName () const =0
 Gets the base name of the image, i.e., the file name of the first image path stored in the database. More...
 
virtual int getImageInfo (int &type, int &sectorSize) const =0
 
virtual std::vector< std::string > getImageNames () const =0
 
virtual std::vector< std::wstring > getImageNamesW () const =0
 Gets a list of image paths. More...
 
virtual KNOWN_STATUS getKnownStatus (const uint64_t fileId) const =0
 Return the known status of the file with the given id. More...
 
virtual int getMaxFileIdReadyForAnalysis (uint64_t a_lastFileId, uint64_t &maxFileId) const =0
 
virtual int getMinFileIdReadyForAnalysis (uint64_t &minFileId) const =0
 
virtual int getModuleErrors (std::vector< TskModuleStatus > &moduleStatusList) const =0
 
virtual int getModuleInfo (std::vector< TskModuleInfo > &moduleInfoList) const =0
 
virtual int getNumFiles () const =0
 
virtual int getNumVolumes () const =0
 
virtual int getSessionID () const =0
 
virtual
TskImgDB::UNALLOC_IMG_STATUS 
getUnallocImgStatus (int unallocImgId) const =0
 
virtual UnallocRungetUnallocRun (int a_unalloc_img_id, int a_file_offset) const =0
 Given an offset in an unallocated image that was created for carving, return information about where that data came from in the original image. More...
 
virtual std::map< uint64_t,
std::string > 
getUniqueCarvedFiles (HASH_TYPE hashType) const =0
 Returns the file ids and carved file names for a unique set of carved files. More...
 
virtual std::vector
< TskCarvedFileInfo
getUniqueCarvedFilesInfo (HASH_TYPE hashType) const =0
 Returns the file ids, content hashes and, carved file names for a unique set of carved files. More...
 
virtual std::vector< uint64_t > getUniqueFileIds (HASH_TYPE hashType) const =0
 
virtual int getUnusedSector (uint64_t fileId, TskUnusedSectorsRecord &unusedSectorsRecord) const =0
 
virtual int getVolumeInfo (std::list< TskVolumeInfoRecord > &volumeInfoList) const =0
 
virtual int initialize ()=0
 Opens the database and creates the needed tables. More...
 
virtual int open ()=0
 Opens an existing database. More...
 
virtual std::string quote (const std::string str) const =0
 
virtual int setHash (const uint64_t a_file_id, const TskImgDB::HASH_TYPE hashType, const std::string &hash) const =0
 
virtual int setModuleStatus (uint64_t file_id, int module_id, int status)=0
 
virtual int setUnallocImgStatus (int unallocImgId, TskImgDB::UNALLOC_IMG_STATUS status)=0
 
 TskImgDB ()
 Default constructor.
 
virtual int updateFileStatus (uint64_t a_file_id, FILE_STATUS a_status)=0
 update the status field in the database for a given file. More...
 
virtual int updateKnownStatus (uint64_t a_file_id, KNOWN_STATUS a_status)=0
 update the known status field in the database for a given file. More...
 
virtual ~TskImgDB ()
 Destructor.
 

Protected Member Functions

virtual void addArtifactType (int typeID, string artifactTypeName, string displayName)=0
 
virtual void addAttributeType (int typeID, string attributeTypeName, string displayName)=0
 
virtual void addBlackboardAttribute (TskBlackboardAttribute attr)=0
 
TskBlackboardArtifact createArtifact (uint64_t artifactID, uint64_t objID, int artifactTypeID)
 
TskBlackboardAttribute createAttribute (uint64_t artifactID, int attributeTypeID, uint64_t objectID, string moduleName, string context, TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE valueType, int valueInt, uint64_t valueLong, double valueDouble, string valueString, vector< unsigned char > valueBytes)
 
virtual TskBlackboardArtifact createBlackboardArtifact (uint64_t file_id, int artifactTypeID)=0
 
virtual vector< int > findAttributeTypes (int artifactTypeId)=0
 
int64_t findParObjId (const TSK_FS_FILE *fs_file, const int64_t &fsObjId)
 Find parent object id of TSK_FS_FILE. More...
 
virtual map< int,
TskArtifactNames
getAllArtifactTypes ()
 
virtual map< int,
TskAttributeNames
getAllAttributeTypes ()
 
virtual string getArtifactTypeDisplayName (int artifactTypeID)=0
 
virtual int getArtifactTypeID (string artifactTypeString)=0
 
virtual string getArtifactTypeName (int artifactTypeID)=0
 
virtual string getAttributeTypeDisplayName (int attributeTypeID)=0
 
virtual int getAttributeTypeID (string attributeTypeString)=0
 
virtual string getAttributeTypeName (int attributeTypeID)=0
 
virtual vector
< TskBlackboardArtifact
getMatchingArtifacts (string whereClause)=0
 
virtual vector
< TskBlackboardAttribute
getMatchingAttributes (string whereClause)=0
 
void storeParObjId (const int64_t &fsObjId, const TSK_FS_FILE *fs_file, const int64_t &objId)
 Store meta_addr to object id mapping of the directory in a local cache map. More...
 

Protected Attributes

map< int64_t, map< TSK_INUM_T,
map< uint32_t, int64_t > > > 
m_parentDirIdCache
 

Friends

class TskDBBlackboard
 

Detailed Description

Interface for class that implments database storage for an image.

The database will be used to store information about the data being analyzed. Can be registered with and retrieved from TskServices.

Member Enumeration Documentation

Hash types supported by framework.

Enumerator
MD5 

128-bit MD5

SHA1 

160-bit SHA1

SHA2_256 

256-bit SHA2

SHA2_512 

512-bit SHA2

Files have a 'known' status that is updated with the use of hash databases.

Enumerator
IMGDB_FILES_KNOWN 

'Known', but cannot differentiate between good or bad. NSRL, for example, identifies known, but does not assign a good or bad status.

IMGDB_FILES_KNOWN_GOOD 

Known to be good / safely ignorable.

IMGDB_FILES_KNOWN_BAD 

Known to be bad or notable.

IMGDB_FILES_UNKNOWN 

Unknown files. Perhaps because they haven't been analyzed yet or perhaps because they are user files that are not in a database. All files start off in this state.

Data types that can be stored in blackboard.

Enumerator
BB_VALUE_TYPE_BYTE 

Single byte.

BB_VALUE_TYPE_STRING 

String.

BB_VALUE_TYPE_INT32 

32-bit integer

BB_VALUE_TYPE_INT64 

64-bit integer

BB_VALUE_TYPE_DOUBLE 

double floating point

Member Function Documentation

virtual int TskImgDB::addAllocUnallocMapInfo ( int  a_volID,
int  unallocImgID,
uint64_t  unallocImgStart,
uint64_t  length,
uint64_t  origImgStart 
)
pure virtual

Add information about how the unallocated images were created so that we can later map where data was recovered from.

This is typically used by CarvePrep and the results are used by CarveExtract via getUnallocRun().

Parameters
a_volIDVolume ID that the data was extracted from.
unallocImgIDID of the unallocated image that the sectors were copied into.
unallocImgStartSector offset of where in the unallocated image that t he run starts.
lengthNumber of sectors that are in the run.
origImgStartSector offset in the original image (relative to start of image) where the run starts
Returns
1 on errror

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual int TskImgDB::addFsFileInfo ( int  fileSystemID,
const TSK_FS_FILE fileSystemFile,
const char *  fileName,
int  fileSystemAttrType,
int  fileSystemAttrID,
uint64_t &  fileID,
const char *  filePath 
)
pure virtual

Add data for a file system file to the image database.

Parameters
fileSystemIDFile system ID of the file system the file belongs to
fileSystemFileTSK_FS_FILE object for the file
fileNameFile name
fileSystemAttrTypeFile system attribute type (see TSK_FS_ATTR_TYPE_ENUM)
fileSystemAttrIDFile system attribute ID, used to index attributes for files with multiple attributes
[out]fileIDFile ID assigned to the file by the image database
filePathPath to the file in the image, file name omitted
Returns
0 on success or -1 on error.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual int TskImgDB::addImageName ( char const *  imgPath)
pure virtual

Add the path to the image to the image database.

Parameters
imgPathThe image path.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

Referenced by TskImageFileTsk::extractFiles().

virtual int TskImgDB::addUnallocImg ( int &  unallocImgId)
pure virtual

Used when a new unallocated image file is created for carving.

Parameters
unallocImgId[out] Stores the unique ID assigned to the image.
Returns
-1 on error, 0 on success.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual int TskImgDB::close ( )
pure virtual

Close the database.

Returns
0 on success and 1 on failure.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

int64_t TskImgDB::findParObjId ( const TSK_FS_FILE fs_file,
const int64_t &  fsObjId 
)
protected

Find parent object id of TSK_FS_FILE.

Use local cache map, if not found, fall back to SQL

Parameters
fs_filefile to find parent obj id for
fsObjIdfs id of this file
Returns
parent obj id ( > 0), -1 on error

References TSK_FS_FILE::name, TSK_FS_NAME::par_addr, and TSK_FS_NAME::par_seq.

Referenced by TskImgDBSqlite::addFsFileInfo(), and TskImgDBPostgreSQL::addFsFileInfo().

virtual int TskImgDB::getFileRecord ( const uint64_t  fileId,
TskFileRecord fileRecord 
) const
pure virtual

Queries the blackboard for raw information about a specific file.

Parameters
fileIdID of file to lookup
fileRecordLocation where data should be stored
Returns
-1 on error and 0 on success.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

Referenced by TskFile::getUniquePath(), and TskFile::initialize().

virtual SectorRuns* TskImgDB::getFreeSectors ( ) const
pure virtual

Returns a list of the sectors that are not used by files and that are in unpartitioned space.

Typically this is used by CarvePrep.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual std::string TskImgDB::getImageBaseName ( ) const
pure virtual

Gets the base name of the image, i.e., the file name of the first image path stored in the database.

Returns
The name of the image, possibly the empty string if no image paths have been stored.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual std::vector<std::wstring> TskImgDB::getImageNamesW ( ) const
pure virtual

Gets a list of image paths.

Returns
A vector of image paths as std::strings. There may be multiple paths for a split image or the list may be empty if no image paths have been stored.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual KNOWN_STATUS TskImgDB::getKnownStatus ( const uint64_t  fileId) const
pure virtual

Return the known status of the file with the given id.

Parameters
fileIdid of the file to get the status of
Returns
KNOWN_STATUS or -1 on error

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

Referenced by TskFile::getKnownStatus().

virtual UnallocRun* TskImgDB::getUnallocRun ( int  a_unalloc_img_id,
int  a_file_offset 
) const
pure virtual

Given an offset in an unallocated image that was created for carving, return information about where that data came from in the original image.

This is used to map where a carved file is located in the original image.

Parameters
a_unalloc_img_idID of the unallocated image that you want data about
a_file_offsetSector offset where file was found in the unallocated image
Returns
NULL on error or a run descriptor.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual std::map<uint64_t, std::string> TskImgDB::getUniqueCarvedFiles ( HASH_TYPE  hashType) const
pure virtual

Returns the file ids and carved file names for a unique set of carved files.

Uniqueness is based on the value of a particular hash type. Where duplicate hash values exist, the lowest file_id is chosen. NOTE: This function is deprecated and will be removed in the next major release, use the getUniqueCarvedFilesInfo() member function instead.

Parameters
hashTypeThe type of hash value to use when determining uniqueness.
Returns
A map of file ids to the corresponding carved file name.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual std::vector<TskCarvedFileInfo> TskImgDB::getUniqueCarvedFilesInfo ( HASH_TYPE  hashType) const
pure virtual

Returns the file ids, content hashes and, carved file names for a unique set of carved files.

Uniqueness is based on the value of a particular hash type. Where duplicate hash values exist, the lowest file_id is chosen.

Parameters
hashTypeThe type of hash value to use when determining uniqueness.
Returns
A map of file ids to the corresponding carved file name. Throws TskException.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual int TskImgDB::initialize ( )
pure virtual

Opens the database and creates the needed tables.

Returns
1 on error and 0 on success.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

virtual int TskImgDB::open ( )
pure virtual

Opens an existing database.

Use initialize() to create a new one.

Returns
1 on error and 0 on success.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

void TskImgDB::storeParObjId ( const int64_t &  fsObjId,
const TSK_FS_FILE fs_file,
const int64_t &  objId 
)
protected

Store meta_addr to object id mapping of the directory in a local cache map.

Parameters
fsObjIdfs id of the directory
fs_filefile object for the directory
objIdobject id of the directory from the objects table

References TSK_FS_NAME::meta_addr, TSK_FS_NAME::meta_seq, and TSK_FS_FILE::name.

Referenced by TskImgDBSqlite::addFsFileInfo(), and TskImgDBPostgreSQL::addFsFileInfo().

virtual int TskImgDB::updateFileStatus ( uint64_t  a_file_id,
FILE_STATUS  a_status 
)
pure virtual

update the status field in the database for a given file.

Parameters
a_file_idFile to update.
a_statusStatus flag to update to.
Returns
1 on error.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

Referenced by TskFileAnalysisPipeline::run(), and TskFile::setStatus().

virtual int TskImgDB::updateKnownStatus ( uint64_t  a_file_id,
KNOWN_STATUS  a_status 
)
pure virtual

update the known status field in the database for a given file.

Parameters
a_file_idFile to update.
a_statusStatus flag to update to.
Returns
1 on error.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.


The documentation for this class was generated from the following files:

Copyright © 2011-2013 Brian Carrier. (carrier -at- sleuthkit -dot- org)
This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.