Writing audit logs in Common Event Format

You can configure PingAccess to write any of its five audit logs in Common Event Format (CEF).

To enable CEF, edit the <PA_HOME>/conf/log4j2.xml file in one of the following ways:

If you have a server that supports rsyslog, enable the CEF formatted syslog appender.
If your server does not support rsyslog, enable the CEF format file.

Enable the CEF formatted syslog appender

Uncomment the syslog failover appender references in the following sections:

apiaudit
engineaudit
agentaudit
sidebandclientaudit

sidebandaudit

For example, in the Audit log configuration section of the log4j2.xml file, go to the apiaudit logger configuration and uncomment the <AppenderRef ref="ApiAuditLogToCEF-Syslog-Failover"/> appender reference:

<!-- ======================= -->
<!-- Audit log configuration -->
<!-- ======================= -->
<Logger name="apiaudit" level="${sys:pa.log.level.apiaudit:-INFO}" additivity="false">
   <AppenderRef ref="APIAuditLog-File"/>
   <!--<AppenderRef ref="ApiAuditLog-Database-Failover"/>-->
   <!--<AppenderRef ref="ApiAuditLog-SQLServer-Database-Failover"/>-->
   <!--<AppenderRef ref="ApiAuditLog-PostgreSQL"/>-->
   <!--<AppenderRef ref="ApiAudit2Splunk"/>-->
   <!--<AppenderRef ref="ApiAuditLog-HarFile"/>-->
   <!--<AppenderRef ref="ApiAuditLogToCEF-File"/>-->
   <AppenderRef ref="ApiAuditLogToCEF-Syslog-Failover"/>
</Logger>

Repeat Step 1 for the following appender references:
- <AppenderRef ref="EngineAuditLogToCEF-Syslog-Failover"/>
- <AppenderRef ref="AgentAuditLogToCEF-Syslog-Failover"/>
- <AppenderRef ref="SidebandClientAuditLogToCEF-Syslog-Failover"/>
- <AppenderRef ref="SidebandAuditLogToCEF-Syslog-Failover"/>

Uncomment the Socket appender configurations in the following sections:

Api Audit log : CEF Formatted syslog appender
Engine Audit log : CEF Formatted syslog appender
Agent Audit log : CEF Formatted syslog appender
SidebandClient Audit log : CEF Formatted syslog appender
Sideband Audit log : CEF Formatted syslog appender

Each Socket appender is followed by two related appenders:

RollingFile
PingFailover

Together, they create a running audit-cef-syslog-failover.log file in the <PA_HOME>/log/pingaccess.log directory, if CEF logging fails for any reason. If you uncomment the Socket appenders, you must also uncomment the related appenders.

For example, in the Api Audit log : CEF Formatted syslog appender section, uncomment the ApiAuditLogToCEF-Syslog Socket appender configuration:

<!--
<Socket name="ApiAuditLogToCEF-Syslog" host="{syslog.host}" port="{syslog.port}" protocol="{syslog.protocol}" ignoreExceptions="false">
   <PingSyslogLayout>
      <PatternLayout>
         <pattern>%escape{CEF}{CEF:0|Ping Identity|PingAccess|%X{AUDIT.paVersion}|%X{exchangeId}|API_AccessEvent|0|rt=%d{ISO8601} msg=%X{AUDIT.responseCode} duid=%X{AUDIT.subject} src=%X{AUDIT.client} requestMethod=%X{AUDIT.method} request=%X{AUDIT.requestUri} cs1Label=AuthenticationMechanism cs1=%X{AUDIT.authMech} cs2Label=RoundTripMS cs2=%X{AUDIT.roundTripMS} externalId=%X{AUDIT.trackingId} %n}</pattern>
      </PatternLayout>
   </PingSyslogLayout>
</Socket>

<RollingFile name="ApiAuditLogToCEF-Syslog-FILE"
fileName="${sys:pa.home}/log/pingaccess_api_audit_cef_syslog_failover.log"
filePattern="${sys:pa.home}/log/pingaccess_api_audit_cef_syslog_failover.%d{yyyy-MM-dd}.log"
ignoreExceptions="false">
   <PatternLayout>
      <pattern>%escape{CEF}{CEF:0|Ping Identity|PingAccess|%X{AUDIT.paVersion}|%X{exchangeId}|API_AccessEvent|0|rt=%d{ISO8601} msg=%X{AUDIT.responseCode} duid=%X{AUDIT.subject} src=%X{AUDIT.client} requestMethod=%X{AUDIT.method} request=%X{AUDIT.requestUri} cs1Label=AuthenticationMechanism cs1=%X{AUDIT.authMech} cs2Label=RoundTripMS cs2=%X{AUDIT.roundTripMS} externalId=%X{AUDIT.trackingId} %n}</pattern>
   </PatternLayout>
   <Policies>
      <TimeBasedTriggeringPolicy />
   </Policies>
</RollingFile>

<PingAccessFailover name="ApiAuditLogToCEF-Syslog-Failover" primary="ApiAuditLogToCEF-Syslog" error="File">
   <Failovers>
      <AppenderRef ref="ApiAuditLogToCEF-Syslog-FILE" />
   </Failovers>
</PingAccessFailover>
-->

Repeat this step for the following appenders:

EngineAuditLogToCEF-Syslog
AgentAuditLogToCEF-Syslog
SidebandClientAuditLogToCEF-Syslog
SidebandAuditLogToCEF-Syslog

In the ApiAuditToCEF-Syslog, EngineAuditToCEF-Syslog, AgentAuditToCEF-Syslog, SidebandClientAuditToCEF-Syslog, and SidebandAuditToCEF-Syslog Socket appenders, replace the following placeholder parameter values:

syslog.host

The URL of your syslog host server.

syslog.port

The port that your syslog host server uses.

syslog.protocol

The protocol that your syslog host server uses. Valid values are UDP or TCP.

Only the TCP protocol supports failover.
Save and close the file.

Enable the CEF format file

Uncomment the CEF file appender references in the apiaudit, engineaudit, agentaudit, sidebandclientaudit, and sidebandaudit logger configurations.

In the Audit log configuration section of the log4j2.xml file, go to the apiaudit logger configuration and uncomment the ApiAuditLogToCEF-FILE appender reference:

<!-- ======================= -->
<!-- Audit log configuration -->
<!-- ======================= -->
<Logger name="apiaudit" level="${sys:pa.log.level.apiaudit:-INFO}" additivity="false">
   <AppenderRef ref="APIAuditLog-File"/>
   <!--<AppenderRef ref="ApiAuditLog-Database-Failover"/>-->
   <!--<AppenderRef ref="ApiAuditLog-SQLServer-Database-Failover"/>-->
   <!--<AppenderRef ref="ApiAuditLog-PostgreSQL"/>-->
   <!--<AppenderRef ref="ApiAudit2Splunk"/>-->
   <!--<AppenderRef ref="ApiAuditLog-HarFile"/>-->
    [.b]**<AppenderRef ref="ApiAuditLogToCEF-File"/>**
   <!--<AppenderRef ref="ApiAuditLogToCEF-Syslog-Failover"/>-->
</Logger>

Repeat Step 1 for the following appender references:
- EngineAuditLogToCEF-FILE
- AgentAuditLogToCEF-FILE
- SidebandClientAuditLogToCEF-FILE
- SidebandAuditLogToCEF-FILE

Uncomment the RollingFile preset appender configurations in the following sections:

Api Audit log : CEF format file
Engine Audit log : CEF format file
Agent Audit log : CEF format file
SidebandClient Audit log : CEF format file

Sideband Audit log : CEF format file

For example, in the Api Audit log : CEF format file section, uncomment the ApiAuditLogToCEF-FILE RollingFile preset appender configuration:

<RollingFile name="ApiAuditLogToCEF-File"
             fileName="${sys:pa.home}/log/pingaccess_api_audit_cef.log"
             filePattern="${sys:pa.home}/log/pingaccess_api_audit_cef.%d{yyyy-MM-dd}.log" >
   <PatternLayout>
      <pattern>%escape{CEF}{CEF:0|Ping Identity|PingAccess|%X{AUDIT.paVersion}|%X{exchangeId}|API_AccessEvent|0|rt=%d{ISO8601} msg=%X{AUDIT.responseCode} duid=%X{AUDIT.subject} src=%X{AUDIT.client} requestMethod=%X{AUDIT.method} request=%X{AUDIT.requestUri} cs1Label=AuthenticationMechanism cs1=%X{AUDIT.authMech} cs2Label=RoundTripMS cs2=%X{AUDIT.roundTripMS} externalId=%X{AUDIT.trackingId} %n}</pattern>
   </PatternLayout>
   <Policies>
<TimeBasedTriggeringPolicy />
   </Policies>
</RollingFile>

Repeat the previous step for the following appender configurations:
- EngineAuditLogToCEF-FILE
- AgentAuditLogToCEF-FILE
- SidebandClientAuditLogToCEF-FILE
- SidebandAuditLogToCEF-FILE
Save and close the file.