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-2024 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}