12.1 Searching Events

Change Guardian provides an option to perform advanced search on events. With the necessary configuration, you can also search system events generated by Change Guardian and view the raw data for each event. By default, events are returned in a reverse chronological order.

Search results include all events generated by the Change Guardian system operations, by default. These events are tagged with the Sentinel tag. If you do not specify a query and click Search for the first time, the default search returns all events with severity 0 to 5. Otherwise, the search feature reuses the last specified search query.

You can run a search to view events indexed in traditional storage. You can also search for events in other Change Guardian servers that are distributed across different geographic locations.

To search for a value in a specific field, use the ID of the event name and the value. For example, to search for an authentication attempt to Change Guardian by user2, specify the following: evt:LoginUser AND sun:user2

You can use advanced feature to refine searches using the product name, severity, source IP, and the event type. You can combine multiple advanced search criteria by using operators. The advanced search criteria syntax is modeled on the search criteria for the Apache Lucene open source package.

To search events with the product name NMAS and severity five:

pn:NMAS AND sev:5
To search the initiator IP address 10.0.0.1 and a “Set Password” event:sip:10.0.0.01 AND evt:"Set Password"

NOTE:If time is not synchronized across your server, client, and event sources, you might get unexpected results from your search. This is especially a problem if searches are performed on time durations such as Custom, Last 1 hour, and Last 24 hours where display results are based on the time zone of the machine on which the search is performed.

Following sections provide information about the following:

12.1.1 Performing a Search

To search:

In the Reports and Searches panel, click New search.
You can perform a search by using any of the following:
- Search criteria: Specify the search criteria in the Search field.
- Build criteria: Build a new criteria using the build criteria user interface.
- Select and Append criteria: Click Select and Append criteria and select from the criteria listed, click Add > Search. You can select criteria from the list of criteria or filter the criteria based on recent criteria, tags, or filters.
  - Show only recent criteria: Select a search criterion from the recent search history. The search history displays a maximum of 15 search expressions. Select the criteria, click Show recent criteria, and then click Add.
  - Show only Filters: You can reuse existing filters to perform a new search. Click Show Filters that lists the existing filters. Select the filter on which you want to perform the search, and then click Add.
  - Show only Tags: You can search events that have a particular tag. Click Show Tags, that lists the tags in the system. Select the tags, and then click Add.
  You can combine multiple criteria, tags, or filters by using the And or Or condition.
(Optional) Select a time period for the search.
- The default is Last 1 hour.
- Custom allows you to select a start date and time and an end date and time for the query. The start date should be earlier than the end date, and the time is based on the machine’s local time.
- Whenever searches all available data, without any time constraints.
(Optional) If you have administrator privileges, you can select other Change Guardian servers for the search.

If you have data federation configured, you can perform a search on other Change Guardian servers. For more information, see Section 10.0, Configuring Data Federation.
Click Search.

The search results are displayed. For information on the search results, see Viewing Search Results.
(Optional) Modify the search criteria by clicking Edit Criteria.
(Optional) Modify the search results by selecting the desired event fields in the search results

To add an AND or Or condition to the existing criteria, left-click the event field, select the required fields, and then specify the desired condition.
Click Search.
(Conditional) To save the search query, see Saving a Search Query.

12.1.2 Viewing Search Results

Searches return a set of events. When results are sorted by relevance, only the top 50,000 events can be viewed. When results are sorted by time, all the events in the system are displayed.

Occasionally, the search engine might index events faster than they are inserted into the data directory. If you run a search that returns events that were not added in the data directory, you get a message indicating that some events match the search query, but they are not found in the data directory. If you run the search again later, the events are added to the data directory and the search is shown as successful.

To see detailed event information, click the shield icon.

The information in each event is grouped into the following categories:

Category	Icon	Description
General	No icon	Generic information about the event, such as severity, date, time, product name, and taxonomy.
Initiator		The source that caused the event to occur. The source can be a device, network port, etc.
Target		The object that is affected by the event. The object can be a file, database table, directory object, etc.
Observer		The service that observed the event activity.
Reporter		The service that reported the event activity.
Tags	No icon	Tags that the events are being tagged with.
Customer value	No icon	Fields set by the customer.
Retention period	No icon	Retention period of the event.

The initiator, target, and observer can be hosts, services, and accounts. In some cases, the initiator, target, and observer can be all the same, such as a user modifying this or her own account. In other cases, the initiator, target, and observer can be different, such as an intrusion detection system detecting a network attack. If an event field has no data, it is not displayed in the results.

Event fields are grouped according to the following categories:

Group	Icon	Description
Host		The initiator or target host information. For example, initiator host IP, target hostname, or target host ID.
User		The initiator or target user information. For example, the initiator username, initiator user department, target user ID, or target username.
Service		The initiator or target service information. For example, the target service name, target service component, or initiator service name.
Domain		Domain information of both the host and user. For example, the target host domain and initiator username.
IPCountry		The country information of the initiator and target trust. For example, the target host country.
Target trust		The target trust and target domain information of the event that was affected. The name can be a group, role, profile, etc.
Target data		The target data name and data container information. The data name is the name of the data object, such as a database table, directory object, or file that was affected by the event. The data container is the full path for data object.
Tenant name		The name of the tenant that owns the event data, applied to all the events in the inbound stream from a given Collector. The tenant name can be the name of the customer, division, department, etc.
Vulnerability		A flag that indicates whether Exploit Detection has matched this attack against known vulnerabilities in the target.

Each event type is represented by a specific icon. The following table lists the icons that represent the various types of events:

You can view the search results in the summary view and in the detailed view. When you mouse over an event field, the information about the field is displayed.

Icon	Type of Event
	Audit event
	Performance event
	Anomaly event
	Correlation event
	Unparsed event

Summary View

The Summary view of the search results displays the basic information about the event. The basic information includes severity, date, time, product name, taxonomy, and observer category for the event.

Detailed View

To view the report details, click the More link at the top right corner of the search results.

This displays details such as host/user domain information, IPCountry information, extended target fields like TargetTrust and TargetData, Observer and Reporter fields, customer set variables, default data retention duration information for any individual event, and the tags set for the event.
To view all the details of an event, click the All link.
To view details about all events, click the Show more details link at the top of the search results page.

You can expand or collapse the details for all events on a page by using the Show more details or Show less details link.

12.1.3 Refining Search Results

The search refinement panel can be used to narrow the search results by selecting one or more values for an event field. You can refine the results for one or more event fields.

The set of event fields that is displayed in the search refinement panel is configurable on a per-user basis.

For performance considerations, the maximum sample size used to calculate the event field value statistics is 50,000 events. The actual sample size is displayed in the field count label as Field counts based on the first <sample-size> events where <sample-size> is replaced by the actual sampling size.

To refine search results:

In the Reports and Searches panel, click New Search.
Specify the search criteria, then click Search.
Click fields in the REFINE section.The Select Event Fields window is displayed.
To refine the search, select the event fields from the available fields, then click Save.

The selected event fields are displayed in the REFINE panel.

A count at the right side of each event field displays the number of unique values that exist for that event field in the data directory. The calculation is based on the first 50,000 events found.

The event field selection is on a per-user basis. Each user can have a different set of selected event fields.
Click each event field to view the unique values for that event field.

For example, if the search results contain events that had severities 1, 2, 5, and 4, the event field is displayed as Severity (4).

The top 10 unique values are initially displayed in the order of most frequent to least frequent.

The value next to the check box represents the unique value for that event field and the value at the far right represents the number of times the value appears in the search result.

If there are multiple unique values occurring the same number of times in a search, the values are sorted by the most recent occurrence of the value.

For example, if events of severity 1 and 4 occurred 34 times in the search results, and an event of severity 4 was logged most recently, the unique value 4 appears at the top of the list.

To display the unique values in the order of least frequent to most frequent, click reverse.

When there are more than 10 unique values, you can view and filter either the top 10 or the bottom 10 unique values. You cannot refine your search on both the conditions at the same time.

In the following scenarios, the number of events returned from a refined search is greater than the number of values listed for an event field:
- If the refinement performs a new search with additional terms intersected with the initial search string, such as by using an AND operator, the new search is run against all events in the system, including the result set from the initial search. If new events that came into the system match the refined search, they are shown in the resulting set and the event count is greater than the field value count.
- If there are more than 50,000 events, the event field statistics are calculated only on the first 50,000 events.
  
  There could be an event field value that occurs 50 times in the first 50,000 events, but it could occur 1,000 times in all other stored events. In this scenario, the displayed value count is 50, but when the search is refined with this value it returns 1,000 events.
Click OK.

Selected event field values are listed under the event field in the REFINE panel.

The right panel displays the refined search results, which contain only the selected values.
Repeat Step 3 through Step 6 to further refine the search.
(Optional) Click clear to clear the selected unique event field values from the REFINE panel and to return to the original search results.
(Optional) Click add to search to add the refined search values to the current search tab and to recalculate the search statistics.

If you have already added the event field value to the current search tab, clicking clear does not return to the previous search results.

12.1.4 Saving a Search Query

You can save a search query, then repeat it as desired. To save a search query, you must first perform a search. When you are satisfied with the search results, you save the search query.

NOTE:You must have the necessary permission to access the specific options. For example, only users in the Report Administrator role can save the search query as a report template.

Saving a Search Query as a Search Template

Perform and refine a search until you are satisfied with the search results.

For more information, see Refining Search Results.
Click Save as, and then click Save search.
Specify a unique name for the search and provide an optional description.
Specify the following information in the Default Parameters section:

Data sources: Displays the number of servers that Change Guardian will search for events. This option is useful if data federation is enabled. To select the data sources you want to search, click selected data sources, then select the data sources.

Email to: To e-mail the report template to others, specify the e-mail address. To send the report template to more than one person, specify multiple e-mail addresses separated by a comma.

Result limit: Specify the number of results to be stored in the search template. By default, 1000 results are stored in a report template.
Click Save.

Saving a Search Query as a Filter

You can save your search queries as filters for future use so you can perform a search using the saved filters rather than specifying the query manually every time.

To save a search query as a filter:

Perform a search, and refine the search results as desired.

For more information, see Refining Search Results.
(Conditional) If you are using Change Guardian with traditional storage, click Save as, then click Save search as filter.
Specify a unique name for the filter and an optional description.
In the drop-down list, select one of the following options to specify the access for this filter:
- Private: Allows you to make this filter private. Other users cannot view or access this filter.
- Public: Allows you to share this filter with all users.
- Users in same role: Allows you to share this filter with users who have the same role as yours.
- Users in selected roles: Allows you to share this filter with users in specific roles. If you select this option, a blank field is displayed where you can specify the roles. As you type the role name, a list of roles is displayed.
  
  Select one or more roles.
  
  NOTE:This option is available only for users in the administrator role.
Click Save.

The saved filter is listed in the Filters panel.

Saving a Search Query as a Report Template

You can save the search query as a search report.

NOTE:You must have the Manage Reports permission to save the search query as a report template.

Perform a search, and refine the search results as desired.

For more information, see Refining Search Results.
When you are satisfied with the search results, click Save as, then click Save search as report.

Specify the following parameters:

Parameter	Description
Report name	Specify a unique name for the report. The name should not exceed 200 characters.
Based on	Select the base report from which you want to create the report. You can view a sample report by clicking the View Sample button.
Description	The description is automatically displayed based on the report that is selected and you can edit the description.
Criteria	Criteria is automatically populated based on the report selected and is not editable.
Additional criteria	Specify additional search criteria to the existing criteria. To build a new criteria on your own, click Edit Criteria. To build a new criteria from available system objects containing criteria, click Add Criteria. The criteria that you add here is appended to the existing criteria.
Data sources	Select the source machines on which the reports can be run by clicking the selected data sources link. You can select data sources only if your Change Guardian is configured for data federation. For more information, see Section 10.0, Configuring Data Federation.
Additional Criteria	Specify additional criteria to refine the results. The criteria that you specify here can be edited while scheduling the report. If you specify Criteria name, the name is displayed at the end of the report results. NOTE:This parameter is not available for all reports.
Time Zone	Specify the time zone with which you want to populate the report. When you schedule the report, the time zone that you specify here is displayed in the report data. For example, if the Time Zone is set to US/Pacific-New time, the report data displays the selected time zone. By default, it displays the time zone that is set in the client system. NOTE:This parameter is not available for all reports.
Date Range	If the report includes time period parameters, choose the date range. All time periods are based on the local time for the browser. The From Date and the To Date automatically change to reflect the option you selected. Current Day: Shows events from midnight of the current day until 11:59:00 PM of the current day. If the current time is 8:00:00 AM, the report shows 8 hours of data. Previous Day: Shows events from midnight yesterday until 11:59:00 PM yesterday. Week To Date: Shows events from midnight Sunday of the current week until the end of the selected day. Previous Week: Shows events for the last seven days. Month to Date: Shows events from midnight the first day of the current month until the end of the selected day. Previous Month: Shows events for a month, from midnight of the first day of the previous month until 11:59:00 PM. of the last day of the previous month. Custom Date Range: Shows events for a period whose start and end date are chosen. If you select Custom Date Range, set the start date (From Date) and the end date (To Date) for the report.
From Date	Lets you set the from date.
To Date	Lets you set the to date.
Event Name	Name of the event. Default value is *
Severity	0 1 All
Email to	Specify an e-mail address in the Email to field. If you want to mail the report to more than one user, separate the e-mail addresses with a comma.
Result limit	Specify the number of results to be displayed or stored when you run or schedule the report. By default, 1000 results are stored. If you specify a value in Group By field, the result limit is based on grouping.

Click Save to save the search as report definition.

You can see the saved report definition in the Reports and Searches panel.

Saving a Search Query as a Routing Rule

You must be in the administrator role to save the search query as a routing rule.

Perform a search, and refine the search results as desired.

For more information, Refining Search Results.
When you are satisfied with the search results, click Save as, then click Save search as routing rule.
Specify a name for the rule.
(Conditional) To associate one or more tags to the events, click Select tag, select the desired tags, then click Set.
Select where you want to route the events to:
- All: Events are routed to all Change Guardian services, including Correlation and Security Intelligence.
- Event store only: Events are sent directly to the event store, and are not displayed in Event Views and the search results page.
- None (drop): Events are dropped or ignored, and are not sent to any Change Guardian service.
Select one or more actions to be performed on each event that meets the search criteria. Click the plus and minus icons to add and remove actions.
Click Save.

Saving a Search Query as a Retention Policy

You must be in the administrator role to save the search query as a retention policy.

Perform a search, and refine the search results as desired.

For more information, see Searching Events and Refining Search Results.
When you are satisfied with the search results, click Save as, then click Save search as retention policy.
Specify a name for the retention policy.
In the Keep at least field, specify the minimum number of days to retain the events in the system. The value must be a valid positive integer.
(Optional) In the Keep at most field, specify the maximum number of days for which the events should be retained in the system.

The value must be a valid positive integer and must be greater than or equal to the Keep at least value. If no value is specified, the system retains the events in the system until the space is available in primary storage.
Click Save.

The newly created policy is displayed in the data retention table. For more information on retention policies, see Section 10.0, Configuring Data Federation.

12.1.5 Exporting the Search Results to a File

Perform a search, and refine the search results as desired.

For more information,
In the search results, select the events you want to export to a file.
Click Event operations > Export to file.
Specify the following information:

File Name: Specify a name for the file to which you want to export the search results.

Event Limit: Specify the maximum number of events to be saved. The event limit must be less than the number of events you selected and the maximum event limit is 200000.

All the search results are written into a .csv file. These files are then compressed into a .zip file for downloading.
(Optional) You can remove the event fields that you do not want to export to the file. Click Choose Fields, then clear the selections for the fields that you do not want to export to the file.

By default, the null fields are excluded and not exported to file.
Click Export to export the search result to a file.

A download file dialog box is displayed with an option to open or save the .zip file.
Select the desired option, then click OK.

12.1.6 Search Query Syntax

Change Guardian uses the Lucene query language for searching events. This section provides an overview of how to use the Lucene query language to perform searches in Change Guardian. For more advanced features, see Apache Lucene - Query Parser Syntax.

For information about the event fields in Change Guardian, click Tips on the top right corner. A table is displayed that lists the event names and their IDs.

Use the following search query:

Basic Search Query

A basic query is a search for a value on a field. The syntax is as follows:

msg:<value>

The field name (msg) is separated from the value by a colon.

For example, to search for a phrase that includes the word “authentication,” you can specify the search query as follows:

msg:authentication

Or, to search for events of severity 5, you can specify the search query as follows:

sev:5

If the value has spaces or other delimiters in it, you should use quotation marks. For example:

msg:"value with spaces"

Change Guardian classifies event fields as either tokenized fields or non-tokenized fields. A tokenized field is indexed and is searched differently than a non-tokenized field.

Case Insensitivity

Indexing and searching in Change Guardian is not case-sensitive. For example, the following queries are all equivalent:

msg:AdMin
msg:admin
msg:ADMIN

Special Characters

If you include special characters as part of a search, the special characters must be escaped. These characters are as follows:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

Use “ \” before the character you want to escape. For example, to search for ISO/IEC_27002:2005 in the rv145 (Tag) field, use the following query:

rv145:ISO\/IEC_27002\:2005

You can also use quotation marks around the query:

rv145:"ISO/IEC_27002:2005"

If the value contains quotation marks, you must escape it by using the “\” character instead of quotation marks. For example, to search for “system “mail” service” in the initiatorservicename field, you must specify the query as follows:

sp:"system \"mail\" service"

For more information about quoting wildcard characters, see Quoted Wildcards.

Operators

Lucene supports AND, OR, and NOT Boolean operators, which allow words to be combined. Boolean operators must be always capitalized.

OR Operator

The OR operator is the default conjunction operator. If there is no Boolean operator between two clauses, the OR operator is used. The OR operator links two clauses and finds a matching event if either of the clauses is satisfied. The symbol || can be used in place of the word OR. For example, consider the following query:

sun:admin OR dun:admin

This query finds events whose initiator user name or target user name is “admin.” The following query produces the same result because OR is used by default:

sun:admin dun:admin

AND Operator

The AND operator links two clauses and finds a matching event only if both clauses are satisfied. The symbol && can be used in place of the word AND. For example, consider the following query:

sun:admin AND dun:tester

This query finds events whose initiator user name is admin and the target user name is tester.

NOT Operator

The NOT operator excludes events that match the clause after the NOT. The symbol ! can be used in place of the word NOT. For example, consider the following query:

sev:[0 TO 5] NOT st:I NOT st:A NOT st:P

This query matches all events whose severity is between 0 and 5, but excludes those whose sensor type is I (internal), A (audit), or P (performance); that is, it excludes Change Guardian internal events.

The NOT operator cannot be used by itself because it is a way to exclude events from a set that has been found by other search terms. For example, consider the following query:

NOT st:I NOT st:A NOT st:P

This query might seem like it should return all events where the sensor type is not I, A, or P. However, it is an invalid query because a query cannot begin with the NOT operator.

Operator Precedence

Parentheses can be used in the usual way to change operator precedence. They can be nested to any depth, as shown in the following examples:

(sun:admin OR dun:admin) AND (sip:10.0.0.1 OR sip:10.0.0.2)

((sun:admin OR dun:admin) AND (sip:10.0.0.1 OR sip:10.0.0.2)) OR (msg:user AND evt:authentication)

The Default Search Field

Lucene uses a default search field, which is the field that is searched if no field is specified. In Change Guardian, _data is the default search field. By default, the default search field is a concatenation of the following event fields:

evt,msg,sun,iuid,dun,tuid,sip,sp,dip,dp,rv42,shn,rv35,rv41,dhn,rv45,obsip,sn,obsdom,obssvcname,ttd,ttn,rv36,fn,ei,rt1,rv43,rv40,isvcc

The default search field is indexed and searched as a tokenized field. The result is that you can search for words that might appear in any event field.

You can also customize the set of event fields that are concatenated in the default search field by adding the indexedlog.datafield.ids property in the configuration.properties file.

For example, suppose you have two non-tokenized fields in an event, sun (initiator user name) and dun (target user name). The sun field has the following value:

report-administrator

The dun field has the following value:

system-tester

The _data field contains the concatenation of these fields separated by a single space character:

report-administrator system-tester

Because the _data field is a tokenized field, the words “report,” “administrator,” “system,” and “tester” are indexed and searchable. The following queries would find this event:

report

_data:report

report-administrator

_data:report-administrator

report tester

In addition, the following queries also find this event:

sun:report-administrator

dun:system-tester

Tokenized Fields

Fields that are classified as tokenized fields are parsed into individual words for indexing. Therefore, a search occurs only on words within the field value. Characters that are considered to be word delimiters are not searchable, nor are words that are considered to be stop words. Lucene removes extremely common words to save disk space and speed up searching. These words are ignored in search filters. Currently, the following stop words are removed:

a
an
and
are
as
at
be
but
by
for
if
in
into
is
it
no
not
of
on
or
such
that
the
their
then
there
these
they
this
to
was
will
with

When it does a search, Lucene examines all of the words in a field and tries to match words in the search value. For example, suppose that you specify a search for messages containing the following value:

msg:"user-authentication failed on the server"

The words that are parsed within this value are “user,” “authentication,” “failed,” and “server.” These are the only search words that would match this value. “On” and “the” are omitted because they are stop words.

The value has the hyphen character (-) between some words. Hyphens are treated as word delimiters, so Lucene does not search for hyphens. Consider, the following query:

msg:"user-authentication"

The results might not be exactly what you expect. The query search value matches the value, but not because it is matching the hyphen. It matches because Lucene first parses the words in the search value and identifies the words “user” and “authentication.” Lucene then matches those words against values that have the words “user” and “authentication” with no intervening words in between. This query would also match the following value, even though there is no hyphen between “user” and “authentication”:

user authentication has failed on the server

Consider the following query:

msg:"failed on server"

This query has the stop word, "on," which is ignored. However, the stop word does affect the relative positioning that is expected to be between words when evaluating a value to see if it matches. The “failed on server” search matches any phrase where the words failed and server are separated by exactly one word. It does not matter what the word is because the separating word is a stop word and is ignored. Thus, the above query would match all of the following:

failed on server

failed-on server

failed a server

failed-a-server

Proximity indicators created by using the ~ character followed by a value, make this more complicated. The query dictates an expected distance between words. In the “failed on server” query, the expected distance between “failed” and “server” is one word. The proximity indicator specifies how much variance there can be from the expected distance. For example, consider the following query, where a proximity indicator of one (~1) is specified:

msg:"failed on server"~1

This query indicates that the distance between “failed” and “server” could be plus or minus one from the expected distance, which is one because of the stop word “on.” Thus, the distance could be 1, 1-1 (0), or 1+1 (2). Thus, all of the following would match:

failed on server

failed on the server

failed finance server

As of Lucene version 3.1, word parsing is done according to word break rules outlined in the Unicode Text Segmentation algorithm. For more information, see Unicode Text Segmentation.

For information about tokenized fields in Change Guardian, click Tips. A table is displayed that lists all the event fields and whether an event field is searchable or not.

Non-Tokenized Fields

Fields that are classified as non-tokenized fields are parsed fully for indexing. Thus, a search occurs on full field values. For example, to search events whose initiatoruserfullname (iufname) field has the value “Bob White”, you must specify the query as follows:

iufname:"Bob White"

Wildcards in Search Queries

Change Guardian supports wildcards in search values but not in regular expressions:

The asterisk (*) matches zero or more characters.
The questions mark (?) matches any one character.

NOTE:The search query characters should be in lowercase along with the wildcard. For example: polid:imanag*

For example:

adm*test: Matches admtest, ADMTEST, admintest, adMINtEst (note the lack of case sensitivity).
adm?test: Matches adm1test and adMatest. Does not match admtest or ADMINTEST because it must have exactly one character between “adm” and “test”.

Wildcards in Tokenized Fields

Wildcards are applied differently to tokenized fields and non-tokenized fields. Wildcards for tokenized fields match only words that were parsed from the value and not the entire value. For example, if you specify the search query msg:authentication*failed to search for the message The user authentication has failed on the server, it does not return the events with this message. This is because “*” does not match anything between “authentication” and “failed.” However, it matches any words that begin with “authentication” and end with “failed.” For example, it returns results if any of the following words are used: “authenticationhasfailed,” “authenticationuserfailed,” and “authenticationserverfailed.” For tokenized fields, all matching that uses wildcard searches is done on the words within the value and not on the full value.

Quoted Wildcards

Tokenized Fields

When wildcards are quoted, they are not treated as wildcards, but as word delimiters. For example, consider the following query:

msg:"user* fail*"

The search value "user* fail*" is parsed into two words, “user” and “fail.” The semantic is "find any event where the msg field contains “user” AND “fail” words in that order, and there are no intervening words between them.” Thus, it does not match the following value:

The user authentication has failed on the server.

This is because the wildcard is not treated as a wildcard but as a word delimiter.

Non-Tokenized Fields

When wildcards are quoted, they are treated as literal characters to search. For example, if the query is: sun:"adm*," it returns the following values:

adm*

ADM* (case-insensitive)

The query does not return the following values:

admin

ADMIN

Leading Wildcards

Leading wildcards are not valid in searches because Lucene does not allow the * or ? characters to be the first character of a search value. For example, the following queries are invalid:

sun:*adm* The semantic is “find any event whose initiator user name value contains the letters a, d, and m in sequence.“
sun:*tester The semantic is “find any event whose initiator user name value ends with “tester.”
sun:* The semantic is “find any event whose initiator user name field is non-empty.”

Because this is an important type of query, Change Guardian provides an alternative way to accomplish this. For more information, see The notnull Query.

The notnull Query

You might need to find events where some field is present, or non-empty. For example, to find all events that have a value in the sun field, you can specify the query as sun:*

The query does not return the expected results because Lucene does not support wildcards to be the first character of a search value. However, Change Guardian provides an alternate solution. For every event, Change Guardian creates a special field called notnull. The notnull field is a list of all fields in the event that are not null (not empty). For example, if there is an event that has values in the evt, msg, sun, and xdasid fields, the notnull field contains the following value:

evt msg sun xdasid

The notnull field is a tokenized field, so the following kinds of queries are possible:

notnull:sun Finds all events whose sun field has a value.
notnull:xdas* Finds all events where any field beginning with the name "xdas" has a value.

When a notnull field is added in Lucene, creating, indexing, and storing this field adds a cost to processing each event as CPU needs to create and index the field and it also requires additional storage space. If you want to disable storing the list of non-empty fields in the notnull field, set the following property in the /etc/opt/novell/sentinel/config/configuration.properties file:

indexedlog.storenotnull=false

Save the file and restart the Change Guardian server. All events received after this property was set do not have a notnullfield associated.

NOTE:If you disable the notnull field, do not use the notnull field in search filters, rule filters, or policy filters because the results might be incorrect and unpredictable.

Tags in Search Queries

The Tag field (rv145) is a tokenized field that has special parsing rules for words. The parsing rules enable you to search on tags that include non-alphanumeric characters. However, the only word delimiters are white space characters, such as the blank and the tab. This is because tags do not include white space in their names. For example, the following queries find the event if the event is tagged with the ISO/IEC_27002:2005 tag and the NIST_800-53 tag:

rv145:"ISO/IEC_27002:2005"

rv145:"iso/iec_27002:2005"

rv145:"ISO/IEC_27002*"

rv145:nist_*

The slash (/), hyphen (-), and colon (:) characters are significant in the search value because, unlike other tokenized fields, the parsing rules for rv145 do not treat them as a word delimiter. Also, the search is not case sensitive.

The following queries would not find the event:

rv145:"ISO IEC_27002 2005"

rv145:"iso *"

Regular Expression Queries

Regular expression queries allow you to search events that match a pattern. These queries must be enclosed in quotation marks (“ “) and forward slash (/). For example, to search for an initiator user name that ends with the character "a”, you can specify the search query as follows:

sun:"/.*a/"

If you need to include special characters in your query, you must escape special characters by preceding them with the backslash (\) character. For example, to search for an initiator user name that ends with the character “$”, you can specify the search query as follows:

sun:"/.*\$/"

For more information about using special characters, see Special Characters.

NOTE:Regular expression queries utilize significantly more system resources than other kinds of queries because they are unable to leverage the more efficient data structures available in the index. Executing regular expression queries take longer than other kinds of queries and potentially pull system resources from other components of the system. Therefore, use regular expression queries carefully and narrow the breadth of the search as much as possible by using time range and non-regular expression criteria terms.

Range Queries

Range queries allow you to find events where a field value is between a lower bound and an upper bound. Range queries can be inclusive or exclusive of the upper and lower bounds. Whether a particular value falls in the specified range is based on lexicographic character sorting. Inclusive ranges are denoted by square brackets []. Exclusive ranges are denoted by curly brackets {}.

For example, consider the following query:

sun:[admin TO tester]

This query finds events whose sun field has values between admin and tester, inclusive. Note that "TO" is capitalized.

However, if you change the query as follows:

sun:{admin TO tester}

The query now finds all events whose sun field is between admin and tester, not including admin and tester.

Some event fields, such as sev and xdasid are numeric. In Change Guardian, range queries on numeric fields are based on numeric sorting and not on lexicographic character sorting. For example, consider the following query:

xdasid:[1 TO 7]

This query returns events whose xdasid value is 1, 2, 3, 4, 5, 6, or 7. If the range evaluation was based on lexicographic sorting, it would incorrectly match 10, 101, 100001, 200, and so on.

IP Addresses Query

There are several extensions that Change Guardian has implemented for searching on IP addresses. Specifically, there are a number of convenient ways to specify IP address ranges. These are explained in the following sections:

CIDR Notation

Change Guardian supports the Classless Inter-Domain Routing (CIDR) notation as a search value for IP address fields, such as sip (initiator IP) and dip (target IP) for specifying an IP address range. The notation uses a combination of an IP address and a mask, as follows:

"xxx.xxx.xxx.xxx/n"

In this notation, n is the number of high order bits in the value to match. For example, consider the following query:

sip:"10.0.0.0/24"

This query returns events whose sip field is an IPv4 address ranging from 10.0.0.0 to 10.0.0.255.

The same notation works for IPv6 addresses. For example, consider the following query:

sip:"2001:DB8::/48"

This query returns events whose sip field is an IPv6 address ranging from 2001:DB8:: to 2001:DB8:0:FFFF:FFFF:FFFF:FFFF:FFFF.

Wildcards in IP Addresses

You can use only the asterisk character (*) in the IP address search values to specify ranges of IP addresses. You cannot use the question mark (?) character.

In IPv4 addresses, an asterisk (*) can be used at any of the positions in the quad format. In IPv6 addresses, an asterisk (*) can be used between colons to specify a 16-bit segment. For example, all of the following queries are valid on the sip field:

sip:10.*.80.16

sip:10.02.*.*

sip:10.*.80.*

sip:"CAFE:*::FEED"

sip:"CAFE:*:FADE:*::FEED"

If an asterisk (*) is used in one of the quad positions in an IPv4 address or between colons in an IPv6 address, it cannot be combined with other digits. For example, all of the following queries are invalid:

sip:10.*7.80.16

sip:10.10*.80.16

sip:"CAFE:FA*::FEED"

sip:"CAFE:*DE::FEED"

Because the question mark (?) is not allowed, the following queries are invalid:

sip:10.10?.80.16

sip:10.?.80.16

sip:"CAFE:FA??::FEED"

sip:"CAFE:??DE::FEED"