Build discovery plugins

Discovery plugins are used to import data from third-party scan providers into your DigiCert® Trust Lifecycle Manager inventory for centralized monitoring and management. Each discovery plugin defines how to access, authenticate, and retrieve data from a particular scan provider. This article covers the Java classes and development process for building discovery plugins.

Before you begin

Follow the steps in the Prepare your development environment topic to:
- Access the example repository for this plugin type.
- Configure the required development tools and settings.
- Run a test build.
Make sure you understand the common project files for custom plugins.
Review the README file for the example plugin repository in detail.

Plugin development

To develop a discovery plugin, create a branch of the example repository and update the Java class definitions with your custom logic:

Each plugin should target a particular scan provider, for example a specific network scanner or certificate monitoring service.
The scan provider must expose its data through an API or similar mechanism. Your custom logic specifies how to connect to and authenticate with that provider to retrieve certificate, endpoint, and security scan data.
When you add a connector (instance) of the plugin in Trust Lifecycle Manager, import operations for that connector trigger the discovery workflow, which must include steps to:
- Connect to and authenticate with the external scan provider.
- Retrieve certificate, endpoint, and security scan data from the provider and return it to Trust Lifecycle Manager to import into inventory.

Java classes

The example discovery plugin provides the following Java source files under src/main/java/com/example/discovery. To create your custom plugin, modify or extend the applicable class and method definitions in these files.

MyDiscoveryPlugin.java

Description

The primary class that defines the custom logic for each discovery plugin. It extends the AbstractDiscoveryWorkflow class and implements custom integration and data import tasks for incorporating a particular scan provider into discovery workflows in Trust Lifecycle Manager.

Customizations

To implement custom integration and data import logic, update the code in the following methods, annotated with @Override.

Purpose

Import certificate, endpoint, and security scan data from the external scan provider.

Customizing

By default, this method sets hard-coded scan data to import into Trust Lifecycle Manager.

To customize it:

Add logic to dynamically read certificate, endpoint, and security scan data from the external scan provider.
Using the same framework as the hard-coded examples, assign the scan data points to import objects and return a list of them to Trust Lifecycle Manager.

Required

The response returned to Trust Lifecycle Manager must consist of a list of import data points, for example: response.setImportDataList(List.of(scan1, scan2, scan3));

Each individual scan data point corresponds to a single certificate and its associated data. Use the same set methods from the example plugin to assign each property value. At minimum, each data point returned to Trust Lifecycle Manager must include the following mandatory properties:

Property	Description
`CertString`	PEM-encoded certificate.
`Ip`	IP address of endpoint where the certificate was found.
`Port`	Port number where the certificate was found on the endpoint.
`DomainName`	Domain name of the endpoint where the certificate was found, corresponding to the certificate's common name and/or SAN DNS name.

Optional

Use ImportStateMap objects to store metadata in Trust Lifecycle Manager about ongoing import operations, or to apply custom logic to each import operation based on this metadata.

To update the import metadata based on the current scan, create a new ImportStateMap object and use it to set one or more metadata properties, then add it to the current response using the ImportDataResponse.setImportState() method.

Define metadata properties in the ImportStateMap.java class. The example plugin defines the following metadata properties in this class, but you are free to add, remove, or extend these properties as needed.

Property	Description
`Offset`	Offset value reflecting the total number of scan data points imported from the target system.
`Type`	The type of scan data being imported.
`LastUpdated`	The date of the most recent import operation.

To retrieve the import metadata from Trust Lifecycle Manager as set by the previous scan operation, use the ImportDataRequest.getImportState() method. Use this previous metadata as needed to apply custom logic or modify the metadata for the current import operation (for example, adjusting the offset value).

Purpose

Fetch user and account data. This metadata helps identify each plugin instance and keep a single connector per account.

Customizing

By default, this method sets hard-coded account and user data to import into Trust Lifecycle Manager.

To customize it:

Add logic to dynamically read applicable account and user data from the scan provider, to help identify each plugin instance.
Using the same framework as the hard-coded examples, assign the dynamic data to a response object and return it to Trust Lifecycle Manager.

Note

All fields in the response are optional. However, lack of any unique identifying metadata may result in errors in Trust Lifecycle Manager when adding multiple instances (connectors) of the same plugin.

MyDiscoveryPluginRunner.java

Description

Acts as the entry point for the plugin, invoking the plugin object defined in MyDiscoveryPlugin.java, along with the required SDK context object for sharing information across different methods and storing results at different execution points.

Customizations

This class should not typically be modified. If you do customize it, make sure the fully qualified class name matches the one in the pom.xml file.

MyPluginConfiguration.java

Description

Defines the configuration properties for the plugin. All properties you define here should have matching fields in the config_settings section of the JSON configuration file for the plugin. This ensures that users provide values for these properties when configuring each instance (connector) of the plugin in Trust Lifecycle Manager.

Customizations

By default, this class defines variables to store user credentials (userName and password) for accessing the external scan provider.

To customize:

Adjust the default variables if the scan provider uses an authentication method other than user credentials.
Add one or more variables to store any required network properties for connecting to the scan provider, such as its URL or IP address.
Define additional variables as needed to configure different settings for connecting and using each instance of the custom plugin.

ImportStateMap.java

Description

Defines optional metadata properties for tracking the state of import operations. To maintain state across successive import operations:

At the end of each import call, serialize an ImportStateMap object into the response returned to Trust Lifecycle Manager.
At the start of the next import call, deserialize that object back from the request to restore the previous import state.

See the getDiscoveryData() method under MyDiscoveryPlugin.java for usage details.

Customizations

By default, this class defines the following properties.

Property	Description
`Offset`	Offset value reflecting the total number of scan data points imported from the target system.
`Type`	The type of scan data being imported.
`LastUpdated`	The date of the most recent import operation.

To customize, add, remove, or modify these properties as needed for your import use case. Any properties defined here can be set and retrieved in MyDiscoveryPlugin.java using the corresponding Lombok-generated getter and setter methods.

Build the plugin ZIP file

Important

Before building the plugin, make sure your development environment includes the required software and settings. For details, see Prepare your development environment.

After adding your custom logic, build the plugin ZIP file on the development system as follows:

From the top-level project directory, run the build script by making the ./build.sh command.
The script prints status messages to the console as it executes. At the end, it generates and prints the SHA-256 checksum for the ZIP file, confirming a successful build.
Find the final ZIP file for the plugin in the plugin-dist subdirectory. The ZIP file contains the plugin JAR file and metadata JSON file required by Trust Lifecycle Manager.

What's next

To add the plugin to Trust Lifecycle Manager, you must upload both the plugin ZIP file and corresponding JSON configuration file.

For details about the required JSON configuration format, see Create the plugin configuration.

In this section: