PingAccess

Writing audit logs in Common Event Format

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

About this task

To enable CEF:

Steps

  1. Edit the <PA_HOME>/conf/log4j2.xml file.

  2. Select a tab to continue.

    Choose from:

    • If you have a server that supports rsyslog, use the CEF syslog appender tab.

    • If your server does not support rsyslog, use the CEF file tab.

  • CEF file

  • CEF syslog appender

Enabling the CEF format file

Steps

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

    Example:

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

    Code 
    <!-- ======================= -->
<!-- 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 this with the EngineAuditLogToCEF-FILE, AgentAuditLogToCEF-FILE, SidebandClientAuditLogToCEF-FILE, and SidebandAuditLogToCEF-FILE appender references.

  2. Uncomment the RollingFile preset appender configurations in the Api Audit log : CEF format file, Engine Audit log : CEF format file, Agent Audit log : CEF format file, SidebandClient Audit log : CEF format file, and Sideband Audit log : CEF format file sections.

    Example:

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

    Code 
    <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 this with the EngineAuditLogToCEF-FILE, AgentAuditLogToCEF-FILE, SidebandClientAuditLogToCEF-FILE, and SidebandAuditLogToCEF-FILE appender configurations.

  3. Save and close the file.

Enabling the CEF formatted syslog appender

Steps

  1. Uncomment the syslog failover appender references in the apiaudit, engineaudit, agentaudit, sidebandclientaudit, and sidebandaudit sections.

    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:

    Code 
    <!-- ======================= -->
<!-- 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 this with the <AppenderRef ref="EngineAuditLogToCEF-Syslog-Failover"/>, <AppenderRef ref="AgentAuditLogToCEF-Syslog-Failover"/>, <AppenderRef ref="SidebandClientAuditLogToCEF-Syslog-Failover"/>, and <AppenderRef ref="SidebandAuditLogToCEF-Syslog-Failover"/> appender references.

  2. Uncomment the Socket appender configurations in the 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, and Sideband Audit log : CEF Formatted syslog appender sections.

    Each Socket appender is followed by two related appenders, RollingFile and 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, make sure to uncomment the related appenders also.

    Example:

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

    Code 
    <!--
<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 with the EngineAuditLogToCEF-Syslog, AgentAuditLogToCEF-Syslog, SidebandClientAuditLogToCEF-Syslog, and SidebandAuditLogToCEF-Syslog appenders.

  3. 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.

  4. Save and close the file.