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

#include <TskImgDB.h>

Inheritance diagram for TskImgDB:

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 SectorRuns *	getFileSectors (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 SectorRuns *	getFreeSectors () 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 UnallocRun *	getUnallocRun (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

enum TskImgDB::HASH_TYPE

Hash types supported by framework.

Enumerator
MD5	128-bit MD5
SHA1	160-bit SHA1
SHA2_256	256-bit SHA2
SHA2_512	512-bit SHA2

enum TskImgDB::KNOWN_STATUS

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.

enum TskImgDB::VALUE_TYPE

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_volID	Volume ID that the data was extracted from.
unallocImgID	ID of the unallocated image that the sectors were copied into.
unallocImgStart	Sector offset of where in the unallocated image that t he run starts.
length	Number of sectors that are in the run.
origImgStart	Sector 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

	fileSystemID	File system ID of the file system the file belongs to
	fileSystemFile	TSK_FS_FILE object for the file
	fileName	File name
	fileSystemAttrType	File system attribute type (see TSK_FS_ATTR_TYPE_ENUM)
	fileSystemAttrID	File system attribute ID, used to index attributes for files with multiple attributes
[out]	fileID	File ID assigned to the file by the image database
	filePath	Path 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

imgPath The 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_file	file to find parent obj id for
fsObjId	fs 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

fileId	ID of file to lookup
fileRecord	Location 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

fileId id 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_id	ID of the unallocated image that you want data about
a_file_offset	Sector 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

hashType The 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

hashType The 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

fsObjId	fs id of the directory
fs_file	file object for the directory
objId	object 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_id	File to update.
a_status	Status 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_id	File to update.
a_status	Status flag to update to.

Returns: 1 on error.

Implemented in TskImgDBPostgreSQL, and TskImgDBSqlite.

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

framework/tsk/framework/services/TskImgDB.h
framework/tsk/framework/services/TskImgDB.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation