<!-- vim: set syn=markdown : -->
<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
#set($h1='#')
#set($h2='##')
#set($h3='###')

$h1 Apache Log4j Audit

$h2 What is Audit Logging

The basic purpose of audit logging is to provide the information to determine what actions have been performed, or
attempted to be performed, by whom, when they did it and what the data associated with the action was. Audit log
data is most typically used by security teams to monitor for fraud or illegal or otherwise unauthorized activities
and to be able to correct changes that were incorrectly made. Audit logs are often used to demonstrate compliance
with legal obligations such as Sarbanes-Oxley or HIPPA.

$h3 What is the difference between audit logging and "normal" logging?

In a typical application developers add logging statements at key points to help diagnose problems or to
document unexpected occurances, such as a failure to communicate with a key service. These are normally referred
to as diagnostic logs. Diagnostic logs are critical in maintaining the servicability of the application
but generally aren't very useful in helping to determine who made a particular change and when it was done.
On the other hand, audit logs focus on identifying when a change was made, who made it, and what data elements were
changed. While audit logs can sometimes help in troubleshooting problems, that isn't their primary purpose just as
the primary purpose of diagnostic logging is not to record actions taken by people using the system.

A key difference between diagnostic logs and audit logs is that while diagnostic logs are generally free form
with the content left up to the developer, audit logs usually contain the action being performed and the data
elements that have been impacted. In many systems audit logs are written to a database where the values for these
elements may be written to specific columns. In recent times it is more common to see audit logs written to NoSQL
data stores where they can be efficiently queried.

Another key difference is that audit logs are often used to generate reports that are of value to several parts of
the organization. For example, an auditor at a bank might be interested in locating all the accounts with more than
3 failed login attempts the prior day, or all the transfers for more than $10,000.00. A customer service representative
might want to watch the audit events for a specific user while they are on the phone with them troubleshooting a problem.
Generally, diagnostic logs do not provide the information to support these use cases while audit logs do.

Finally, diagnostic logs and audit logs differ in that diagnostic logs typically are categorized via "levels"
while audit logs are not. Diagnostic logging typically includes fairly detailed logging of the internals of the system
via debug level messages. Other messages may be classified as informational or, in response to some kind of an
error, a warning or error log message may be generated.  In contrast to this, audit logs are usually always logged
so a level is meaningless.

While audit logs and diagnostic logs may differ in their format and usage, Log4j can still play a part in delivering
both. Unlike systems where audit logs are written directly to a database, the use of Log4j and Log4j-Audit allows
applications to be written to perform audit logging without any knowledge of where those will end up and what they will
be used for. Furthermore, the log events can be easily transformed into various formats that best matches their
intended uses.

$h2 What is Log4j Audit?

Log4j Audit provides a framework for defining audit events and then logging them using Log4j. The framework focuses on
defining the events and providing an easy mechanism for applications to log them, allowing products to provide
consistency and validity to the events that are logged. It does not focus on how the log events are written to a
data store. Log4j itself provides many options for that.

Log4j Audit builds upon Log4j by defining its own AuditMessage. An AuditMessage is a container for
[StructuredDataMessage](http://logging.apache.org/log4j/2.x/manual/messages.html)s which allows a log message to be
generated that contains a set of keys and values. The AuditMessage passes through Log4j as any other log event
would.

$h2 Features

Each application has its own events that need to be audited. Before using Log4j Audit, application owners need to define
the AuditMessages that capture the exact attributes of that need to be captured. The [Getting Started](gettingStarted.html) page
provides a tutorial that explains how to define audit events for an application.

$h3 Audit Event Catalog

Once audit events are defined, they need to be maintained: as the application evolves, developers will inevitably
discover they need to add, remove or change attributes of the audit events. Log4j Audit can persist the audit event
definitions in a JSON file. This file becomes the Audit Event Catalog for the application. Log4j Audit is designed
to store the event definition file in a Git repository so that the evolution of the audit events themselves have an
audit trail in the Git history of the file. Log4j Audit provides a web interface for editing the events.

Log4j Audit uses a catalog of events to determine what events can be logged and to validate the events. Java
interfaces are generated from the catalog for applications to use when generating the audit events. A web UI
is provided to edit and manage the catalog but the UI requires a specific user's Git credentials and
so is best run on the local user's computer.

$h3 Dynamic Event Catalog

The typical event catalog is considered static. It is defined during the development process and cannot be changed in
a running system without a new release.

In addition to the catalog that is managed by the web UI a set of dynamic catalogs can also be used. These catalogs
can be used by multi-tenant applications where each tenant has a different set of events and/or attributes that need
to be logged. The dynamic events are defined while the application is running and because they are specific to a
tenant in the running system. Because they are dynamic they are maintained in a database. Changes to the dynamic
catalog do not affect the static catalog. Changes to the dynamic catalog are performed using the audit service's REST
API.

$h3 Audit Service

Non-Java applications can perform audit logging by generating the event data and passing it to an auditing service
where the events will be validated and logged.

$h3 Sample Project

Users of Log4j Audit must provide a Git repository where the audit events will reside which will be used to generate
the Java event interfaces. Log4j Audit provides a sample project that contains a sample catalog file and creates
the Java interfaces from that file. The project also contains a module that generates a war file containing the
editor for that catalog as well as the REST endpoints to manipulate the dynamic catalogs.

$h2 Requirements

Log4j Audit requires Java 8 and Log4j 2.10.0 or greater.
A Git repo to maintain the JSON catalog of events and attributes is required.
A database is required if the application wants to define dynamic catalog events and attributes. Log4j Audit provides
built in support for PostgresQL.