{"id":16376253,"url":"https://github.com/decebals/auditor","last_synced_at":"2025-04-10T01:49:12.458Z","repository":{"id":57742630,"uuid":"115276927","full_name":"decebals/auditor","owner":"decebals","description":"Auditing micro framework for Java","archived":false,"fork":false,"pushed_at":"2018-01-10T17:00:38.000Z","size":50,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-15T17:45:57.689Z","etag":null,"topics":["auditing","java"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decebals.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"auditor-core/pom.xml","citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-24T17:06:02.000Z","updated_at":"2023-08-23T00:19:59.000Z","dependencies_parsed_at":"2022-09-09T09:11:06.777Z","dependency_job_id":null,"html_url":"https://github.com/decebals/auditor","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decebals%2Fauditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decebals%2Fauditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decebals%2Fauditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decebals%2Fauditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decebals","download_url":"https://codeload.github.com/decebals/auditor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248142731,"owners_count":21054667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auditing","java"],"created_at":"2024-10-11T03:24:06.714Z","updated_at":"2025-04-10T01:49:12.439Z","avatar_url":"https://github.com/decebals.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Auditing micro framework for Java\n=====================\n[![Travis CI Build Status](https://travis-ci.org/decebals/auditor.png)](https://travis-ci.org/decebals/auditor)\n[![Maven Central](http://img.shields.io/maven-central/v/ro.fortsoft.auditor/auditor-parent.svg)](http://search.maven.org/#search|ga|1|ro.fortsoft.auditor)\n\nThe goal of this project is to create a tiny auditing micro framework that could be very easy to understand and hack.\n \nFeatures/Benefits\n-------------------\nWith Auditor you can easily create audit information (events) for your application.  \nAuditor is an open source (Apache license) lightweight auditing framework for Java, with no dependencies (in `core` module) and very extensible.   \nI recommend you to use this library in small and medium applications. \n\nIf you need something more powerful, please take a look at the excellent [Audit4J](http://audit4j.org) library.\n\nWhy I created Auditor and I didn't use Audit4J?  \nFirst of all, Audit4J is excellent but it's a little heavy (with maybe to many dependencies) for my taste.\nIn a [comment](https://github.com/audit4j/audit4j-core/issues/62), the man behind Audit4J says:\n\u003e From the initial stage, audit4j is designed for the enterprise applications and we haven't designed audit4j for embedded systems. \nInitially we used ActiveMQ to handle audit events asynchronously but It's not the suitable mechanism when we consider the throughput since we had the requirement to process 25000 TP. After several considerations and evaluations we redesigned the Audit4j and used reactor for asynchronous processing.\nCurrently audit4j is built around reactor and various streams.\n  \nIn my projects I already use Log4J for auditing, so my idea is to use the Log4J ecosystem for auditing.   \nSo, I created an Log4J based auditor (`Log4jAuditor` class), and I improved the Log4J's pattern layout (`AuditPatternLayout` class) with an implementation capable of capturing audit event details.  \nI don't want to reinvent things (file rolling, layout patterns, different kind of storages, ...) so I will let the Log4J's ecosystem to work for me.   \nLog4J comes with a huge number of appender implementations (async, database, ...), so anytime I can choose the implementation that I need it.\nIn conclusion the performance of Auditor is dictated by the performance of the Log4J's appender implementation.    \n\nFor people that don't want to use Log4J based auditor implementation and want something small, \nthis library comes with some common auditor implementations like [ConsoleAuditor](https://github.com/decebals/auditor/blob/master/auditor-core/src/main/java/ro/fortsoft/auditor/ConsoleAuditor.java), \n[FileAuditor](https://github.com/decebals/auditor/blob/master/auditor-core/src/main/java/ro/fortsoft/auditor/FileAuditor.java) \nand [AsyncFileAuditor](https://github.com/decebals/auditor/blob/master/auditor-core/src/main/java/ro/fortsoft/auditor/AsyncFileAuditor.java).  \n\nComponents\n-------------------\n- **Auditor** represents the entry point. The auditing implementation may use any appropriate medium and format to store audit events.\n- **AuditEvent** provides information about an auditing event.\n- **AuditEventFormatter** represents the formatter interface for audit event. It transforms an audit event to a String. \n\nArtifacts\n-------------------\n- Auditor Core `auditor-core` (jar)\n- Auditor Log4J `auditor-log4j` (jar)\n\nUsing Maven\n-------------------\nIn your pom.xml you must define the dependencies to Auditor artifacts with:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ero.fortsoft.auditor\u003c/groupId\u003e\n    \u003cartifactId\u003eauditor-core\u003c/artifactId\u003e\n    \u003cversion\u003e${auditor.version}\u003c/version\u003e\n\u003c/dependency\u003e    \n```\n\nwhere ${auditor.version} is the last Auditor version.\n\nYou may want to check for the latest released version using [Maven Search](http://search.maven.org/#search%7Cga%7C1%7Cro.fortsoft.auditor).\n\nAlso you can use the latest SNAPSHOT via the Sonatype Maven Repository. For this, you must add above lines in your `pom.xml`:\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003esonatype-nexus-snapshots\u003c/id\u003e\n        \u003curl\u003ehttps://oss.sonatype.org/content/repositories/snapshots\u003c/url\u003e\n        \u003creleases\u003e\n            \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/releases\u003e\n        \u003csnapshots\u003e\n            \u003cenabled\u003etrue\u003c/enabled\u003e\n        \u003c/snapshots\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\nHow to use\n-------------------\nIt's very simple to add Auditor in your application:\n\n```java\npublic class MyBusinessClass {\n\n\n    private Auditor auditor = new Log4jAuditor(\"audit\"); // or inject  \n    \n    public void bussinesMethod() {\n        // business\n        ...\n        \n        // add audit event\n        auditor.audit(new AuditEvent(\"Login\").setUsername(\"decebal1\").setSession(getUUID()).setIp(\"localhost\"));\n    }\n\n}\n```\n\nInternally, `Log4jAuditor`, when receive a `AuditEvent`, it transforms the audit event in a Log4j's [LoggingEvent](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/spi/LoggingEvent.html) and append the logging event to the all appenders assigned to the audit logger.\nBefore passing the logging event to appenders, `Log4jAuditor` tries to extract information like `username`, `session` and `ip` from [MDC](https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/MDC.html) if this information is missing from the audit event.\nSo, you can put this information somewhere in your code (for example a servlet filter):\n```java\nMDC.put(\"username\", username);\nMDC.put(\"session\", sessionId);\nMDC.put(\"ip\", hostname);\n```\n\nand create the audit event with a more short line:\n```java\nauditor.audit(new AuditEvent(\"Login\"));\n```\n \nSure, you can use any out of the box Auditor implementation or create your custom Auditor implementation, but if you use Log4J in your project for logging (like me) I suggest you to use `Log4jAuditor` (from `auditor-log4j`, so don't forget to add it to your project as dependency).  \n  \nI will give you addition information about how to use `Log4jAuditor` in your project.  \nFirst of all add a [log4j.properties](https://github.com/decebals/auditor/blob/master/auditor-log4j/src/test/resources/log4j.properties) file to your project.  \n\nTo use auditor you should add (in your log4j.properties) the logger:\n```\n#\n# Loggers\n#\nlog4j.logger.audit=INFO, file\n``` \n\nand the appender:\n```\nlog4j.appender.file=org.apache.log4j.RollingFileAppender\nlog4j.appender.file.File=./logs/audit.log\nlog4j.appender.file.MaxFileSize=1MB\nlog4j.appender.file.MaxBackupIndex=10\nlog4j.appender.file.layout=ro.fortsoft.auditor.log4j.AuditPatternLayout\nlog4j.appender.file.layout.ConversionPattern=[%d{MM/dd/yyyy HH:mm:ss}] %-5p %U %S %H %m%n\n```\n \nIn appender is useful to add `AuditPatternLayout` pattern layout (penultimate line).\nAvailable patterns:\n- [%U] - username\n- [%S] - session\n- [%H] - host name/address  \n \nNow if you run your application, in `./logs/audit.log` you will see something like:\n```java\n[12/24/2017 02:00:06] INFO decebal1 b844d5e4-6fc0-4ec7-b402-8e7668e5a2b3 localhost Login\n[12/24/2017 02:00:06] INFO decebal2 25925950-ecab-41dd-ac8f-d7fcf6099263 127.0.0.1 Login\n```\n \nFor the patterns added by `AuditPatternLayout` see the [javadoc](https://github.com/decebals/auditor/blob/master/auditor-log4j/src/main/java/ro/fortsoft/auditor/log4j/AuditPatternLayout.java#L25) of class.\n \nVersioning\n------------\nAuditor will be maintained under the Semantic Versioning guidelines as much as possible.\n\nReleases will be numbered with the follow format:\n\n`\u003cmajor\u003e.\u003cminor\u003e.\u003cpatch\u003e`\n\nAnd constructed with the following guidelines:\n\n* Breaking backward compatibility bumps the major\n* New additions without breaking backward compatibility bumps the minor\n* Bug fixes and misc changes bump the patch\n\nFor more information on SemVer, please visit http://semver.org/.\n\nLicense\n--------------\n    Copyright 2017 Decebal Suiu\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecebals%2Fauditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecebals%2Fauditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecebals%2Fauditor/lists"}