The auditing system allows the user to capture events which occur on the system, and log them to an audit file. More...

Inheritance diagram for Audit:

[legend]

Collaboration diagram for Audit:

[legend]

Static Public Member Functions
_.Library.Status	Convert (_.Library.Integer Count)
	Converts Audit records to the current IRIS format. More...

_.Library.String	ConvertLocalHToUTC (_.Library.String LocalH)
	Convert the local $H time to an ODBC format string in UTC. More...

_.Library.String	ConvertUTCHToLocal (_.Library.String UTC)
	Convert a UTCTimeStamp in ODBC format to Local Time in ODBC format. More...

_.Library.Status	Copy (_.Library.Integer NumCopied, _.Library.String Namespace, _.Library.Integer Flags, _.Library.String BeginDateTime, _.Library.String EndDateTime, _.Library.String EventSources, _.Library.String EventTypes, _.Library.String Events, _.Library.String Usernames, _.Library.String SystemIDs)
	Copy matching audit records to a defined namespace. More...

_.Library.Status	Delete (_.Library.Integer NumDeleted, _.Library.String BeginDateTime, _.Library.String EndDateTime, _.Library.String EventSources, _.Library.String EventTypes, _.Library.String Events, _.Library.String Usernames, _.Library.String SystemIDs)
	Delete matching audit records. More...

_.Library.Status	Erase (_.Library.Integer Flags)
	Erase the audit file. More...

_.Library.Boolean	Exists (_.Library.String UTCTimeStamp, _.Library.String SystemID, _.Library.Integer AuditIndex, _.Library.ObjectHandle Audit, _.Library.Status Status)
	Audit record exists. More...

_.Library.Status	Export (_.Library.String FileName, _.Library.Integer NumExported, _.Library.Integer Flags, _.Library.String BeginDateTime, _.Library.String EndDateTime, _.Library.String EventSources, _.Library.String EventTypes, _.Library.String Events, _.Library.String Usernames, _.Library.String SystemIDs)
	Export matching records to an xml file. More...

_.Library.Status	Get (_.Library.String UTCTimeStamp, _.Library.String SystemID, _.Library.Integer AuditIndex, _.Library.String Properties)
	Get the Audit properties. More...

_.Library.Status	Import (_.Library.String FileName, _.Library.Integer NumImported, _.Library.Integer Flags)
	Import audit records from an xml file. More...

_.Library.Status	Modify (_.Library.String UTCTimeStamp, _.Library.String SystemID, _.Library.Integer AuditIndex, _.Library.String Properties)
	Modify an Audit record's properties. More...

_.SYS.Audit	OpenAuditItem (_.Library.String UTCTimeStamp, _.Library.String SystemID, _.Library.BigInt AuditIndex)
	Open an Audit Log item, given its ID information (UTC date, system ID, and audit index). More...

Public Attributes
	AuditIndex
	More...

	Authentication
	Authentication method process used. More...

	CSPSessionID
	Session ID of the process if a CSP process. More...

	ClientExecutableName
	Executable name on the client machine. More...

	ClientIPAddress
	IP address of the client, as passed from client. More...

	Description
	Description of the audit event. More...

	Event
	Name of the audit event. More...

	EventData
	EventData – arbitrary data associated with this event. More...

	EventSource
	Event Source (system events all have "%System" here). More...

	EventType
	EventType. More...

	GroupName
	Group of the audit event. More...

	JobId
	Job ID. More...

	JobNumber
	Job Number. More...

	Namespace
	Namespace process was executing in. More...

	OSUsername
	Operating system username of process. More...

	Pid
	Process ID. More...

	Roles
	$ROLES value that was active when the audit event occurred. More...

	RoutineSpec
	Routine running including DB and System. More...

	StartupClientIPAddress
	IP address of the client, as detected on the TCP channel by the server process. More...

	Status
	Any Status variable passed into the call. More...

	SystemID
	SystemName:ConfigurationName of where the event was generated. More...

	UTCTimeStamp
	UTC $ZTIMESTAMP value when the audit event occurred. More...

	UserInfo
	User info field. More...

	Username
	Username from $Username that was active when audit event occurred. More...

Detailed Description

The auditing system allows the user to capture events which occur on the system, and log them to an audit file.

When running SQL queries on the audit log, it is helpful to use the UTCTimestamp in the WHERE clause to speed up the query, and minimize the amount of data which is returned. For example:

SELECT SystemID,AuditIndex,UTCTimeStamp,EventSource,EventType,Event,Pid,CSPSessionID,Username,Description<br>
FROM %SYS.Audit<br>
WHERE UTCTimeStamp BETWEEN :UTCBeginDateTime AND :UTCEndDateTime<br>
ORDER BY UTCTimeStamp DESC, SystemID DESC, AuditIndex DESC<br>
<br>
The UTCTimeStamp is the UTC time in ODBC format. To convert a local $H time to this format use
the following:<br><br>
s x=##Class(%SYS.Audit).ConvertLocalHToUTC($H)
<br>
The UTCTimeStamp which is returned as part of the record, can be converted to local time
with the following:<br><br>
s x=##Class(%SYS.Audit).ConvertUTCToLocal(UTCTimeStamp)<br><br>

Access to all the audit class methods require the Admin_Secure:"Use" privilege.

If you wish to modify an audit record, use the Modify() class method. If you wish to modify it using direct object you must first use the OpenAuditRecord() class method and then the Save() method. Note that saving the object in this way also requires that the user have write access to the Audit database resource.

Member Function Documentation

◆ Convert()

_.Library.Status Convert ( _.Library.Integer Count )

static

Converts Audit records to the current IRIS format.

This is called before any of the Audit methods runs and also during an upgrade to make sure that the audit global is in the current format.
It will also check if there are any audit records in Cache' format (stored in the ^CacheAuditD global) and merge those globals into the current IRIS audit global.
Note that journaling is turned off for the process during the conversion.

Parameters:
Count (byref) - Returned count of number of audit records converted.
0 - Version already matches.
Requires Admin_Secure:"Use" privilege.

◆ ConvertLocalHToUTC()

_.Library.String ConvertLocalHToUTC ( _.Library.String LocalH )

static

Convert the local $H time to an ODBC format string in UTC.

When using SQL, use this function to convert a local time in $h to UTC time to use in your SELECT statement.

◆ ConvertUTCHToLocal()

_.Library.String ConvertUTCHToLocal ( _.Library.String UTC )

static

Convert a UTCTimeStamp in ODBC format to Local Time in ODBC format.

◆ Copy()

_.Library.Status Copy	(	_.Library.Integer	NumCopied,
		_.Library.String	Namespace,
		_.Library.Integer	Flags,
		_.Library.String	BeginDateTime,
		_.Library.String	EndDateTime,
		_.Library.String	EventSources,
		_.Library.String	EventTypes,
		_.Library.String	Events,
		_.Library.String	Usernames,
		_.Library.String	SystemIDs
	)

static

Copy matching audit records to a defined namespace.

Parameters:
BeginDateTime - $zdatetime($H,3) value of the first audit record to copy, "" = first record
EndDateTime - $zdatetime($H,3) value of the Last audit record to copy, "" = Last record
The following parameters may be specified as a comma separated list as follows:
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
Note that these are all case insensitive matches
EventSources - Comma separated list of valid event sources
EventTypes - Comma separated list of valid event types
Events - Comma separated list of event names
Usernames - Comma separated list of user names
SystemIDs - Comma separated list of System:Config names
Namespace - Valid namespace to copy audit records to
Flags - Bit 0 - Delete audit record after copy
Return values:
NumCopied (byref) - Number of audit records copied
Requires Admin_Secure:"Use" privilege.

◆ Delete()

_.Library.Status Delete	(	_.Library.Integer	NumDeleted,
		_.Library.String	BeginDateTime,
		_.Library.String	EndDateTime,
		_.Library.String	EventSources,
		_.Library.String	EventTypes,
		_.Library.String	Events,
		_.Library.String	Usernames,
		_.Library.String	SystemIDs
	)

static

Delete matching audit records.

Parameters:
BeginDateTime - $zdatetime($H,3) value of the first audit record to delete, use "" to begin with the first record
EndDateTime - $zdatetime($H,3) value of the Last audit record to delete. Audit records will be deleted up through, but not including, this value. Use "" to delete through last record
The following parameters may be specified as a comma separated list as follows:
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
Note that these are all case insensitive matches
EventSources - Comma separated list of valid event sources
EventTypes - Comma separated list of valid event types
Events - Comma separated list of event names
Usernames - Comma separated list of user names
SystemIDs - Comma separated list of System:Config names
Return values:
NumDeleted (byref) - Number of audit records deleted
Requires Admin_Secure:"Use" privilege.

◆ Erase()

_.Library.Status Erase ( _.Library.Integer Flags )

static

Erase the audit file.

Flags: 0 - Erase all contents
1 - Erase and create new audit file
2 - Erase and create new audit file, treat as encryption state changed
Note that bit 1 infers that ALL data in the audit database will be deleted, not just Audit data
Requires Admin_Secure:"Use" privilege.

◆ Exists()

_.Library.Boolean Exists	(	_.Library.String	UTCTimeStamp,
		_.Library.String	SystemID,
		_.Library.Integer	AuditIndex,
		_.Library.ObjectHandle	Audit,
		_.Library.Status	Status
	)

static

Audit record exists.

This method checks for the existence of an Audit record in the security database.
Parameters:
UTCTimeStamp - UTC timestamp of the audit record
SystemID - System ID of the audit event, usually NODE:CFGNAME
AuditIndex - Index number of the audit record
Return values:
If Value of the method = 0 (Audit record does not exist, or some error occured)
Audit = Null
Status = Audit "x" does not exist, or other error message<br>
If Value of the method = 1 (Audit record exists)
Audit = Object handle to Audit record
Requires Admin_Secure:"Use" privilege.
If you wish to modify the returned object, use the Modify() method.

◆ Export()

_.Library.Status Export	(	_.Library.String	FileName,
		_.Library.Integer	NumExported,
		_.Library.Integer	Flags,
		_.Library.String	BeginDateTime,
		_.Library.String	EndDateTime,
		_.Library.String	EventSources,
		_.Library.String	EventTypes,
		_.Library.String	Events,
		_.Library.String	Usernames,
		_.Library.String	SystemIDs
	)

static

Export matching records to an xml file.

Parameters:
FileName - Valid filename to copy audit records to
Flags - Bit 0 - Delete audit record after export
BeginDateTime - $zdatetime($H,3) value of the first audit record to copy, "" = first record
EndDateTime - $zdatetime($H,3) value of the Last audit record to copy, "" = Last record
The following parameters may be specified as a comma separated list as follows:
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
Note that these are all case insensitive matches
EventSources - Comma separated list of valid event sources
EventTypes - Comma separated list of valid event types
Events - Comma separated list of event names
Usernames - Comma separated list of user names
SystemIDs - Comma separated list of System:Config names
Username - Comma separated list of user names to copy, "*" = All
Return values:
NumCopied (byref) - Number of audit records exported.
Note: Two audit record will get written out when this is called in case the first one is deleted as part of the export operation.
Requires Admin_Secure:"Use" privilege.

◆ Get()

_.Library.Status Get	(	_.Library.String	UTCTimeStamp,
		_.Library.String	SystemID,
		_.Library.Integer	AuditIndex,
		_.Library.String	Properties
	)

static

Get the Audit properties.

Parameters:
SystemID - System ID of the audit event, usually NODE:CFGNAME
AuditIndex - Index number of the audit record
Return values:
Properties - Array of properties
Properties("AuditIndex")
Properties("ClientExecutableName")
Properties("ClientIPAddress")
Properties("CSPSessionID")
Properties("Description")
Properties("Event")
Properties("EventData")
Properties("EventSource")
Properties("EventType")
Properties("JobId")
Properties("Namespace")
Properties("Pid")
Properties("Roles")
Properties("RoutineSpec")
Properties("StartupClientIPAddress")
Properties("SystemID")
Properties("Username")
Properties("UTCTimeStamp")
Requires Admin_Secure:"Use" privilege.

◆ Import()

_.Library.Status Import	(	_.Library.String	FileName,
		_.Library.Integer	NumImported,
		_.Library.Integer	Flags
	)

static

Import audit records from an xml file.

Parameters:
FileName - Valid filename to import audit records from
NumImported (byref) - Returns number of records imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
Audit records may not be imported into the SYS namespace
Requires Admin_Secure:"Use" privilege.

◆ Modify()

_.Library.Status Modify	(	_.Library.String	UTCTimeStamp,
		_.Library.String	SystemID,
		_.Library.Integer	AuditIndex,
		_.Library.String	Properties
	)

static

Modify an Audit record's properties.

Modifies an Audit records properties from the security database.
Parameters:
UTCTimeStamp - UTC timestamp of the audit record
SystemID - System ID of the audit event, usually NODE:CFGNAME
AuditIndex - Index number of the audit record
See the Get() method for a description of the Properties parameter.
If a specific property is not passed in the properties array, the value is not modified.
Requires Admin_Secure:"Use" privilege.

◆ OpenAuditItem()

_.SYS.Audit OpenAuditItem	(	_.Library.String	UTCTimeStamp,
		_.Library.String	SystemID,
		_.Library.BigInt	AuditIndex
	)

static

Open an Audit Log item, given its ID information (UTC date, system ID, and audit index).

Requires Admin_Secure:"Use" privilege.
If you wish to modify the returned object, use the Modify() method.

Member Data Documentation

◆ AuditIndex

AuditIndex

◆ Authentication

Authentication

Authentication method process used.

◆ CSPSessionID

CSPSessionID

Session ID of the process if a CSP process.

◆ ClientExecutableName

ClientExecutableName

Executable name on the client machine.

◆ ClientIPAddress

ClientIPAddress

IP address of the client, as passed from client.

This corresponds to the ClientIPAddress in SYS.ProcessQuery.

◆ Description

Description

Description of the audit event.

Control characters less than $c(32) are not allowed in this data except for CR,LF, and tab.

◆ Event

Event

Name of the audit event.

◆ EventData

EventData

EventData – arbitrary data associated with this event.

Control characters less than $c(32) are not allowed in this data except for CR,LF, and tab.

◆ EventSource

EventSource

Event Source (system events all have "%System" here).

◆ EventType

EventType

EventType.

◆ GroupName

GroupName

Group of the audit event.

◆ JobId

JobId

Job ID.

◆ JobNumber

JobNumber

Job Number.

◆ Namespace

Namespace

Namespace process was executing in.

◆ OSUsername

OSUsername

Operating system username of process.

Username given to the process by the operating system when the process is created. When displayed, it is truncated to 16 characters. Note that the real O/S username is only returned when connecting to UNIX or VMS systems; For Windows, it will return the O/S username for a console process, but for telnet it will return the $USERNAME of the process. For client connections, it contains the O/S username of the client.

◆ Pid

Pid

Process ID.

Note that on VMS system, the Hex pid is stored internally as a decimal value, i.e. $zh(pid).

◆ Roles

Roles

$ROLES value that was active when the audit event occurred.

◆ RoutineSpec

RoutineSpec

Routine running including DB and System.

◆ StartupClientIPAddress

StartupClientIPAddress

IP address of the client, as detected on the TCP channel by the server process.

This corresponds to the StartupClientIPAddress in SYS.ProcessQuery.

◆ Status

Status

Any Status variable passed into the call.

◆ SystemID

SystemID

SystemName:ConfigurationName of where the event was generated.

This is useful when merging separate audit streams from different systems.

◆ UTCTimeStamp

UTCTimeStamp

UTC $ZTIMESTAMP value when the audit event occurred.

◆ UserInfo

UserInfo

User info field.

◆ Username

Username

Username from $Username that was active when audit event occurred.

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ Convert()

◆ ConvertLocalHToUTC()

◆ ConvertUTCHToLocal()

◆ Copy()

◆ Delete()

◆ Erase()

◆ Exists()

◆ Export()

◆ Get()

◆ Import()

◆ Modify()

◆ OpenAuditItem()

Member Data Documentation

◆ AuditIndex

◆ Authentication

◆ CSPSessionID

◆ ClientExecutableName

◆ ClientIPAddress

◆ Description

◆ Event

◆ EventData

◆ EventSource

◆ EventType

◆ GroupName

◆ JobId

◆ JobNumber

◆ Namespace

◆ OSUsername

◆ Pid

◆ Roles

◆ RoutineSpec

◆ StartupClientIPAddress

◆ Status

◆ SystemID

◆ UTCTimeStamp

◆ UserInfo

◆ Username