| <!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 – The Apache Log4j Audit Catalog - 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"> |
| <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 active"> |
| <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>The Apache Log4j Audit Catalog</h1> |
| <p>Log4j-Audit uses a Catalog that describes the attributes and events that can be logged. The catalog is required to generate the audit events and to validate events being logged.</p> |
| <div class="section"> |
| <h2><a name="The_Catalog_and_Catalog_Editor"></a>The Catalog and Catalog Editor</h2> |
| <p>Log4j Audit provides an AuditCatalog WAR that can be deployed to a servlet container for use in creating and maintaining the catalog. Because the Catalog Editor requires the credentials to be configured on the machine where the web application is running and it performs no other authentication of the user, it is recommended that the Catalog Editor be run locally on the user’s machine.</p> |
| <p>The catalog provides screens to maintain the attributes, events, products, and categories defined in the catalog. Changes made to these entities are stored in an in-memory database until the user elects to persist them, at which time the catalog is exported as JSON and stored into the configured git repository.</p> |
| <p>Because the editor can only edit the default catalog and the persistant storage is the JSON file in the Git repository, the Catalog Editor is configured to only use the in memory database.</p> |
| <div class="section"> |
| <h3><a name="Attributes"></a>Attributes</h3> |
| <p>Attributes are the discrete data elements to be captured in audit events. One of the goals of the audit catalog is to avoid having what are essentially the same attributes with different names in various events. When creating new events users are highly encouraged to scan the existing attributes for one that is already present.</p> |
| <p>Attributes can have aliases and examples, however the Catalog Editor provides no way to edit these and Log4j Audit currently doesn’t do anything with these fields.</p> |
| <p>The attribute edit screen allows attributes to be defined, modified or deleted. The fields that may be modified are: </p> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <th>Field</th> |
| <th>Description</th></tr> |
| <tr class="b"> |
| <td>Name</td> |
| <td>The name of the attribute as it will be known to Java. It is expected to be defined in camelCase.</td></tr> |
| <tr class="a"> |
| <td>Display Name</td> |
| <td>The text that should be used to display the field in an application</td></tr> |
| <tr class="b"> |
| <td>Description</td> |
| <td>The description of the attribute as it would appear in help text in a UI.</td></tr> |
| <tr class="a"> |
| <td>Data Type</td> |
| <td>The type of data contained in the field. Must be one of BIG_DECIMAL, BOOLEAN, DOUBLE, FLOAT, INT, LIST, LONG, MAP, STRING</td></tr> |
| <tr class="b"> |
| <td>Indexed</td> |
| <td>True if this field should be indexed when stored in a database.</td></tr> |
| <tr class="a"> |
| <td>Sortable</td> |
| <td>True if this field should be sortable when displayed in a UI.</td></tr> |
| <tr class="b"> |
| <td>Required</td> |
| <td>True if this field is required by default</td></tr> |
| <tr class="a"> |
| <td>Request Context</td> |
| <td>True if this attribute is provided in the RequestContext</td></tr> |
| <tr class="b"> |
| <td>Constraints</td> |
| <td>Rules to use to validate the value. Must be null or one of ANYCASEENUM, ENUM, MAXLENGTH, MAXVALUE, MINLENGTH, MINVALUE, PATTERN</td></tr> </table> |
| <div class="section"> |
| <h4><a name="Data_Types"></a>Data Types</h4> |
| <p>An attribute must be defined as being one of the supported data types. Log4j Audit will use this information when generating the event Interfaces. By doing so, the data being logged will be guaranteed to be of the correct type at compile time. When logging using the Audit Service the data will be validated for the correct type when the event is received.</p></div> |
| <div class="section"> |
| <h4><a name="Constraints"></a>Constraints</h4> |
| <p>If a constraint is present on an attribute definition Log4j Audit will validate the value when the event is logged. The enum types must provide a list of valid values. The min and max constraints must be configured with an appropriate value. The pattern constraints must be configured with a regular expression to apply against the value. If the data fails to validate against a constraint the attempt to audit the event will fail. Using constraints can prevent garbage data from being included in the audit database but at the cost of potentially having auditing fail.</p> |
| <p><img src="images/attributes.png" alt="Attribute Editor" /></p></div></div> |
| <div class="section"> |
| <h3><a name="Events"></a>Events</h3> |
| <p>Events represent the aggregation of attributes to be collected when a specific action is performed. Event names should identify what action took place and the associated attributes should identify the key characteristics of who performed the action and what they did.</p> |
| <p>Events can have aliases, however the Catalog UI provides no way to edit them and Log4j Audit currently doesn’t do anything with alias fields.</p> |
| <p>The event edit screen allows events to be defined, modified, or deleted. The fields that may be modified are: </p> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <th>Field</th> |
| <th>Description</th></tr> |
| <tr class="b"> |
| <td>Name</td> |
| <td>The name of the event as it will be known in the catalog. It is expected to be defined in camelCase.</td></tr> |
| <tr class="a"> |
| <td>Display Name</td> |
| <td>The text that should be used to display the name of the event in an application</td></tr> |
| <tr class="b"> |
| <td>Description</td> |
| <td>The description of the event as it would appear in help text in a UI.</td></tr> |
| <tr class="a"> |
| <td>Assigned Attributes</td> |
| <td>The attributes to be associated with this event and whether they are required.</td></tr> </table> |
| <p>RequestContext attributes are always part of audit events whether they are declared or not. Specifying a non-RequestContext attribute is required for it to be associated with an event. Specifying a value of True or False for whether the attribute is required to be present will override whatever definition was present when the attribute was defined. If neither box is checked the attribute definition’s required attribute will be honored.</p> |
| <p><img src="images/events.png" alt="Event Editor" /></p></div> |
| <div class="section"> |
| <h3><a name="Products_and_Categories"></a>Products and Categories</h3> |
| <p>Events may be grouped into products and categories, however it is not required that an event be included in a product or category. Log4j Audit doesn’t use the products or categories itself, however UI tools that display audit events may choose to filter based on products or categories.</p></div></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> |
