diff --git a/bindings/java/doxygen/os_accounts.dox b/bindings/java/doxygen/os_accounts.dox index dd15fc6026dc94537411f00306047f2a901d6f17..7e260e4db62f8c30292489a8108b6632bfe5e6c2 100644 --- a/bindings/java/doxygen/os_accounts.dox +++ b/bindings/java/doxygen/os_accounts.dox @@ -46,6 +46,16 @@ OS accounts also have other properties, such as full name, creation date, etc., OS accounts are managed by org.sleuthkit.datamodel.OsAccountManager. +\subsection os_acct_acct_inst OS Account Instances + +An OS Account can exist on multiple systems for several reasons, including: +- It's a domain account and the user logged into several systems +- It's a local account, but there was a reference to the account in an event log or registry setting. + +Therefore, the database stories each instance the account was seen. An account instance shows that there was a reference to the account on a given host. The instance types are defined in org.sleuthkit.datamodel.OsAccountInstance.OsAccountInstanceType. + +When writing modules, you should record each instance that you see the account. + \subsection os_acct_acct_os Supported Operating Systems At this point, APIs exist for only Windows accounts, such as: @@ -54,35 +64,35 @@ At this point, APIs exist for only Windows accounts, such as: The underlying database schema supports other operating systems, but the utility APIs do not exist to populate them other than with Windows SIDs. These methods may be added in the future. -\section os_account_storing Storing Original Account Data +\section os_account_storing Storing Original Account Data in Other Tables -We recommend that the OS account addresses or names that were parsed from the data source be saved alongside any references to OsAccount objects. For example, the case database stores the UID or SID that was stored in a file system for a file in addition to the reference to the OsAccount object that is associated with that address. This helps to ensure the original data is preserved in case an Os account can't be created, gets deleted, or is incorrectly merged. +We recommend that the OS account addresses or names that were parsed from the data source be saved alongside any references to OsAccount objects when making new tables. For example, the case database stores the UID or SID that was stored in a file system for a file in addition to the reference to the OsAccount object that is associated with that address. This helps to ensure the original data is preserved in case an Os account can't be created, gets deleted, or is incorrectly merged. \section os_acct_example Example Creation & Update Code -There are three unique elements to creating and updating OS accounts when adding data to the case database: +There are three unique things to keep in mind when creating or updating OS accounts: <ol> -<li>When creating and updating OS accounts in the case database, you need to avoid some pitfalls involving doing a lot of work in a transaction. Why? For single-user cases, if you have created a org.sleuthkit.datamodel.SleuthkitCase.CaseDbTransaction, you should never call another database access method unless it allows you to pass in the CaseDbTransaction you are using. Otherwise, the method that you call will attempt to create its own transaction and because you already have the underlying SQLite case database locked, the called method will block forever waiting for a lock it cannot obtain. For a multi-user case, you will run the risk of attempting to create OS accounts in the case database that would duplicate accounts created by another user on another machine. In this scenario, uniqueness constraints will cause your entire transaction to fail and everything you have done up to that point will be rolled back and will have to be redone. +<li><b>Transactions.</b> To avoid duplicates, OS Accounts are often created and merged outside of a transaction. With single-user cases, you can get into deadlocks when you mix transaction-based API calls and non-transaction API calls. -This means that if you want to use a CaseDbTransation to add a lot of files or artifacts associated with OS accounts, you'll need to: +This means that if you want to use a CaseDbTransation to add a lot of files or artifacts associated with OS accounts at once, you'll need to: <ol type="a"> <li>Pre-process the data to identify what OS accounts you need to create or look up <li>Look up or create the OS accounts in individual transactions <li>Start a new transaction and add the files or artifacts with the references to the OS accounts </ol> -<li>You need to check if you have more information than what is already stored (e.g., maybe the realm name was unknown). +<li><b>Updates.</b> When you come accross OS Account data, you may have more info then what already exists in the DB and you should therefore try to upate it. e.g maybe the realm name was unknown. You should call an "update" command just in case you have new data. -<li>You need to record that an OS account was referenced on a given data source because OS accounts are stored in parallel to data sources and are not children of them. +<li><b>Instances.</b> You need to record that an OS account was referenced on a given data source because OS accounts are stored in parallel to data sources and are not children of them. Some methods, such as 'addFile()', will automatically record the instance. </ol> Here are some examples. \subsection os_acct_ex_get Adding a File or Data Artifact -If you pass in an OsAccount to the various methods to add files and data artifacts, then the database will make the association and record the occurence. All you need to do is get the account. You can do that with org.sleuthkit.datamodel.OsAccountManager.getWindowsOsAccount(). Note that sometimes that call will fail if the SID associated with the file is for a group, for example, if the OS account has admin rights. +The various addFile() methods allow you to pass in an OsAccount and the database will make the association and record the occurence. All you need to do is get the account. You can do that with org.sleuthkit.datamodel.OsAccountManager.getWindowsOsAccount(). Note that sometimes that call will fail if the SID associated with the file is for a group, for example, if the OS account has admin rights. If you get an OsAccount, you can try to update it if you think you may have new information.