Getting Started with Repository Services API
To check that the functionality of repository services API is available, use the RepositoryRecordInserterExample.exe test application, which is installed with the InTrust SDK. Run this application from the command prompt as follows:
RepositoryRecordInserterTest.exe <InTrust_server_binding_string> <repository_name>
<InTrust_server_binding_string> can be the name of the InTrust server.
<repository_name> is either the name of the repository as it appears in the InTrust UI (InTrust Deployment Manager, Repository Viewer, InTrust Manager).
Example:
RepositoryRecordInserterExample.exe intrust01 "Default InTrust Audit Repository"
The example uses the “Default InTrust Audit Repository” name. A repository with this name is created during InTrust deployment, so unless it has been renamed, it is present in every InTrust environment.
Testing Repository Searching
If the test program runs successfully, you should see event data in the command prompt's standard output. Getting the data is actually the second stage of the program's operation. The first stage is writing that data.
Testing Event Writing
The program writes a number of events to the specified repository. To examine them in detail, connect to the repository with Repository Viewer. For all these events, “MyComputer” is used as the Source Computer parameter value and “computer” as the Computer parameter value.
Next Steps
The sources of RepositoryRecordInserterExample.exe should have been provided to you together with the InTrust SDK installer. Open the project in Visual Studio, study it, try to customize it and test the effects of your changes.
Log Knowledge Base API
The log knowledge base contains settings for transforming data from original log formats to the repository format. The API does not work with predefined log definitions, which are completely out of its scope; it is designed only for user-defined logs.
To work with the log knowledge base, use the following interfaces:
To begin working with the log knowledge base, get a collection of known organizations (Organizations method of the IInTrustEnvironment interface) and pick the necessary one. This involves working with the IInTrustOrganizationCollection interface. Organizations are discovered by an Active Directory query.
The IInTrustOrganization that you get has the Eventory method, which provides access to the organization-wide log knowledge base.
For details about the format of rules for matching log events and mapping fields, see Log Transformation Rule Format.
|
|
Caution: If you modify the knowledge base for a specific log, this will invalidate all existing index data for that log in all repositories that contain the log. Indexed searches will no longer find this log’s events gathered prior to the modification. Data gathered after the modification will be indexed correctly and be searchable. If the unavailability of old data is not a problem for you, you don't have to do anything. Otherwise, you will need to recreate valid indexes for all repositories that contain the log. However, it is not feasible to recreate an index for a large production repository without taking it offline for a long time. If you need to experiment with log knowledge base editing, use a dedicated test organization and small repositories, which can be reindexed quickly. For details about repository reindexing, see Recreating the Index. |
Example
static void GetFullEventory()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
string eventory = ev.Eventory;
Console.WriteLine("Full eventory : " + eventory);
}
static void AddNewLog()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection logs = ev.Logs;
IInTrustEventoryItem log = logs.Add("NewLog",
@"<FieldInfo>
<Fields>
<Field FieldName = ""New_field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
</Fields>
<EventRules>
<Event EventID = ""701"">
<Field Name = ""Who"" Index = ""11""></Field>
<Field Name = ""What"" Index = ""12""></Field>
<Field Name = ""Object_Type"" Index = ""13""></Field>
<Field Name = ""Object_Name"" Index = ""14""></Field>
</Event>
</EventRules>
</FieldInfo>");
}
static void GetLogAndChangeRule()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection logs = ev.Logs;
IInTrustEventoryItem log = logs.Item("NewLog");
log.Rules = @"<FieldInfo>
<Fields>
<Field FieldName = ""New_field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
</Fields>
<EventRules>
<Event EventID = ""701"">
<Field Name = ""Who"" Index = ""11""></Field>
</Event>
</FieldInfo>";
}
static void EnumLogs()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection logs = ev.Logs;
foreach (IInTrustEventoryItem cur_log in logs)
{
string log_name = cur_log.Name;
string log_rule = cur_log.Rules;
Console.WriteLine("Log name : " + log_name);
Console.WriteLine("Log rule : " + log_rule);
}
}
static void RemoveLog()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection logs = ev.Logs;
logs.Remove("NewLog");
}
static void AddNewDataSource()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection dataSources = ev.DataSources;
IInTrustEventoryItem dataSource = dataSources.Add("{10000000-0000-0000-0000-000000000001}",@"<FieldInfo>
<Fields>
<Field FieldName = ""New_field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
</Fields>
<EventRules>
<Event EventID = ""701"">
<Field Name = ""Who"" Index = ""11""></Field>
<Field Name = ""What"" Index = ""12""></Field>
<Field Name = ""Object_Type"" Index = ""13""></Field>
<Field Name = ""Object_Name"" Index = ""14""></Field>
</Event>
</EventRules>
</FieldInfo>");
}
static void GetDataSourceAndChangeRule()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection dataSources = ev.DataSources;
IInTrustEventoryItem dataSource = dataSources.Item("{10000000-0000-0000-0000-000000000001}");
dataSource.Rules = @"<FieldInfo>
<Fields>
<Field FieldName = ""New_field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
</Fields>
<EventRules>
<Event EventID = ""701"">
<Field Name = ""Who"" Index = ""11""></Field>
</Event>
</FieldInfo>";
}
static void EnumDataSources()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection dataSources = ev.DataSources;
foreach (IInTrustEventoryItem curDataSource in dataSources)
{
string ds_name = curDataSource.Name;
string ds_rule = curDataSource.Rules;
Console.WriteLine("Data source name : " + ds_name);
Console.WriteLine("Data source rule : " + ds_rule);
}
}
static void RemoveDataSources()
{
IInTrustEnvironment env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServer("8.8.8.8");
IInTrustOrganization org = server.Organization;
IInTrustEventory ev = org.Eventory;
IInTrustEventoryItemCollection dataSources = ev.DataSources;
dataSources.Remove("{10000000-0000-0000-0000-000000000001}");
}
|
NOTE: In the functions that handle data sources, the data source name must be in GUID format; for example: {10000000-0000-0000-0000-000000000001} |
Log Transformation Rule Format
Log transformation rules are defined as XML. The structure of a rule is shown in the example below, which contains all of the tags and parameters available.
<FieldInfo>
<Fields>
<Field FieldName = "TTF" DisplayName = "TTest Field" IsIndexed = "true"></Field>
<Field FieldName = "TTF2" DisplayName = "TTest Field 2" IsIndexed = "true"></Field>
</Fields>
<EventRules>
<Event EventID = "701">
<Field Name = "TTF" Index = "1"></Field>
<Field Name = "TTF2" Index = "3"></Field>
</Event>
</EventRules>
</FieldInfo>
Log events are matched by Event ID, and the Field tags specify how the original event fields are mapped to repository record fields. The Index parameter specifies the index of the target insertion string.
The following is a variation of the example above:
<FieldInfo>
<Fields>
<Field FieldName = "TTF" DisplayName = "TTest Field" IsIndexed = "true"></Field>
<Field FieldName = "TTF2" DisplayName = "TTest Field 2" IsIndexed = "true"></Field>
</Fields>
<EventRules>
<Field Name = "TTF" Index = "1"></Field>
<Field Name = "TTF2" Index = "3"></Field>
</EventRules>
</FieldInfo>
In this second snippet, the rule applies to all event IDs in a log.
Interfaces
The following is a list of all interfaces available with the InTrust repository API:
| Interface | Details |
|---|---|
| IBulkEventWithReadExtensions | Results of a repository search as an array of event_with_read_extensions structures. |
| IBulkRecord | Records packed into a single batch as an array of record structures for writing to the repository. |
| IBulkRecord2 | Results of a repository search as an array of record2 structures. |
| ICookie | Acts as the owner of a repository search and can stop the search. |
| IEventToRecordFormatter | Transforms event records to a representation suitable for insertion into a repository by the PutRecords2 method of IRepositoryRecordInserter. |
| IIdleRepository | An idle repository has the correct structure on the file system, but is not registered with an InTrust organization. Currently, you can search in idle repositories using the repository API, but you cannot write to them. |
| IIdleRepositoryFactory | Creates an idle InTrust repository. |
| IIndexManager | Provides access to indexing-related operations. |
| IIndexManagerFactory | Creates an instance of IIndexManager for a production or idle repository. |
| IInTrustEnvironment | Entry point for access to InTrust organizations, servers and repositories. |
| IInTrustEventory | Provides access to the log knowledge base, which contains rules that govern the transformation of log entries into repository and event records. |
| IInTrustEventoryItem | Represents an entry in the log knowledge base. |
| IInTrustEventoryItemCollection | Provides a collection of IInTrustEventoryItem interfaces. |
| IInTrustOrganization | Provides access to an InTrust organization. |
| IInTrustOrganizationCollection | Provides a collection of all available InTrust organizations. |
| IInTrustRepository | Provides the searching and writing capabilities of a repository. |
| IInTrustRepositoryCollection | Provides a collection of all repositories available in the InTrust organization. |
| IInTrustRepositorySearcher | Provides repository search capabilities. |
| IInTrustServer | Provides access to an InTrust server. |
| IInTrustServerCollection | Provides a collection of all InTrust servers in the InTrust organization. |
| IMultiRepositorySearcher | A container for search objects that lets you search in all of the specified repositories simultaneously. |
| IMultiRepositorySearcherFactory | Creates an instance of IMultiRepositorySearcher. |
| IObservable | Defines a provider for push-based notification. |
| IObserver | Provides a mechanism for receiving push-based notifications. You need to create your own implementation of this interface. |
| IProperty | Property attached to an InTrust repository. A property is a way to tag repositories for arbitrary purposes. |
| IPropertyCollection | Collection of properties associated with an InTrust repository. Access to the collections is gained through specialized methods of the IInTrustRepository interface (such as CustomAttributes and ForwardingProperties), which filter the available properties by purpose. |
| IRepositoryRecordInserter | Provides write access to the repository that it is associated with and manages one or more IRepositoryRecordInserterLight interfaces, which do the actual writing. |
| IRepositoryRecordInserterLight | Generates valid record structures from predefined and significant values and writes them to the repository. |