The Black Duck Fortify Software Security Center (SSC) plugin runs in the background as a service, and maps your Black Duck project to one or more Fortify SSC projects. It pushes open source security risk information from Black Duck into your connected Fortify SSC application. The implementation also makes it possible to monitor and manage open source risk, and provision the information concurrently into Fortify SSC. This enables you to view and manage all security risks pertaining to an application in a single view.
You can download Black Duck Fortify SSC at https://github.com/blackducksoftware/hub-fortify-ssc-integration-service.
The Black Duck parser plugin is a simple parser to convert the Black Duck vulnerability report into a Fortify-friendly format.
Download the parser at https://github.com/blackducksoftware/hub-fortify-parser/releases.
Install the Black Duck Parser using the following instructions corresponding with your Fortify environment:
blackduck-plugin-<Version>.jar
parser plugin using the SSC user interface.blackduck-plugin-<Version>.jar
file to $USER_HOME\.fortify\plugin-framework\plugins
. $USER_HOME\.fortify
directory into which to copy the Black Duck plugin. To address this, do the following:C:\.fortify\plugin_framework\plugins
directory. The service account must be able to read this folder.-Dfortify.home=C:\.fortify
The plugin is invoked automatically when the Black Duck Fortify SSC integration service uploads the security vulnerabilities using the Fortify Upload API.
If you don't plan to modify the source code, there should be no need to recompile and build the parser; however, if you change the source code, you must rebuild. The parser is a Gradle project; there are dependencies on Fortify jars in the /WEB-INF/lib directory within the Fortify tomcatforSSC
folder.
..\WEB-INF\lib
folder.gradle clean assemble.
The latest release is 2.0.3.
If you have previously installed a version of the parser lower than 2.0.0, you must upgrade to the latest version.
As of Black Duck Fortify version 2.0.2, additional columns are added to the security vulnerability report to fix the duplicate ID issue, and to display detailed security information in the Fortify UI. This allows the parser to process file formats used prior to Black Duck Fortify version 2.0.7 and Black Duck parser version 2.0.2. This is a one-time process. Before beginning the upgrade of the parser, we recommend saving your report data from within the Fortify UI. This ensures that you can restore your data if you need to revert to the old parser. The steps are as follows.
Version 2.0.2 or higher of the Black Duck parser is required for HPE Fortify SSC versions 17.10.x and higher. HPE Fortify SSC version 17.10.x and higher is incompatible with version 1.0.0 of the Black Duck parser. |
Use the following procedure to install and run the Black Duck Fortify SSC plugin.
After you have downloaded and installed the Black Duck Fortify SSC plugin and the Black Duck parser, use the following processes to configure your Black Duck Fortify SSC plugin.
Configure the application.properties file to integrate Black Duck with your Fortify SSC projects. The application.properties file contains:
If the project BOM updated date is greater than last successful runtime of the job, then only the vulnerabilities upload to Fortify SSC. Otherwise, it is ignored.
# Cron expressions can be generated at http://www.cronmaker.com. The cron expression must contain six values; ignore the last value. cron.expressions=0 0 0/1 * * ? spring.batch.job.enabled=true # Black Duck Hub Server details - Either hub username and password or API token to be provided. If both given, API token will be prioritized hub.username=<<HUB_USER_NAME>> hub.password=<<HUB_PASSWORD>> hub.timeout=12000 hub.server.url=https://<<HUB_SERVER_IP_ADDRESS>>:<<HUB_SERVER_PORT_NUMBER>> hub.api.token=<<HUB_API_TOKEN>> # Trust certificate either true or false hub.always.trust.cert=false #BlackDuck proxy details - optional hub.proxy.host= hub.proxy.port= hub.proxy.user= hub.proxy.password= hub.proxy.nohost= # Fortify Server details fortify.server.url=http://<<FORTIFY_SERVER_IP_ADDRESS>>:<<FORTIFY_SERVER_PORT_NUMBER>>/ssc/ fortify.username=<<FORTIFY_USER_NAME>> fortify.password=<<FORTIFY_PASSWORD>> maximum.thread.size=5 hub.fortify.batch.job.status.file.path=../config/batch_job_status.txt hub.fortify.report.dir=../report/ hub.fortify.mapping.file.path=../config/mapping/json logging.file=../log/hub-fortify.log attribute.file=../config/attributes.properties hub.fortify.push.for.zero.vulnerability=true batch.job.status.check=true logging.level.org.springframework=ERROR logging.level.com.blackducksoftware=INFO # Logging patter for the console logging.pattern.console= %d{MM-dd-yyyy HH:mm:ss,SSS} %-5p [%t] %c:%L %M -%m%n # Logging pattern for file logging.pattern.file= %d{MM-dd-yyyy HH:mm:ss,SSS} %-5p [%t] %c:%L %M -%m%n |
To configure the application.properties file:
To specify an HTTPS connection:
You can use environment variables to avoid hard-coding certain configuration values in the applications.properties file. It is recommended that you use environment variables for sensitive information like usernames and passwords. |
To use an environment variable to set a particular application property, set the property value to $MY_ENVIRONMENT_VARIABLE_NAME, as shown in the following examples.
# BlackDuck Server details
hub.username=$HUB_USERNAME
hub.password=$HUB_PASSWORD
hub.timeout=$HUB_TIMEOUT
hub.server.url=$HUB_SERVER_URL
# Fortify Server details
fortify.server.url=$FORTIFY_SERVER_URL
fortify.username=$FORTIFY_USERNAME
fortify.password=$FORTIFY_PASSWORD
If you prefer not to use Black Duck user names and passwords at all; either hard coded in the configuration, or with environment variables, you can use a Black Duck API token for authentication. To use an API token:
This will generate the token. You can now provide this value in your applications.properties file. For example: hub.api.token=<my API token> Note that you can also specify the API token as an environment variable for additional security. |
For the attributes.properties file, note the following considerations:
If your Black Duck environment utilizes proxies, you can configure the proxy settings in the applications.properties file as follows.
You can map specific Fortify applications to Black Duck by selecting which of your Black Duck projects to map to your Fortify applications. This is accomplished by editing the mapping.json file, located in the Config folder. You must specify the version numbers. Note that this file is case-sensitive.
1:1 Mapping: As of Black Duck versions 3.0.0 and higher, you can map one Black Duck project to one Fortify Application.
To map Fortify projects to Black Duck:
You can map as many Fortify projects as needed. Repeat the preceding process for each mapped project. In the following example, three projects are mapped. Note that you must add a comma after the ending curly bracket for each project.
Black Duck Fortify versions 2.0.1 and higher provide the following mapping options:
When mapping many Black Duck project versions to one Fortify application version mapping, the integration service removes the duplicate vulnerabilities across Black Duck project versions, and Fortify displays the Project Name as Multiple projects, and Project Version as Multiple versions for the vulnerability.
To add the host as a trusted entity, you must execute the following command:
keytool -import -trustcacerts -keystore $JAVA_HOME/jre/lib/security/jssecacerts -file /path/to/certificate -alias hub |
If you prefer your Fortify SSC plugin to trust self-signed certificates from Black Duck, then set the following value in the applications.properties file:
hub.always.trust.cert=true |
Please be aware that trusting self-signed certificates is less secure than using a server certificate signed by a trusted authority; therefore, using self-signed certificates is not recommended.
Optionally, you can configure Cron job settings, which are in the application.properties file. This enables your Fortify projects to be automatically updated with Black Duck information on a predetermined schedule. The default setting is once per hour. Black Duck recommends that you use http://www.cronmaker.com/ to create your Cron expression.
To configure Cron jobs:
Based on your Cron expression, the batch job performs the following steps:
The batch job status file contains the date and time stamp of the last successful run.
You can change the batch job settings to force the Black Duck Fortify SSC plugin to push vulnerabilities from the specified date. By default, the Black Duck Fortify SSC plugin pushes the change vulnerabilities after the last successful run-time of the job. You can configure batch jobs by editing the batch job status file, located in the Config folder, as follows.
To configure batch jobs:
The batch_job_status.txt file, located in the Config folder, is used to store the last successful run-time of the job. In the Deployment folder, the batch_job_status.txt file is blank. This allows all Black Duck projects to be pushed to Fortify on the first usage. During the initial run, if you have not added the project to the mapping.json file, then you cannot push the vulnerabilities.
Modify the batch_job_status.txt file to contain a date earlier than the last Bill of Materials update date for the Black Duck project. In the next run, the batch job pushes the vulnerabilities to Fortify.
You can manually upload security vulnerabilities to Fortify using the Fortify UI. You should familiarize yourself with the sample.csv security report file that is available in the Reports area in GitHub here.
Generally, to upload vulnerabilities, simply:
If, for whatever reason, you are unable to select Black Duck engine on the upload page, follow these alternative instructions to ensure that the upload is properly read as Black Duck data:
A sample.csv file is available in GitHub under the Reports folder. |
To swap projects, use the following process.
If you would like to launch the Black Duck Fortify plugin in Windows Task Scheduler, then there are a few additional configuration changes you must make. The changes are necessary because if you run the plugin from the Windows Task Scheduler, the plugin will be invoked from the system32 directory, and this invalidates certain relative paths. To address this, do the following:
FORTIFY_APP_HOME
environment variable to your downloaded plugin location.FORTIFY_APP_HOME=C:\ssc\hub-fortify-ssc-integration-service-2.0.6
$FORTIFY_APP_HOME/bin/hub-fortify-ssc-integration-service.bat
In that file, find the text:../config/
%APP_HOME%/config/
$FORTIFY_APP_HOME/config/application.properties
and replace "..
" with ${FORTIFY_APP_HOME}
on the following lines:hub.fortify.batch.job.status.file.path=${FORTIFY_APP_HOME}/config/batch_job_status.txt
hub.fortify.report.dir=${FORTIFY_APP_HOME}/report
hub.fortify.mapping.file.path=${FORTIFY_APP_HOME}/config/mapping.json
logging.file=${FORTIFY_APP_HOME}/log/hub-fortify.log
attribute.file=${FORTIFY_APP_HOME}/config/attributes.properties
The log files are in the Log folder. They contain the status of your Black Duck Fortify runs. The log file contains exception errors, file issues, and more. You must manually check the log file, as this is the only communications path monitoring and displaying the status of your Black Duck Fortify SSC service runs.
New feature
Known issue
Resolved issues
You must upgrade Black Duck Fortify parser to 2.0.2 or later. |
Known issues
New features
New features
New features
Known issues
New features
Known issues
New features
Resolved issues
Changes in 2.0.2b
New features
Known issues in version 2.0.2
java.util.concurrent.ExecutionException: com.blackducksoftware.integration.hub.rest.exception.IntegrationRestException:
There was a problem trying to GET this item: https://<<HUB_HOST_NAME>>/api/projects?q=name%3A<<HUB_PROJECT_NAME>>&offset=0&limit=100. Error: 401
java.util.concurrent.ExecutionException: com.blackducksoftware.integration.hub.rest.exception.IntegrationRestException:
There was a problem trying to GET this item: https://<<HUB_HOST_NAME>>/api/projects?q=name%3A<<HUB_PROJECT_NAME>>&offset=0&limit=100. Error: 400
New features
New features
Known issues for version 1.0.0
In the existing Hub Fortify integration, you must manually upload the vulnerability report in the Fortify UI. Each row in the vulnerability report must have a unique key. In the Black Duck parser plugin, the ID is a unique key, which is called as Issue Id in Fortify SSC.
Workaround
Black Duck has modified the combination of this unique key to adapt to additional situations as follows.