Creating and Removing Repositories
The methods for creating and removing production InTrust repositories (Add and Remove) are available in the IInTrustRepositoryCollection2 interface, which provides access to all repositories in a particular InTrust organization.
|
|
Caution: For these operations to succeed, the account you are using must be an InTrust organization administrator. To configure this privilege for the account, do one of the following:
|
Calling the Add method of IInTrustRepositoryCollection2 is not enough to create a repository. After you have made the call and obtained the IInTrustRepository3 interface, you need to complete the configuration of its options and call its Commit method. This will complete the creation of the repository.
For details about obtaining a collection of repositories, see Connecting to a Repository.
Instead of a production repository (which is registered with InTrust, managed by an InTrust server and has an entry in the InTrust configuration), you may want to create an idle repository (which has only the raw repository file structure). For that, use the IIdleRepositoryFactory interface, which constructs IIdleRepository interfaces.
Working with Repository Properties
Repositories have very flexible configuration, where some properties are predefined and others can be custom-defined. Access to repository configuration is provided through the IInTrustRepository3 interface, which has getter and setter methods for supported property groupings. The following groupings are available at this time:
- Forwarding properties
These properties are used by the event forwarding engine in InTrust (see Integration into SIEM Solutions Through Event Forwarding). For details about these properties, see IForwardingSettings. - Indexing properties
These properties are the configuration of the repository indexing engine in InTrust (see Repository Indexing for Advanced Search Capabilities). For details about these properties, see IIndexingSettings. - Custom attributes
These are arbitrary properties that you can set as necessary for your own purposes. For details, see Using Custom Attributes.
Using Custom Attributes
You can associate custom attributes with InTrust repositories. They are available through the CustomAttributes methods of an IInTrustRepository3 interface. They use the IProperty interface and are accessed collectively through IPropertyCollection interfaces.
There are no custom attribute guidelines; what custom attributes you add and how you use them is up to you. However, note that the following limits are set for the generic IProperty interface used by custom attributes:
- Name: 64 characters
- If you set a string of the BSTR type for the value: 1024 characters
It is also recommended that you keep the number of custom attributes low: tens rather than hundreds.
For details about the generic property interfaces used for custom attributes, see IProperty and IPropertyCollection.
Example (C#)
/* Connect to repository */
IInTrustEnvironment2 env = new InTrustEnvironment();
IInTrustServer server = env.ConnectToServerWithCredentials("8.8.8.8", @"domain\user_name", "password");
IInTrustOrganization org = server.Organization as IInTrustOrganization3;
IInTrustRepository3 rep = org.Repositories2.Item("Default InTrust Audit Repository");
/* Get collection of custom attributes */
IPropertyCollection props = rep.CustomAttributes;
/* Set custom attributes */
props.Set("NumberAttr", 12);
props.Set("StringAttr", "Initial status");
rep.Commit();
/* Get attribute by name */
IProperty stringAttr = props.Item("StringAttr");
/* Get value */
System.Console.WriteLine("String attribute value is {0}", stringAttr.PropertyValue);
/* Set new value */
stringAttr.PropertyValue = "Updated status";
rep.Commit();
/* Enumerate all attributes */
foreach (IProperty prop in props)
{
System.Console.WriteLine("Attibute : {0}, Value : {1}", prop.PropertyName, prop.PropertyValue);
}
/* Delete attribute */
props.Remove("NumberAttr");
(props as IADCCommitable).Commit(); /* Commit only the custom properties without the other repository fields */
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 IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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");
IInTrustOrganization3 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} |