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.

DigiCert provides an example GitHub repository to help you build custom discovery plugins. This page describes the project components and build steps.

Before you begin

Make sure you understand and satisfy these prerequisites before building discovery plugins for Trust Lifecycle Manager.

GitHub repositories

To start building plugins, you need access to the following repositories under the DigiCert organization in GitHub:

tlm-plugin-example-discovery: Example discovery plugin for Trust Lifecycle Manager. To help create your own custom plugins, you will use this repository as the starting point.
tlm-plugins-sdk: DigiCert software development kit for building plugins for Trust Lifecycle Manager. The example plugin repository depends on this SDK repository.

To request access to these repositories, contact your DigiCert account representative or solutions engineer. Note that you must have a personal access token (classic) in GitHub to use these repositories.

Maven build system

The example plugin repository is a Java project based on the Maven build system. The system where you build the plugin must have:

Java 17 or later
Maven version 3.6 or later

Java IDE

To view and work on the example plugin repository, DigiCert recommends using an integrated development environment (IDE). The IDE helps resolve dependencies and ensures the project development environment is configured correctly.

The instructions on this page focus on the Eclipse IDE. To learn more, refer to the official Eclipse website.

Overview of the build process

The process of building a custom plugin consists of these steps:

Clone the GitHub repository for the example discovery plugin.
The repository URL is https://github.com/digicert/tlm-plugin-example-discovery. Contact your DigiCert account representative or solutions engineer for questions about how to access this repository.
Import the project into the Java IDE.
Follow these steps to import the example plugin project into the Eclipse IDE. The process is similar for other Java IDEs.
1. Open the Eclipse IDE and select the option to Import projects.
2. In the Import modal, go to Maven > Existing Maven Projects and select Next.
3. Navigate to the root folder where you cloned the example plugin repository and select it.
4. After selecting the folder, you should see /pom.xml listed in the Projects window. Select Finish to proceed with the import.
Verify the project files in the Java IDE.
In the Java IDE, you should see all the same files from the GitHub repository, plus additional listings for the Java Runtime Environment (JRE) and Maven dependencies. Review the top-level README.md file for more details about the plugin project files, dependencies, and build process.
Update the project to add your own custom code and settings.
See the Project files and Source files sections below for key components to focus on.
Build the Maven project to generate the final Zip file.
To compile and package everything, run the build script (build.sh) in the top-level project directory. For details, see the Build the plugin Zip file section.

Project files

The following files contain important settings, dependencies, and information for the plugin project. These files are found in the top-level directory of the example discovery plugin.

Project file	Description	Required updates
README.md	The project README file includes important details about the project dependencies, file hierarchy, build process, and more. For best results, review it carefully before making any updates.	—
pom.xml	Contains all the information Maven needs to build the project, including core dependencies, plugins, and build configurations. The `build-plugin-fat-jar` execution block defines the main Java class to execute during runtime. Default value is `com.example.discovery.MyDiscoveryPluginRunner`.	If your custom code includes additional dependencies, you must include them here. If your plugin defines a different main class than the default, update the `mainClass` value in the `build-plugin-fat-jar` execution block.
build.sh	Shell script to build the project by generating the Maven assets and creating the final Zip file for upload into Trust Lifecycle Manager. The script also generates an SHA-256 checksum to ensure the integrity of the Zip file.	Before running this script, make sure the settings.xml file includes the required credentials as described below.
configuration.json	Default JSON file for configuring the plugin in Trust Lifecycle Manager. To enable the plugin, you must upload the JSON configuration file along with the final Zip file.	Update this file to match the required parameters for your plugin. For details, see Create the plugin configuration.
settings.xml	Defines required settings for running the Maven build command, including access to an additional GitHub repository with core plugin SDK files and dependencies. If you will run the build script as part of GitHub actions, the required credentials get populated automatically. Otherwise, you must supply the credentials as described on the right. The credentials must come from a personal access token (classic) in GitHub.	To run the build script locally, use one of the following methods to provide the required GitHub credentials: Add the credentials to the `username` and `password` fields in the settings.xml file. Define the following environment variables with the credentials to use: `GITHUB_ACTOR` or `GITHUB_USER` (username) and `GITHUB_TOKEN` (password).
zip.xml	Defines the list of files to include in the final Zip file for the plugin.	—

Source files

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.

Build the plugin Zip file

Importante

Before running the build script, make sure you've set up the GitHub credentials as configured in the project settings.xml file. For details, see Project files.

After customizing the plugin project and source files, build the plugin Zip file on the development system as follows:

Change into the top-level project directory.
Enter sh build.sh to run the build script.
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 in Trust Lifecycle Manager, you must upload both the plugin Zip file and corresponding JSON configuration file.

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

En esta sección: