This chapter explains the main administration tasks and tools you use to manage the audit store, audit policies, and bus-stop files.
This chapter includes the following topics:
Setting up audit in your environment involves the following major tasks:
Planning the type of store to use for audit records and the store configuration details. For information about audit store management, see Managing the Audit Store.
Configuring and maintaining audit policies so that audit events are generated. For information about audit policies, see Managing Audit Policies.
Configuring audit reports and queries. For information about reporting, see Chapter 15, "Using Audit Analysis and Reporting."
Registering applications. For information about application registration, see Section 22.3, "Registering the Application with the Service."
Migrating audit information. For information about audit data migration, see Section 6.6.3, "Migrating Audit Data."
Administering the audit database, including increasing the database size that stores the generated audit data, and backing up and purging that data. For information about audit administration, see Audit Database Administration.
The audit store is a database that provides the scalability and high-availability needed to store audit records and that allows you to view and generate reports.
The following sections introduce the audit store and explain how to manage it:
When you create a domain, the process generates the audit schema, a data structure required to store audit records in the database. It also sets up an audit data source in the server that uses the audit schema. If your environment is not set up with a database to store records, then audit records are kept in bus-stop files.
See also:
After the bus-stop file reaches a certain size and all the data was uploaded to the database, the audit loader deletes the file from the file system. Specify the location and maximum size of bus-stop files, so that bus-stop files are automatically deleted. Deleting audit files manually is not recommended.
Bus-stop files for Java components are located in the following directory:
$DOMAIN_HOME/servers/$SERVER_NAME/logs/auditlogs/Component_Type
Bus-stop files for system components are located in the following directory:
$ORACLE_INSTANCE/auditlogs/Component_Type/Component_Name
In Java components, the maximum size of a bus-stop file is set with the audit.maxFileSize property.
In system components, the maximum size of a bus-stop file is set in the auditconfig.xml file:
<serviceInstance name="audit" provider="audit.provider"> <property name="audit.maxFileSize" value="10240" /> <property name=" audit.loader.repositoryType " value="Db" /> </serviceInstance>
When you switch from a file to a database store for audit data, all the events collected in the files are moved to the database tables and the audit files are deleted.
The standalone audit loader moves records from bus-stop files to the audit store periodically. The mechanism driving the audit loader depends on the application environment:
Java EE components and applications use the audit loader functionality provided by OPSS runtime. The standalone audit loader is not needed in these environments.
System components and non-Java applications use the audit loader functionality provided by the StandAloneAuditLoader command.
Java SE applications also use the standalone audit loader depending on where the bus-stop files are written. For information about audit for Java SE applications, see Section 24.5.4, "Common Audit Scenarios in Java SE Applications."
The following sections explain how to set up and run the standalone audit loader:
The following settings apply only to non-Java applications and system components.
Before you run the standalone audit loader, set the following audit loader parameters:
ORACLE_HOME, the full path to the home directory
COMMON_COMPONENTS_HOME, the full path to the Java Required Files (JRF) directory
ORACLE_INSTANCE, the full path of an Oracle instance directory
auditloader.jdbcString, the Java Database Connectivity (JDBC) connection string for the database where the audit data is stored
auditloader.username, the name of the user who runs the audit loader
In addition, make sure that the password for the database schema user is available and stored. This password is specified once.
To specify the database schema user password, use the java StandAloneAuditLoader command with the -Dstore.password=true property:
$JDK_HOME/bin/java
-classpath $COMMON_COMPONENTS_HOME/modules/oracle.jps_12.2.1/jps-manifest.jar
-Doracle.home=$ORACLE_INSTANCE -Doracle.instance=$ORACLE_INSTANCE
-Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid
-Dauditloader.username=username
-Dstore.password=true
oracle.security.audit.ajl.loader.StandaloneAuditLoader
which will prompt you to enter a password. The command generates the cwallet.sso file containing the password you entered.
To run the loader, use the StandAloneAuditLoader command:
$JDK_HOME/bin/java
-classpath $COMMON_COMPONENTS_HOME/modules/oracle.jps_12.2.1/jps-manifest.jar
-Doracle.home=$ORACLE_INSTANCE -Doracle.instance=$ORACLE_INSTANCE
-Dauditloader.jdbcString=jdbc:oracle:thin:@host:port:sid
-Dauditloader.username=username
oracle.security.audit.ajl.loader.StandaloneAuditLoader
This command is typically scheduled to run automatically so that audit records are periodically uploaded to the audit store.
An audit policy is a declaration of the type of events that are recorded by Oracle Fusion Middleware Audit Framework (OFM Audit Framework) for a particular component. In Java components, the audit policy is defined at the domain level. In system components, the audit policy is managed at the component instance level.
Note that you must update audit policies when you introduce changes to the application environment, such as adding or deleting components or users. Policy changes do not require server or instance restart.
OFM Audit Framework lets you configure audit policies and provides high control over the types of events and data being audited. You configure audit policies with Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control), WebLogic Scripting Tool (WLST), or programmatically, as explained in the following sections:
See also:
Section 13.2, "Audit Terminology"
Appendix C, "Oracle Fusion Middleware Audit Framework Reference"
Follow the instructions in this section to manage audit policies for Java and system components with Fusion Middleware Control.
Task 5, Importing and Exporting Audit Policies for a Java Component
Task 9, Importing and Exporting Audit Policies for a System Component
Task 1, Opening the Audit Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Audit Policy. The Audit Policy page is displayed.
Task 2, Choosing Events to Audit for a Java Component
In the Audit Component Name drop-down, choose a Java component. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
Note:
The values you enter in the Audit Policy Settings area do not apply to Oracle Access Manager audit.In the Audit Level drop-down, choose the audit level according to your needs:
None - Selects no event categor.ies
Low, Medium, High - Selects subsets of event categories representing predefined audit levels.
Custom - Selects custom filters.
Check flags are displayed in the Select for Audit column, and events in the chosen categories will be audited. View the events within a flagged category by clicking on that row in the categories table. The table of events can be edited in a custom level only.
Task 3, Customizing Audit Policies for a Java Component
In the Audit Component Name drop-down, choose a Java component. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
In the Audit Level drop-down, choose Custom. All categories become available.
Choose categories and events to customize the audit policy by checking the box in the Select For Audit column.
Click Apply to save the changes.
Task 4, Creating Audit Filters for a Java Component
In the Audit Component Name drop-down, choose a Java component. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
A pencil icon in the Edit Filter column denotes that a filter is available for the event. Click on a pencil icon for an event. The Edit Filter dialog is displayed.
Each filter attribute has a formal name and a display name. Either name is displayed in the Edit Filter edit dialog.
Create a filter condition by choosing an item from the Condition drop-down, an operator, and a value. Then click the add button. When you are finished adding conditions, click OK.
Optionally, under Users to Always Audit, specify a comma-separated list of users to audit events initiated by these users. Audit occurs regardless of the audit level or filters that have been specified. User names you enter in this field are not validated
Restart Oracle WebLogic Server on which the Java component is running for the changes to take place.
Task 5, Importing and Exporting Audit Policies for a Java Component
In the Audit Component Name drop-down, choose a Java component. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
At any time while editing a policy, do one of the following:
Click Export to save the current settings to a file
Click Import to load settings from a file
Task 6, Choosing Events to Audit for a System Component
Go to a system component home page. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
In the Audit Level drop-down, choose the audit level.
None, selects no event categor.ies
Low, Medium, High - Selects subsets of event categories representing predefined audit levels.
Custom - Selects custom filters.
Check flags are displayed in the Select for Audit column, and events in the chosen categories will be audited. View the events within a flagged category by clicking on that row in the categories table. The table of events can be edited in a custom level only.
Task 7, Customizing Audit Policies for a System Component
go to a system component home page. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
In the Audit Level drop-down, choose Custom. All categories become available.
Choose categories and events to customize the audit policy by checking the box in the Select For Audit column.
Click Apply to save the changes.
Task 8, Creating Audit Filters for a System Component
Go to a system component home page. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
A pencil icon in the Edit Filter column denotes that a filter is available for the event. Click on a pencil icon for an event. The Edit Filter dialog is displayed. A filter attribute has a formal name and a display name. Either name is displayed in the Edit Filter edit dialog
Create a filter condition by choosing an item from the Condition drop-down, an operator, and a value. Then click the add button. When you are finished adding conditions, click OK.
Optionally, under Users to Always Audit, specify a comma-separated list of users to audit events initiated by these users. Audit occurs regardless of the audit level or filters that have been specified. User names you enter in this field are not validated. Particular users, such as a system administrator, will generate audit traffic anytime that user executes any auditable events for any component.
Restart WebLogic Server on which the system component is running.
Task 9, Importing and Exporting Audit Policies for a System Component
Go to a system component home page. The table of audit categories relevant to the component is displayed in the Audit Policy Settings area.
At any time while editing a policy, do one of the following:
Click Export to save the current settings to a file
Click Import to load settings from a file
Use this section manage audit policies with WLST.
Connect to the WebLogic Server:
>java weblogic.WLST
>connect('userName', 'userPassword', 'url', 'adminServerName')
To view domain or Java component audit policies, use the getAuditPolicy command:
(view domain audit policies) wls:/mydomain/serverConfig> getAuditPolicy() (view component audit policies) wls:/mydomain/serverConfig> getAuditPolicy(componentType="JPS")
To view a system component audit policies:
Obtain the system component MBean name with the getNonJava EEAuditMBeanName command.
Use the getAuditPolicy command:
wls:/mydomain/serverConfig> getAuditPolicy (on="oracle.security.audit.test:type=CSAuditMBean,name=CSAuditProxyMBean")
Connect to WebLogic Server:
>java weblogic.WLST
>connect('userName', 'userPassword', 'url', 'adminServerName')
Go the hierarchy to access the domain of interest:
wls:/mydomain/serverConfig>
Use the setAuditPolicy command to update the audit policy configuration.
For system components use the setAuditPolicy command and include an MBean name to update the audit policy configuration. The name for an audit MBean has the following format:
oracle.as.management.mbeans.register:type=component.auditconfig,name=auditconfig1,instance=INSTANCE,component=COMPONENT_NAME
For example:
oracle.as.management.mbeans.register:type=component.auditconfig,name=auditconfig1,instance=instance1,component=oid1
For system components, such as Oracle HTTP Server or LDAPs, call save explicitly after issuing the setAuditPolicy or importAuditConfig commands.
The following example illustrates this step: navigating to the root proxy MBean in the tree, using the invoke command to call setAuditPolicy, and using the save command:
ORACLE_COMMON_HOME/common/bin/wlst.sh
connect('username', 'password', 'protocol://localhost:7001', 'localhost:7001')
custom()
cd('oracle.as.management.mbeans.register')
cd('oracle.as.management.mbeans.register:type=component,name=oid1,instance=instance1')
invoke('load',jarray.array([],java.lang.Object),jarray.array([],
java.lang.String))
setAuditPolicy(filterPreset='None',
on='oracle.as.management.mbeans.register:type=component.auditconfig,
name=auditconfig1,instance=instance1,component=oid1')
invoke('save',jarray.array([],java.lang.Object),jarray.array([],
java.lang.String))
Assume that the domain current policy audits a user named user1, and you want to add two names, user2 and user3, to the list of users who are always audited, and remove user1 from the list of users audited.
To accomplish these tasks, run the following command:
setAuditPolicy (filterPreset="None",addSpecialUsers="user2,user3",removeSpecialUsers="user1")
Assume that the domain current policy audits user logout events, and you would like to remove logout events and add audit login events.
To accomplish these tasks, run the following command:
setAuditPolicy (on="OHS mbean name")
(filterPreset="Custom",addCustomEvents="OHS:UserLogin",
removeCustomEvents="OHS:UserLogout")
Notice the Custom filter preset called to add and remove events.
When you configure audit at the custom audit level, and you subsequently use WLST to switch to a different (non-custom) audit level, the custom audit settings are retained unless you explicitly remove them.
The following sequence illustrates how changing the audit level affects audit data collection:
The custom audit level is set in a component's policy, and an audit filter is specified as part of the configuration.
At runtime, audit data is collected according to the filter.
The component's audit policy is then changed, for example, from the custom audit level to low with the setAuditPolicy command. The filter that was set up as part of the custom audit level remains in the audit configuration.
Thereafter, audit data is collected based on the low audit level.
The component's audit policy is changed back to the custom level, and an additional filter is added. This new filter is appended to the original filter. Unless the original filter is explicitly deleted, it remains part of the configuration.
Thereafter, audit data is collected based on both filters at the custom level.
OFM Audit Framework provides a set of interfaces that applications can use to retrieve and update audit policies. For information about policy management, see Section 22.4, "Managing Policies Programmatically."
Before Release 11.1.1.7.0, audit wrote out audit records using the application server's time zone. Starting with Release 11.1.1.7.0, audit and the server can use a different time zone. This means that:
New sites see audit events written in Coordinated Universal Time (UTC).
Sites that upgrade from release 11.1.1.6.0 continue, by default, to use the application server time zone for audit records unless you explicitly specify to use UTC.
Records in bus-stop files use UTC.
Audit Time Stamps at New Sites
Audit records in new installations use UTC time stamps. Use the audit.timezone property in the audit configuration to specify it:
<serviceInstance name="audit" provider="audit.provider" location="./audit-store.xml"> <property name="audit.filterPreset" value="None"/> <property name="audit.timezone" value="utc" /> <property name="audit.loader.repositoryType" value="File" /> <property name="auditstore.type" value="file"/> </serviceInstance>
Audit Time Stamps at Upgraded Sites
Audit records prior to release 11.1.1.7 used the application server time stamp. After upgrading to that release, the service configuration remains unchanged and, by default, the records are written using the application server time stamp.
If you wish to use the UTC after upgrading to 12c, then move the current records to avoid any potential inconsistencies and insert the audit.timezone service property in your configuration file.
OFM Audit Framework has several runtime components that log error messages. This framework provides a set of log files that you use to trace errors and to diagnose failures when OFM Audit Framework runs into exceptions.
Time stamps in the audit bus-stop files are recorded in Coordinated Universal Time. This may differ from the machine time depending on the machine's time zone setting.
This section explains the organization and administration of the audit schema in the following topics:
The tables in OFM Audit Framework schema includes:
Base data in a base table. This table contains the basic data for an audit record and is related to the component-specific tables with the IAU_ID attribute.
Common attributes in the IAU_COMMON table. This table contains the basic data for an audit record and is related to the custom tables with the IAU_ID attribute.
Generic attributes in dedicated tables.
Custom attributes in the IAU_CUSTOM_nnn tables.
Not all these tables are used at the same time. The dynamic model uses the common and custom tables. The static (older) model uses the base table and component-specific tables.
The audit loader stores two kinds of data records in tables:
General information (such as time, event type, and event status), stored in one row of the common table (dynamic model) or the base table.
Component-specific information, stored in one row of the custom table (dynamic model) or the component table.
The average audit record size is approximately 0.3 KB. Use this average when you plan to resize database tables, and in addition, monitor how your audit database size grows according to policies and level of activity.
The attributes of the base table are derived from the following file:
$ORACLE_HOME/modules/oracle.iau_12.2.1/components/generic/generic_events.xml
The attributes of the component table are derived from the following file:
$ORACLE_HOME/modules/oracle.iau_12.2.1/components/componentName/component_events.xml
Table C-6 lists the attributes defined in the IAU_BASE base table. Table C-7 lists the attributes defined in the IAU_COMMON common table.
To get a list of attribute names for individual component tables, use the listAuditEvents WLST command.
See also:
Section C.2, "The Audit Schema"
listAuditEvents in Oracle Fusion Middleware Infrastructure Security WLST Command Reference.
For efficient queries, an index is created by default for the IAU_TSTZORIGINATING column in the base table and for each of the component-specific tables.
The default index in IAU_BASE is EVENT_TIME_INDEX, and in component tables is tableName_INDEX (such as OVDCOMPONENT_INDEX, OIDCOMPONENT_INDEX, JPS_INDEX).
Additional columns and indexes in the common table are:
IAU_TSTZORIGINATING, indexed by DYN_EVENT_TIME_INDEX
IAU_AuditUser, indexed by DYN_USER_INDEX
IAU_ComponentType, indexed by DYN_COMPONENT_TYPE_INDEX
IAU_EventCategory, indexed by DYN_EVENT_CATEGORY_INDEX
IAU_EventType, indexed by DYN_EVENT_TYPE_INDEX
When planning the audit database backup, consider the following points.
Growth rate of audit events
Your audit policies determine the number of audit events the framework generates and the number of audit events generated daily determines how often you want to back up the store.
Compliance regulations
Consult you organization's compliance regulations to determine the frequency of backups and number of years for which audit data storage is mandatory.
Use Oracle Database Utility Recovery Manager (RMAN) to back up and recover an Oracle Database. Note that you need to back up the IAU_DISP_NAMES_TL translation table just once, because it typically does not change over time.
Import and export the audit schema to migrate data, for example, if you wish to combine several audit repositories into a single audit store, or if you wish to scale up the database. Use Oracle Data Pump to import and export data from an Oracle Database.
The framework provides the following SQL scripts to purge records from the audit store, in the directory $MW_HOME/oracle_common/common/sql/iau/scripts:
auditDataPurge.sql
auditDeleteData.sql
auditReclaimSpace.sql
To delete records without taking any other action, use auditDeleteData.sql. This script has the following syntax:
auditDeleteData.sql audit_schema_user number_of_days_to_keep
For example, to delete records older that 100 days:
sqlplus> @auditDeleteData.sql DEV_IAU 100
To reclaim space, use auditReclaimSpace.sql. This script has the following syntax:
auditReclaimSpace.sql audit_schema_user
To delete audit records and reclaim space, use auditDataPurge.sql. This script has the following syntax:
auditDataPurge.sql audit_schema_user number_of_days_to_keep
For example, to delete all records older than 100 days and enable row movements to shrink space:
sqlplus> @auditDataPurge.sql DEV_IAU 100
Not all database systems support partitioning, all the tables in the audit schema are not partitioned by default.
Because audit data grows over time, if you store a large volume of data, then consider partitioning the audit schema to allow for easier archiving.
Benefits of partitioning include:
Improved Performance: If a table is range-partitioned by time stamps, for example, then queries by time stamps can be processed on the partitions within that time frame only.
Better Manageability: Partitions can be created on separate tablespaces (thus different disks). This lets you move older data to slower and larger disks, while keeping newer data in faster and smaller disks.
In addition, partitioning makes archival much easier.
Increased Availability: If a single partition is unavailable, for example, and you know that your query can eliminate this partition from consideration, then the query can be processed without waiting for the unavailable partition to become available.
Partitioning tables allows you store individual partitions on different storage tiers. Typically, you create tablespaces in high-performance or low-cost disks, and create partitions in different tablespaces based on the value of the data or other criteria.
Oracle Information Lifecycle Management (ILM) features streamlined data management with partitioning and compression.
Database views enable you to run queries against audit records. Furthermore, you can create indexes on custom tables for their attributes with indexable views. We recommend that applications create a simple view first and switch to an indexable view later on when needed.
To create an indexable view:
Specify the event attributes in the component_events.xml file. In Release 12c (12.2.1) the new indexable attribute has been added to the AttributeType element.
Component_events.xml
<?xml version="1.0"?>
<AuditConfig xmlns="http://xmlns.oracle.com/ias/audit/audit-2.0.xsd">
<AuditComponent componentType="ApplicationAudit" major="1" minor="1">
<Attributes ns="accounting" version="1.0">
<Attribute name="TransactionType" displayName="Transaction Type" type="string" order="1" indexable="true">
<HelpText>Transaction type.</HelpText>
</Attribute>
<Attribute name="AccountNumber" displayName="Account Number" type="int" order="2">
<HelpText>Account number.</HelpText>
</Attribute>
<Attribute name="Date" displayName="Date" type="dateTime" order="3"/>
<Attribute name="Amount" displayName="Amount" type="float" order="4">
<HelpText>Transaction amount.</HelpText>
</Attribute>
<Attribute name="Status" displayName="Account Status" type="string" order="5" indexable="true">
<HelpText>Account status.</HelpText>
</Attribute>
</Attributes>
...
</AuditComponent>
</AuditConfig>
Create indexable views either at registration or after registration.
If at registration time, use any of the following:
Specify the opss.audit.iauview deployment parameter as INDEXABLE in weblogic-application.xml.
Pass the createView=INDEXABLE option to the registerAudit command.
Implement the AuditRegistrationExt interface and returning AuditRegistrationExt.TYPE.INDEXABLE from the getIAUViewSupportType method.
If after registration time, use any of the following:
Run the createIAUView command to switch to an INDEXABLE view.
Generate a SQL script with the createAuditDBView command, to which you specify an INDEXABLE view type. Then run the script as administrator.
If you change event definitions, then drop the associated materialized view before redeployment.
This section provides guidelines for managing audit configuration and maximizing the value of the collected audit data, in the following topics:
Ensure that all audit names conform to the following naming conventions:
Do not use any of the following characters in componentType, Category, Event, or Attribute names: !, @, ”, #, $, %, ’, (, ), *, +, comma, period, -, _, /, space, :, ;, <, =, >, ?, {, }, ~, ^.
The space character is allowed in display names only.
When you name audit events:
Do not prefix the event name with the component name.
Try to make names as specific as possible. For example, use HTTPResponse instead of Response when defining an HTTP response code.
Do not append the suffix Event to all event names. For example, instead of AuthenticationEvent, use Authentication.
To optimize the use of events:
Define separate events for each operation. For example, instead of defining the event Policy with attributes Delete and Create, define the separate events PolicyCreate and PolicyDelete.
Do not define separate events for the events success and failure. For example, do not define the separate events PolicyCreateSuccess and PolicyCreateFailure. Instead use the EventStatus attribute to record them.
To categorize events:
Refer system categories when applicable. For example, UserSession and Authorization.
For configuration operations, make a category around a group of operations. For example, put PolicyCreate, PolicyDelete in a component specific category called Policy.
When you define generic attributes:
Include the following event attributes:
Initiator - the user who performed the event action
MessageText - a short description of what happened.
EventStatus - the event outcome
FailureCode - the error code applicable to the failure.
Use the attribute Resource - the object that was affected, such as the accessed URI or the granted permission.
OFM Audit Framework considers the union of all common attributes in each event and defines a database column for each of them. So try to define as many common attributes as possible.
Define enough information so that events generated by your component can be cross linked to other events.
The component_events.xml file provides version support. If you decide to change the event definitions, make sure to delete any associated materialized view.