After being gone out of the country for nearly 6 weeks, I finally have some time to continue this tutorial.
In Tutorial II, we finished by building a basic EnScript that recursed all the evidence and printed the name of every object to the console. In this tutorial we will take it one step further and begin to make decisions based on certain criteria. In Tutorial II we finished with the following code:
The next step is to use conditional control structures to select only certain files based on certain criteria.
One the foundational conditional statements is a "IF" statement. An example of an IF statement is the following:
if (entry.Name() == "system"){
}
As the EnScript recurses the evidence, it will evaluate each object in the evidence to see if the name field is equal to "system" by answering the questrion of is it "ture" or is it "false". If it is "true", then any code in the curly braces will execute. It is important to note that this type of evaluation is case-sensitive and must be exact, so "System" or "System.dat" evaluate to be false with a file named "system" and the code in the curly braces would not execute.
In the above code, we have inserted the "IF" statement, but notice there are no curly braces as shown above. There are two ways to do control statements, the first is to use an opening curly brace and then a closing curly brace, putting any code you want to execute if the evaluation is true, inside the braces.
The second way is to not use any curly braces and then if the conditional statement evaluates true, then the very next line will be executed. If it evaluates to false, then it will skip the very next line. So in the example above if "if (entry.Name() == "system") is true, then the next line "Console.WriteLine" will execute. If it is false, then that line will be skipped and the script will effectively end, but if there were additional lines of code after the Console.WriteLine command, then they would execute, but in this case, there are not, so the script ends.
EnCase provides a few built-in functions to help make matching text a little easier. The first one I will discuss is the Contains() function. The Contains() function is a built-in function that will look inside a test string for a fragment and then return true id that fragment is inside the initial string. For example:
if (entry.Name().Contains("sys")){
// code goes here
}
In this example, as the EnScript recurses each object in the evidence it will evaluate the name field to see if it "contains" the letters "sys". If it does, then it evaluates true and the code inside the curly braces would execute. The Contains() function is not case-sensitive and it does not matter where the string fragment is located inside the initial string. The file name "system.dat" would evaluate true, as would the file named "mmsystem.dll" since they both have "sys" inside them somewhere. To learn more about internal functions such as Contains(), you can select the EnScript Types from the "View" menu. The Contains() function is a member of the String Class. If you look in the String Class, you will see the Contains() function and a brief syntactical explanation of its use.
If you need to evaluate based on case, then you cant use Contains(), but you could use the Compare() function. The Compare () function takes two inputs, the string you want to evaluate and then a Boolean value to indicate whether you want to evaluate on case sensitivity. For example:
if (entry.Name().Compare("system", true) == 0) {
// code goes here
}
The Compare() function returns a non zero value for any text which is lexically less than or greater than the test you are looking for. If the text is exactly the same, the Compare() function returns a zero (I know, it seems reversed since a zero traditionally means false in Boolean). This is why there is a "==0" at the end of the statement. This statement would evaluate true only if the file name was exactly "system", not "System" or "system.dat".
Once you have used an control statement such as "IF", you probably want to do something with that file, like read text from it or bookmark it. In this tutorial I will introduce the method to bookmark a specific file based on some type of criteria, such as the examples above. In future tutorials, I will detail how to open and read data from a file (file I/O).
To bookmark a object, you should first create a folder to put your bookmarks in. You could just bookmark your file in the root of the bookmark tree, but that would be messy and disorganized. To create a Bookmark folder to later place your bookmarks into, you use the following statements:
BookmarkFolderClass folder;
folder = new BookmarkFolderClass(c.BookmarkRoot(), "My Bookmark Folder");
The first line creates a variable named "folder" of the BookmarkFolder Class type. Then, the second line instantiates (creates) the object named "folder" in the root of the bookmark tree, naming it "My BookmarkFolder".
The next step is to then bookmark any files or folders that you want with the following command:
folder.AddBookmark(entry, 0, entry.LogicalSize(), entry.Name(), BookmarkClass::SHOWREPORT, BookmarkClass::LOWASCII);
I will break this down into segments. The first segment is "folder.AddBookmark". Above, you created a reference to a BookmarkClass object named "folder". To add bookmarks into that folder, you use the function AddBookmark(). The first segment says "add a bookmark into the "folder" object.);
The second segment are the inputs that the function expects to tell EnCase WHAT to bookmark, WHERE to bookmark and how to name the bookmark, as well as how to display it in the bookmark tab.
The first input (entry) is the entryclass object that you want to bookmark.
The second input is where do you want to start the bookmark from, in this example, from the beginning of the file (zero).
The third is the ending bookmark offset. In this example, to the end of the logical file.
The fourth input is the name of the bookmark as you want it to appear in the bookmark tab, in this example, the name of the file/folder object
The fifth input is the options, such as show in the report, show as a picture, etc. In this example, it will be shown in the report view of the bookmarks
The sixth input is the viewtype. This tell EnCase how to display the data you have bookmarked. Should EnCase show it in hex, Ascii, a timestamp or HTML page. In this example display low ascii characters (<128). Our finalized code using the examples explained above is:
This EnScript will recurse all evidence and look at each object for a file name or folder that is exactly "system". When found it will then bookmark that file/folder from the very beginning of the file to the end of the logical file. After running this EnScript, you should have a bookmark folder named "My BookmarkFolder" in the root of the bookmark tab and any files that matched this criteria, would be bookmarked in that folder.