| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| 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. |
| --> |
| <!-- Generated by Apache Maven Doxia at 2018-12-02 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Log4j_Audit – Apache Log4j Audit - Apache Log4j Audit</title> |
| <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" /> |
| <link rel="stylesheet" href="./css/site.css" type="text/css" /> |
| <script type="text/javascript" src="./js/jquery.min.js"></script> |
| <script type="text/javascript" src="./js/bootstrap.min.js"></script> |
| <script type="text/javascript" src="./js/prettify.min.js"></script> |
| <script type="text/javascript" src="./js/site.js"></script> |
| <meta name="Date-Revision-yyyymmdd" content="20181202" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="composite"> |
| <a href="http://www.apache.org/events/current-event.html"> |
| <img class=logo-left src="http://www.apache.org/events/current-event-234x60.png"/> |
| </a> |
| <img class="logo-right" src="./images/logo.png" alt="Apache log4j logo" /> |
| <a href="https://logging.apache.org/"> |
| <img class="logo-center" src="./images/ls-logo.jpg" alt="Apache logging services logo" /> |
| </a> |
| <div class="clear"></div> |
| |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="brand" href="http://logging.apache.org/log4j-audit">Apache Log4j Audit ™</a> |
| <ul class="nav"> |
| <li> |
| |
| |
| <a href="https://cwiki.apache.org/confluence/display/LOGGING/Home" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://logging.apache.org/" class="external" target="_blank" title="Logging Services">Logging Services</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://github.com/apache/logging-log4j-audit" class="external" target="_blank" title="GitHub">GitHub</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container-fluid"> |
| <table class="layout-table"> |
| <tr> |
| <td class="sidebar"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-home"></i>Apache Log4j Audit™</li> |
| <li class="none active"> |
| <a href="index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="gettingStarted.html" title="Getting Started">Getting Started</a> |
| </li> |
| <li class="none"> |
| <a href="catalog.html" title="Audit Catalog">Audit Catalog</a> |
| </li> |
| <li class="none"> |
| <a href="requestContext.html" title="RequestContext">RequestContext</a> |
| </li> |
| <li class="none"> |
| <a href="sample.html" title="Sample Project">Sample Project</a> |
| </li> |
| <li class="none"> |
| <a href="changelog.html" title="Changelog">Changelog</a> |
| </li> |
| <li class="none"> |
| <a href="apidocs/index.html" title="Javadoc">Javadoc</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-pencil"></i>For Contributors</li> |
| <li class="none"> |
| <a href="build.html" title="Building Log4j Audit from Source">Building Log4j Audit from Source</a> |
| </li> |
| <li class="none"> |
| <a href="guidelines.html" title="Guidelines">Guidelines</a> |
| </li> |
| <li class="none"> |
| <a href="javastyle.html" title="Style Guide">Style Guide</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Component Reports</li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-api/index.html" title="Audit API">Audit API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-war/index.html" title="Audit Service">Audit Service</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-audit/log4j-audit-maven-plugin/index.html" title="Maven Plugin">Maven Plugin</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-api/index.html" title="Catalog API">Catalog API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-git/index.html" title="Git Catalog Access">Git Catalog Access</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-jpa/index.html" title="JPA Catalog Access">JPA Catalog Access</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-catalog/log4j-catalog-war/index.html" title="Catalog Editor">Catalog Editor</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li> |
| <li class="none"> |
| <a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a> |
| </li> |
| <li class="none"> |
| <a href="dependency-management.html" title="Dependency Management">Dependency Management</a> |
| </li> |
| <li class="none"> |
| <a href="team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="license.html" title="Project License">Project License</a> |
| </li> |
| <li class="none"> |
| <a href="source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| <li class="none"> |
| <a href="project-summary.html" title="Project Summary">Project Summary</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Project Reports</li> |
| <li class="none"> |
| <a href="changes-report.html" title="Changes Report">Changes Report</a> |
| </li> |
| <li class="none"> |
| <a href="jira-report.html" title="JIRA Report">JIRA Report</a> |
| </li> |
| <li class="none"> |
| <a href="rat-report.html" title="RAT Report">RAT Report</a> |
| </li> |
| </ul> |
| </div> |
| <div id="poweredBy"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/maven-feather.png" /> |
| </a> |
| </div> |
| </td> |
| <td class="content"> |
| <!-- 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. --><h1>Apache Log4j Audit</h1> |
| <div class="section"> |
| <h2><a name="What_is_Audit_Logging"></a>What is Audit Logging</h2> |
| <p>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.</p> |
| <div class="section"> |
| <h3><a name="What_is_the_difference_between_audit_logging_and_normal_logging"></a>What is the difference between audit logging and “normal” logging?</h3> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p></div></div> |
| <div class="section"> |
| <h2><a name="What_is_Log4j_Audit"></a>What is Log4j Audit?</h2> |
| <p>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.</p> |
| <p>Log4j Audit builds upon Log4j by defining its own AuditMessage. An AuditMessage is a container for <a class="externalLink" href="http://logging.apache.org/log4j/2.x/manual/messages.html">StructuredDataMessage</a>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.</p></div> |
| <div class="section"> |
| <h2><a name="Features"></a>Features</h2> |
| <p>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 <a href="gettingStarted.html">Getting Started</a> page provides a tutorial that explains how to define audit events for an application.</p> |
| <div class="section"> |
| <h3><a name="Audit_Event_Catalog"></a>Audit Event Catalog</h3> |
| <p>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.</p> |
| <p>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.</p></div> |
| <div class="section"> |
| <h3><a name="Dynamic_Event_Catalog"></a>Dynamic Event Catalog</h3> |
| <p>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.</p> |
| <p>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.</p></div> |
| <div class="section"> |
| <h3><a name="Audit_Service"></a>Audit Service</h3> |
| <p>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.</p></div> |
| <div class="section"> |
| <h3><a name="Sample_Project"></a>Sample Project</h3> |
| <p>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.</p></div></div> |
| <div class="section"> |
| <h2><a name="Requirements"></a>Requirements</h2> |
| <p>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.</p></div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| <div class="footer"> |
| <p>Copyright © 2016-2018 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Logging, Apache Log4j, Log4j, Apache Log4j Audit, Log4j Audit, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| <p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p> |
| </div> |
| </div> |
| </body> |
| </html> |
