001/* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Portions Copyright 2011-2023 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.ds.api; 028 029 030 031import java.io.IOException; 032import java.util.Collections; 033import java.util.List; 034import java.util.Map; 035 036import com.unboundid.directory.sdk.common.internal.Configurable; 037import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider; 038import com.unboundid.directory.sdk.common.internal.UnboundIDExtension; 039import com.unboundid.directory.sdk.common.types.Entry; 040import com.unboundid.directory.sdk.ds.config.DataSecurityAuditorConfig; 041import com.unboundid.directory.sdk.ds.types.DataSecurityAuditorEntryReporter; 042import com.unboundid.directory.sdk.ds.types.DataSecurityAuditorSummaryReporter; 043import com.unboundid.directory.sdk.ds.types.DirectoryServerContext; 044import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 045import com.unboundid.ldap.sdk.LDAPException; 046import com.unboundid.ldap.sdk.unboundidds.PasswordPolicyStateJSON; 047import com.unboundid.util.Extensible; 048import com.unboundid.util.NotNull; 049import com.unboundid.util.Nullable; 050import com.unboundid.util.ThreadSafety; 051import com.unboundid.util.ThreadSafetyLevel; 052import com.unboundid.util.args.ArgumentException; 053import com.unboundid.util.args.ArgumentParser; 054 055 056 057/** 058 * This class defines an API that must be implemented by extensions that may 059 * examine entries to identify potential security-related issues (or potentially 060 * other characteristics of note). 061 * <BR> 062 * <H2>Configuring Data Security Auditors</H2> 063 * In order to configure a data security auditor created using this API, use a 064 * command like: 065 * <PRE> 066 * dsconfig create-data-security-auditor \ 067 * --auditor-name "<I>{auditor-name}</I>" \ 068 * --type third-party \ 069 * --set enabled:true \ 070 * --set "extension-class:<I>{class-name}</I>" \ 071 * --set "extension-argument:<I>{name=value}</I>" 072 * </PRE> 073 * where "<I>{auditor-name}</I>" is the name to use for the data security 074 * auditor instance, "<I>{class-name}</I>" is the fully-qualified name of the 075 * Java class that extends 076 * {@code com.unboundid.directory.sdk.ds.api.DataSecurityAuditor}, 077 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to 078 * provide to the data security auditor. If multiple arguments should be 079 * provided to the data security auditor, then the 080 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be 081 * provided multiple times. 082 */ 083@Extensible() 084@DirectoryServerExtension() 085@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 086public abstract class DataSecurityAuditor 087 implements UnboundIDExtension, 088 Configurable, 089 ExampleUsageProvider 090{ 091 /** 092 * Creates a new instance of this data security auditor. All data security 093 * auditor implementations must include a default constructor, but any 094 * initialization should generally be done in the 095 * {@code initializeDataSecurityAuditor} method. 096 */ 097 public DataSecurityAuditor() 098 { 099 // No implementation is required. 100 } 101 102 103 104 /** 105 * {@inheritDoc} 106 */ 107 @Override() 108 @NotNull() 109 public abstract String getExtensionName(); 110 111 112 113 /** 114 * {@inheritDoc} 115 */ 116 @Override() 117 @Nullable() 118 public abstract String[] getExtensionDescription(); 119 120 121 122 /** 123 * {@inheritDoc} 124 */ 125 @Override() 126 public void defineConfigArguments(@NotNull final ArgumentParser parser) 127 throws ArgumentException 128 { 129 // No arguments will be allowed by default. 130 } 131 132 133 134 /** 135 * Initializes this data security auditor before beginning processing in the 136 * specified backend. 137 * 138 * @param serverContext A handle to the server context for the server in 139 * which this extension is running. 140 * @param config The general configuration for this data security 141 * auditor. 142 * @param parser The argument parser which has been initialized from 143 * the configuration for this data security auditor. 144 * @param backendID The backend ID for the backend in which processing 145 * will be performed. 146 * 147 * @throws LDAPException If a problem occurs while initializing this data 148 * security auditor. 149 */ 150 public void initializeDataSecurityAuditorForBackend( 151 @NotNull final DirectoryServerContext serverContext, 152 @NotNull final DataSecurityAuditorConfig config, 153 @NotNull final ArgumentParser parser, 154 @NotNull final String backendID) 155 throws LDAPException 156 { 157 // No initialization will be performed by default. 158 } 159 160 161 162 /** 163 * Performs any cleanup that may be necessary when this data security auditor 164 * ends processing in a backend. 165 */ 166 public void finalizeDataSecurityAuditor() 167 { 168 // No implementation is required. 169 } 170 171 172 173 /** 174 * Examines the provided entry to determine whether any data security issues 175 * should be reported. If any such issues are found, then the provided 176 * reporter should be used to report them. 177 * 178 * @param entry The entry to examine. 179 * @param passwordPolicyState The password policy state for the account 180 * with which the provided entry is associated. 181 * @param reporter A reporter whose {@code reportEntry} method 182 * may be used to indicate that the provided 183 * entry has one or more identified issues. 184 * 185 * @throws IOException If a problem is encountered while the reporter is 186 * attempting to add an entry to the report file. 187 */ 188 public abstract void examineEntry( 189 @NotNull final Entry entry, 190 @NotNull final PasswordPolicyStateJSON passwordPolicyState, 191 @NotNull final DataSecurityAuditorEntryReporter reporter) 192 throws IOException; 193 194 195 196 /** 197 * Reports a summary of the results obtained from processing this data 198 * security auditor in the associated backend. 199 * 200 * @param reporter The reporter that may be used to provide the summary of 201 * processing performed by this data security auditor in the 202 * associated backend. 203 * 204 * @throws IOException If a problem is encountered while the reporter is 205 * attempting to add an entry to the report file. 206 */ 207 public abstract void reportSummary( 208 @NotNull final DataSecurityAuditorSummaryReporter reporter) 209 throws IOException; 210 211 212 213 /** 214 * {@inheritDoc} 215 */ 216 @Nullable() 217 public Map<List<String>,String> getExamplesArgumentSets() 218 { 219 return Collections.emptyMap(); 220 } 221}