0
# Core Audit Framework
1

2
The core audit framework provides the foundational components for audit event processing, including factories, handlers, and event models that enable centralized audit logging across Apache Ranger security plugins.
3

4
## Capabilities
5

6
### Audit Provider Factory
7

8
Primary singleton factory for creating and managing audit providers with centralized configuration management.
9

10
```java { .api }
11
/**
12
 * Primary factory for creating and managing audit providers
13
 */
14
public class AuditProviderFactory {
15
    /**
16
     * Get singleton instance of the audit provider factory
17
     * @return AuditProviderFactory instance
18
     */
19
    public static AuditProviderFactory getInstance();
20
    
21
    /**
22
     * Initialize the audit provider factory with configuration
23
     * @param props Properties containing audit configuration
24
     * @param appType Application type identifier
25
     */
26
    public void init(Properties props, String appType);
27
    
28
    /**
29
     * Get the configured audit provider
30
     * @return AuditHandler configured audit provider
31
     */
32
    public AuditHandler getAuditProvider();
33
    
34
    /**
35
     * Shutdown the audit provider factory and all providers
36
     */
37
    public void shutdown();
38
}
39
```
40

41
### Audit Writer Factory
42

43
Factory for creating audit file writers with support for different output formats.
44

45
```java { .api }
46
/**
47
 * Factory for creating audit file writers
48
 */
49
public class AuditWriterFactory {
50
    /**
51
     * Get singleton instance of the audit writer factory
52
     * @return AuditWriterFactory instance
53
     */
54
    public static AuditWriterFactory getInstance();
55
    
56
    /**
57
     * Create audit writer for specified format
58
     * @param writerType Type of writer to create ("json", "orc")
59
     * @return RangerAuditWriter writer instance
60
     */
61
    public RangerAuditWriter createWriter(String writerType);
62
    
63
    /**
64
     * Get configured audit writer
65
     * @return RangerAuditWriter configured writer
66
     */
67
    public RangerAuditWriter getAuditWriter();
68
}
69
```
70

71
### Audit Handler Interface
72

73
Primary interface that all audit handlers must implement, providing the contract for audit event processing.
74

75
```java { .api }
76
/**
77
 * Primary interface for all audit handlers
78
 */
79
public interface AuditHandler {
80
    /**
81
     * Log a single audit event
82
     * @param event AuditEventBase event to log
83
     * @return boolean true if successful, false otherwise
84
     */
85
    public boolean log(AuditEventBase event);
86
    
87
    /**
88
     * Log a collection of audit events
89
     * @param events Collection<AuditEventBase> events to log
90
     * @return boolean true if successful, false otherwise
91
     */
92
    public boolean log(Collection<AuditEventBase> events);
93
    
94
    /**
95
     * Log a JSON string audit event
96
     * @param event String JSON-formatted audit event
97
     * @return boolean true if successful, false otherwise
98
     */
99
    public boolean logJSON(String event);
100
    
101
    /**
102
     * Log a collection of JSON string audit events
103
     * @param events Collection<String> JSON-formatted events
104
     * @return boolean true if successful, false otherwise
105
     */
106
    public boolean logJSON(Collection<String> events);
107
    
108
    /**
109
     * Log audit events from a file
110
     * @param file File containing audit events
111
     * @return boolean true if successful, false otherwise
112
     */
113
    public boolean logFile(File file);
114
    
115
    /**
116
     * Initialize the audit handler with configuration
117
     * @param props Properties configuration properties
118
     */
119
    public void init(Properties props);
120
    
121
    /**
122
     * Initialize the audit handler with base property name
123
     * @param props Properties configuration properties
124
     * @param basePropertyName String base property name for configuration
125
     */
126
    public void init(Properties props, String basePropertyName);
127
    
128
    /**
129
     * Start the audit handler
130
     */
131
    public void start();
132
    
133
    /**
134
     * Stop the audit handler
135
     */
136
    public void stop();
137
    
138
    /**
139
     * Wait for completion of pending operations
140
     */
141
    public void waitToComplete();
142
    
143
    /**
144
     * Wait for completion with timeout
145
     * @param timeout long timeout in milliseconds
146
     */
147
    public void waitToComplete(long timeout);
148
    
149
    /**
150
     * Get handler name for logging purposes
151
     * @return String handler name
152
     */
153
    public String getName();
154
    
155
    /**
156
     * Flush any pending audit events
157
     */
158
    public void flush();
159
}
160
```
161

162
### Authorization Audit Event
163

164
Primary audit event model for authorization events with comprehensive metadata and JSON serialization support.
165

166
```java { .api }
167
/**
168
 * Primary audit event model for authorization events
169
 */
170
public class AuthzAuditEvent extends AuditEventBase {
171
    // Repository information
172
    public String getRepositoryName();
173
    public void setRepositoryName(String repositoryName);
174
    public int getRepositoryType();
175
    public void setRepositoryType(int repositoryType);
176
    
177
    // User and access information
178
    public String getUser();
179
    public void setUser(String user);
180
    public String getAccessType();
181
    public void setAccessType(String accessType);
182
    public short getAccessResult();
183
    public void setAccessResult(short accessResult);
184
    
185
    // Resource information
186
    public String getResourceType();
187
    public void setResourceType(String resourceType);
188
    public String getResourcePath();
189
    public void setResourcePath(String resourcePath);
190
    
191
    // Policy information
192
    public long getPolicyId();
193
    public void setPolicyId(long policyId);
194
    public String getPolicyVersion();
195
    public void setPolicyVersion(String policyVersion);
196
    
197
    // Event metadata
198
    public Date getEventTime();
199
    public void setEventTime(Date eventTime);
200
    public String getEventId();
201
    public void setEventId(String eventId);
202
    
203
    // Client information
204
    public String getClientIP();
205
    public void setClientIP(String clientIP);
206
    public String getClientType();
207
    public void setClientType(String clientType);
208
    
209
    // Additional fields
210
    public String getAction();
211
    public void setAction(String action);
212
    public String getRequestData();
213
    public void setRequestData(String requestData);
214
    public String getResultReason();
215
    public void setResultReason(String resultReason);
216
    
217
    // JSON serialization
218
    public String toJson();
219
    public void fromJson(String jsonString);
220
}
221
```
222

223
### Base Audit Handler
224

225
Abstract base implementation providing common functionality for audit handlers including statistics, logging, and lifecycle management.
226

227
```java { .api }
228
/**
229
 * Base implementation for audit handlers with common functionality
230
 */
231
public abstract class BaseAuditHandler implements AuditHandler {
232
    /**
233
     * Initialize the handler with properties
234
     * @param props Properties configuration properties
235
     */
236
    public void init(Properties props);
237
    
238
    /**
239
     * Log a single audit event (delegates to concrete implementation)
240
     * @param event AuditEventBase event to log
241
     */
242
    public void log(AuditEventBase event);
243
    
244
    /**
245
     * Log JSON string event (delegates to concrete implementation)
246
     * @param event String JSON-formatted event
247
     */
248
    public void logJSON(String event);
249
    
250
    /**
251
     * Log audit events from file (delegates to concrete implementation)
252
     * @param file File containing audit events
253
     */
254
    public void logFile(File file);
255
    
256
    // Statistics methods
257
    public long getErrorLogCount();
258
    public long getSuccessLogCount();  
259
    public long getStashedLogCount();
260
    public int getQueueSize();
261
    
262
    // Status and lifecycle methods
263
    public boolean isFlushPending();
264
    public void logStatusIfRequired();
265
    public String getName();
266
    public void setName(String name);
267
    public boolean stop(boolean isWaitToComplete);
268
}
269
```
270

271
**Usage Examples:**
272

273
```java
274
import org.apache.ranger.audit.provider.AuditProviderFactory;
275
import org.apache.ranger.audit.provider.AuditHandler;
276
import org.apache.ranger.audit.model.AuthzAuditEvent;
277
import org.apache.ranger.audit.model.EnumRepositoryType;
278

279
// Initialize audit framework
280
Properties auditProps = new Properties();
281
auditProps.setProperty("xasecure.audit.is.enabled", "true");
282
auditProps.setProperty("xasecure.audit.hdfs.is.enabled", "true");
283

284
AuditProviderFactory factory = AuditProviderFactory.getInstance();
285
factory.init(auditProps, "ranger-plugin");
286

287
// Get audit provider
288
AuditHandler auditProvider = factory.getAuditProvider();
289

290
// Create audit event
291
AuthzAuditEvent event = new AuthzAuditEvent();
292
event.setRepositoryName("hdfs-service");
293
event.setRepositoryType(EnumRepositoryType.HDFS);
294
event.setUser("alice");
295
event.setAccessType("read");
296
event.setResourcePath("/data/sensitive");
297
event.setAccessResult(1); // ALLOWED
298
event.setEventTime(new Date());
299

300
// Log the event
301
auditProvider.log(event);
302

303
// Batch logging
304
List<AuditEventBase> events = Arrays.asList(event1, event2, event3);
305
auditProvider.log(events);
306

307
// JSON logging
308
String jsonEvent = event.toJson();
309
auditProvider.logJSON(jsonEvent);
310
```
311

312
### Utility Classes
313

314
Core utility class providing essential system-level functions used throughout the Apache Ranger audit framework including token replacement, authentication, JSON processing, and configuration management.
315

316
```java { .api }
317
/**
318
 * Comprehensive utility class with essential system-level functions
319
 */
320
public class MiscUtil {
321
    // Token replacement constants
322
    public static final String TOKEN_START = "%";
323
    public static final String TOKEN_END = "%";
324
    public static final String TOKEN_HOSTNAME = "hostname";
325
    public static final String TOKEN_APP_TYPE = "app-type";
326
    public static final String TOKEN_JVM_INSTANCE = "jvm-instance";
327
    public static final String TOKEN_TIME = "time:";
328
    public static final String TOKEN_PROPERTY = "property:";
329
    public static final String TOKEN_ENV = "env:";
330
    
331
    // Token replacement utilities
332
    public static String replaceTokens(String str, long time);
333
    
334
    // System information utilities
335
    public static String getHostname();
336
    public static void setApplicationType(String applicationType);
337
    public static String getApplicationType();
338
    public static String getJvmInstanceId();
339
    public static String getSystemProperty(String propertyName);
340
    public static String getEnv(String envName);
341
    public static String getFormattedTime(long time, String format);
342
    
343
    // File and directory operations
344
    public static void createParents(File file);
345
    
346
    // Time and rollover management
347
    public static long getNextRolloverTime(long lastRolloverTime, long interval);
348
    public static long getRolloverStartTime(long nextRolloverTime, long interval);
349
    
350
    // Parsing and conversion utilities
351
    public static int parseInteger(String str, int defValue);
352
    public static int toInt(Object value);
353
    public static long toLong(Object value);
354
    public static Date toDate(Object value);
355
    public static Date toLocalDate(Object value);
356
    
357
    // UUID and GUID generation
358
    public static String generateUniqueId();
359
    public static String generateGuid();
360
    
361
    // JSON serialization/deserialization
362
    public static ObjectMapper getMapper();
363
    public static <T> String stringify(T log);
364
    public static <T> T fromJson(String jsonStr, Class<T> clazz);
365
    
366
    // Properties management
367
    public static String getStringProperty(Properties props, String propName);
368
    public static String getStringProperty(Properties props, String propName, String defValue);
369
    public static boolean getBooleanProperty(Properties props, String propName, boolean defValue);
370
    public static int getIntProperty(Properties props, String propName, int defValue);
371
    public static long getLongProperty(Properties props, String propName, long defValue);
372
    public static Map<String, String> getPropertiesWithPrefix(Properties props, String prefix);
373
    
374
    // Collection utilities
375
    public static List<String> toArray(String destListStr, String delim);
376
    
377
    // Security and authentication methods
378
    public static String getCredentialString(String url, String alias);
379
    public static UserGroupInformation createUGIFromSubject(Subject subject);
380
    public static void setUGILoginUser(UserGroupInformation newUGI, Subject newSubject);
381
    public static UserGroupInformation getUGILoginUser();
382
    public static Subject getSubjectLoginUser();
383
    public static <X> X executePrivilegedAction(final PrivilegedExceptionAction<X> action);
384
    public static <X> X executePrivilegedAction(final PrivilegedAction<X> action);
385
    
386
    // Kerberos authentication
387
    public static String getKerberosNamesRules();
388
    public static String getShortNameFromPrincipalName(String principal);
389
    public static Set<String> getGroupsForRequestUser(String userName);
390
    public static void setUGIFromJAASConfig(String jaasConfigAppName);
391
    public static void authWithKerberos(String keytab, String principal, String nameRules);
392
    public static void loginWithKeyTab(String keytab, String principal, String nameRules);
393
    public static UserGroupInformation getLoginUser();
394
    
395
    // UTC date utilities
396
    public static Date getUTCDateForLocalDate(Date date);
397
    public static Date getUTCDate();
398
    
399
    // Logging utilities
400
    public static boolean logErrorMessageByInterval(Logger useLogger, String message);
401
    public static boolean logErrorMessageByInterval(Logger useLogger, String message, Throwable e);
402
}
403
```