Writing audit logs in Common Event Format - PingAccess - 8.0

PingAccess

bundle
pingaccess-80
ft:publication_title
PingAccess
Product_Version_ce
PingAccess 8.0
category
Product
pa-80
pingaccess
ContentType_ce

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

To enable CEF:

  1. Edit the <PA_HOME>/conf/log4j2.xml file.
  2. Select a tab to continue.
    • 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.

Enabling the CEF format file

  1. 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:

    example
    
    <!-- ======================= -->
    <!-- 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.

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

    example
    <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

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

    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:

    example
    <!-- ======================= -->
    <!-- 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.
    Note:

    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.

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

    example
    
    <!--
    <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.
    Note:

    Only the TCP protocol supports failover.

  4. Save and close the file.