com.unboundid.directory.sdk.ds.api.DataSecurityAuditor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of server-sdk Show documentation
The UnboundID Server SDK is a library that may be used to develop various types of extensions to Ping Identity server products, including the Directory Server, Directory Proxy Server, Data Sync Server, Data Metrics Server, and Data Governance Broker.
There is a newer version: 6.2.0.0
Show newest version
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2011-2024 Ping Identity Corporation
 */
package com.unboundid.directory.sdk.ds.api;



import java.io.IOException;
import java.util.Collections;
import java.util.List;
import java.util.Map;

import com.unboundid.directory.sdk.common.internal.Configurable;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.ds.config.DataSecurityAuditorConfig;
import com.unboundid.directory.sdk.ds.types.DataSecurityAuditorEntryReporter;
import com.unboundid.directory.sdk.ds.types.DataSecurityAuditorSummaryReporter;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.unboundidds.PasswordPolicyStateJSON;
import com.unboundid.util.Extensible;
import com.unboundid.util.NotNull;
import com.unboundid.util.Nullable;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;



/**
 * This class defines an API that must be implemented by extensions that may
 * examine entries to identify potential security-related issues (or potentially
 * other characteristics of note).
 * 

 * Configuring Data Security Auditors
 * In order to configure a data security auditor created using this API, use a
 * command like:
 *  *      dsconfig create-data-security-auditor \
 *           --auditor-name "{auditor-name}" \
 *           --type third-party \
 *           --set enabled:true \
 *           --set "extension-class:{class-name}" \
 *           --set "extension-argument:{name=value}"
 * 
 * where "{auditor-name}" is the name to use for the data security
 * auditor instance, "{class-name}" is the fully-qualified name of the
 * Java class that extends
 * {@code com.unboundid.directory.sdk.ds.api.DataSecurityAuditor},
 * and "{name=value}" represents name-value pairs for any arguments to
 * provide to the data security auditor.  If multiple arguments should be
 * provided to the data security auditor, then the
 * "--set extension-argument:{name=value}" option should be
 * provided multiple times.
 */
@Extensible()
@DirectoryServerExtension()
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class DataSecurityAuditor
       implements UnboundIDExtension,
                  Configurable,
                  ExampleUsageProvider
{
  /**
   * Creates a new instance of this data security auditor.  All data security
   * auditor implementations must include a default constructor, but any
   * initialization should generally be done in the
   * {@code initializeDataSecurityAuditor} method.
   */
  public DataSecurityAuditor()
  {
    // No implementation is required.
  }



  /**
   * {@inheritDoc}
   */
  @Override()
  @NotNull()
  public abstract String getExtensionName();



  /**
   * {@inheritDoc}
   */
  @Override()
  @Nullable()
  public abstract String[] getExtensionDescription();



  /**
   * {@inheritDoc}
   */
  @Override()
  public void defineConfigArguments(@NotNull final ArgumentParser parser)
         throws ArgumentException
  {
    // No arguments will be allowed by default.
  }



  /**
   * Initializes this data security auditor before beginning processing in the
   * specified backend.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this data security
   *                        auditor.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this data security auditor.
   * @param  backendID      The backend ID for the backend in which processing
   *                        will be performed.
   *
   * @throws  LDAPException  If a problem occurs while initializing this data
   *                         security auditor.
   */
  public void initializeDataSecurityAuditorForBackend(
                   @NotNull final DirectoryServerContext serverContext,
                   @NotNull final DataSecurityAuditorConfig config,
                   @NotNull final ArgumentParser parser,
                   @NotNull final String backendID)
         throws LDAPException
  {
    // No initialization will be performed by default.
  }



  /**
   * Performs any cleanup that may be necessary when this data security auditor
   * ends processing in a backend.
   */
  public void finalizeDataSecurityAuditor()
  {
    // No implementation is required.
  }



  /**
   * Examines the provided entry to determine whether any data security issues
   * should be reported.  If any such issues are found, then the provided
   * reporter should be used to report them.
   *
   * @param  entry                The entry to examine.
   * @param  passwordPolicyState  The password policy state for the account
   *                              with which the provided entry is associated.
   * @param  reporter             A reporter whose {@code reportEntry} method
   *                              may be used to indicate that the provided
   *                              entry has one or more identified issues.
   *
   * @throws  IOException  If a problem is encountered while the reporter is
   *                       attempting to add an entry to the report file.
   */
  public abstract void examineEntry(
              @NotNull final Entry entry,
              @NotNull final PasswordPolicyStateJSON passwordPolicyState,
              @NotNull final DataSecurityAuditorEntryReporter reporter)
         throws IOException;



  /**
   * Reports a summary of the results obtained from processing this data
   * security auditor in the associated backend.
   *
   * @param  reporter  The reporter that may be used to provide the summary of
   *                   processing performed by this data security auditor in the
   *                   associated backend.
   *
   * @throws  IOException  If a problem is encountered while the reporter is
   *                       attempting to add an entry to the report file.
   */
  public abstract void reportSummary(
              @NotNull final DataSecurityAuditorSummaryReporter reporter)
         throws IOException;



  /**
   * {@inheritDoc}
   */
  @Nullable()
  public Map,String> getExamplesArgumentSets()
  {
    return Collections.emptyMap();
  }
}