Managing DirX Audit Server

This chapter provides information on how to manage the DirX Audit Server. It consists of the following sections:

  • About the DirX Audit Server Components

  • Running the DirX Audit Server Service

About the DirX Audit Server Components

DirX Audit Server (also called the Server) hosts the following component types:

  • Collectors to collect audit messages from audit sources.

  • Transformers to transform audit messages from their original data format to audit messages in the DirX Audit format.

  • A digest producer to generate audit events by calculating the digest fields for operation, type and detail.

  • A tag producer to generate message and event tags for each audit message and its audit events.

  • A Persistence Service Unit to write audit messages including audit events and tags into the relational database.

  • An error-handling unit to manage errors in collected audit messages.

  • A scheduler to run scheduled reports, context records calculation, history DB update, and fact population on a regular basis.

  • A scheduler to run purge jobs for history entries or audit messages.

  • A scheduler to run history synchronization and other jobs on a regular basis.

  • A RESTful API services to provide access for DirX Audit Manager to contents of DirX Audit Database and configuration.

A separate instance of DirX Audit Server is used for every tenant starting with version 7.2.

The collectors read audit messages from their specific audit source and pass them to the appropriate transformer. The transformed messages are then passed to the persistence unit, which adds them to the DirX Audit Database and creates the audit events and tags for each message. Messages that cannot be transformed or stored are passed to the error-handling unit, which stores the failed messages into files. These components are deployed in the form of Apache Camel components and routes.

For more details on these components and their configuration, see the chapters in this guide on database connectivity, collectors, digest and tag producers, fact population and error handling.

Running the DirX Audit Server Service

The DirX Audit Server is based on the Spring Boot technology. A separate instance of DirX Audit Server is used for every tenant starting with version 7.2.

To start and stop DirX Audit Server for a specific tenant, use the DirX Audit Server tenant_name (dirx-audit-server-tenantID on UNIX) service.

Also note that the server will immediately implement any changes in deployed packages and routes in the install_path/server_container/tenants/tenantID/deploy folder (for example, changes of the routes scheduler or deployed collectors) while changes in the server configuration (taken from install_path/conf/tenants/tenantID/configuration.cfg) will be implemented only after DirX Audit Server for a specific tenant is restarted.

The server also uses the JDBC driver file located in the install_path/lib folder. Microsoft JDBC Driver for SQL Server is provided with the standard DirX Audit installation. If you want to connect an Oracle Database, the Oracle JDBC driver should be placed in the install_path/lib folder for the DirX Audit Server, the DirX Audit Manager Classic and tools.
See the section "Oracle Database JDBC Driver Installation" in the "Installation Configurations" in the DirX Audit Installation Guide for instructions on how to install it.

See the DirX Audit Release Notes for more information about supported drivers.

Also see the sections "Server Scheduled Jobs" and "Application Container Configuration" in "Configuring DirX Audit" in the DirX Audit Installation Guide for further configuration details.

REST API

REST API is published at base URI: https://hostname:port/Tenants/tenantID/api/audit/

Rest API provides access for DirX Audit Manager to contents of installed databases, security context and installation information.

  • Core REST API

    Provides information about logged-in user and method to remove security context of the user when logging out.

  • Configuration REST API

    Provides information about DirX Audit configuration, such as licensed components.

  • I18n REST API

    Provides access to internationalization (i18n) resources, such as language bundles and assets.

  • Data Database REST API

    Provides access to Data Database content - Audit Messages and Audit Events.

  • Configuration Database REST API

    Provides access to Configuration Database content - Audit Analysis Views, History Views, Reports and Reports components.

  • History Database REST API

    Provides access to History Database content. This API is only available with valid History database license.

Access to the REST API

To access REST API via Swagger UI see more details in the section "Using Swagger UI" in chapter "Managing DirX Audit Manager and REST API" of this guide.

Swagger and OpenAPI endpoints are available without logging in. So are GET methods of I18n REST API. To access the rest of the endpoints, user needs to be authenticated using one of provided authentication methods. User needs to have appropriate permissions to access all endpoints apart from the ones mentioned before.

Required Audit roles are Audit Administrator, Auditor and Restricted Auditor. Users with roles Audit Administrator and Auditor have access to all endpoints. Restricted Auditor has access only to endpoints of Core and Configuration Reports REST APIs.

Provided authentication methods are:

  • Basic authentication against LDAP server with session management enabled

    Basic authentication is only used when user is being logged in. During login, session is created which is used for the rest of the requests. Session validity is time restricted. See more in section "Session management" below.

  • oAuth2 with OIDC

    When using DirX Audit Manager or Swagger UI to log in, user is redirected to the OIDC authorization server to be authenticated. After successful authentication, user is redirected back.

Session management

For managing sessions, default Spring framework session management is used. When user is authenticated and authorized, a session is created and stored in embedded Tomcat container. JSESSIONID cookie is also created and sent to the client for future use. Default idle validity of session is 1 hour and maximum age of session is 10 hours. This can be configured in the Tenant Configurator. See the section "REST Service Authentication Configuration" in the Tenant Configuration in the chapter "Configuring DirX Audit" in the DirX Audit Installation Guide for details.

History REST API

History REST API is only available in installation with valid History DB license.

Pagination

Pagination is realised using SCIM standard. On query, the response body contains number of total results, number of items per page and start index. Certain page and size of it can be set when querying the endpoint. If not set, default values are used. Default page size is 1000 and default start index is 1.

Caching

Endpoints which load big data sets (such as Audit Messages or Audit Events) cache the results for a limited time. Entries are held in cache for a maximum period of 24 hours. Some entries, like Related Events in Audit Messages endpoints are stored in cache based on interval of context records job. Job calculating context records runs by default every 5 minutes, therefore the data may change and so Related Events are stored in cache only for 5 minutes.

Caching can be disabled globally in DirX Audit Configurator (See "REST Service Configuration" in the Tenant Configuration in the chapter "Configuring DirX Audit" in the DirX Audit Installation Guide for details.) or locally as endpoint parameter.