Xanitizer » Integration » Jenkins

Jenkins Builder

Introduction

We provide a Jenkins plugin that can execute the following steps:

  • Run Security Analysis to run a Xanitizer security analysis based on an existing Xanitizer configuration file or on a root directory with optionally:
    • Create Reports to generate different reports with the results of the Xanitizer security analysis.
    • Create Snapshot to create a new snapshot, that keeps the results of the analysis and makes it possible to compare different versions.
    • Export Project to export the whole Xanitizer project with all snapshots and security analysis results.
  • Install License File to install or update a license file to run Xanitizer.
  • Update OWASP Dependency Check Repository Ant Task to update the internal database of the OWASP Dependency Check, which is used to detect external libraries with known vulnerabilities.

Compatibility

PluginJenkinsXanitizerDownload
1.0.0≥ 2.138.4≥ 4.3.2.xanitizer-jenkins-plugin-1.0.0.hpi

Download and Installation

To install the Xanitizer Jenkins plugin:

  1. Please download the latest version here.
  2. Login into your Jenkins installation as an administrator.
  3. From the Jenkins Dashboard, open “Manage Jenkins > Manage Plugins”.
    Screenshot Jenkins manage plugins
  4. Change to the section “Upload Plugin” in the Advanced tab and press the button “Choose File” to select the hpi file and press the button “Upload” to upload it.
    Screenshot Jenkins upload plugin

The Xanitizer Jenkins plugin does not run the build steps itself, it needs a Xanitizer installation at the execution node (the machine which executes the build) to execute the step.

Configure Xanitizer Jenkins Plugin for a Job

To enable the Xanitizer security analysis for a Jenkins job:

  1. From the job’s page, open “Configure” and scroll to the Build section.
  2. Click on the drop-down box “Add build step” and choose “Xanitizer Security Analysis” to add the Xanitizer security analysis and to display the configuration parameters.
    Screenshot Jenkins enable plugin on job

The Xanitizer Jenkins plugin needs a Xanitizer installation at the execution node (the machine which executes the build) with a license file. The installation directory at the execution node has to be specified via parameter “Installation Directory” and the parameter “License File” can be used to install or update the necessary license file to run Xanitizer in headless mode.

With the drop-down box “Run Security Analysis” it can be configured whether the security analysis is based on an existing Xanitizer configuration file or based on a root directory from where to construct a default configuration.

To generate more than one report (e.g. HTML and XML), the parameters “Overview Report Files” and “Findings List Report Files” can contain a list of output files separated by comma, semicolon or line ending characters.

To update only the OWASP Dependency Check repository without executing a security analysis, enable the parameter “Update OWASP Dependency Check DB?” and set the drop-down box “Run Security Analysis” to “Disabled”.

For all further parameters, please click on the help button Jenkins help icon behind the parameter or read the description here.

The Xanitizer Jenkins plugin supports the following environment variables as part of a configuration parameter in the form ${ENV_VAR_NAME}:

Environment VariableDescription
${JOB_NAME}Name of the project/job of the build.
${WORKSPACE}The absolute path of the workspace.
${BUILD_NUMBER}The current number of the build.
${BUILD_TAG}String of jenkins-${JOB_NAME}-${BUILD_NUMBER}.

Parameters

TitleParameterDescription
Installation DirectoryinstallDirectoryPath to the Xanitizer installation directory.
License File (optional)licenseFileOptional path to the Xanitizer license file. If not specified, the license in the <USER_HOME>/.Xanitizer directory is used.
Run Security AnalysissecurityAnalysisConfigChoose whether the security analysis is disabled, is executed based on an existing Xanitizer configuration file, or is executed based on a root directory from where to construct a default configuration.
Configuration FileconfigFilePath to the Xanitizer configuration file to run a security analysis based on it.
Project Data Directory (optional)projectDataDirectoryOptional path where Xanitizer stores the project data. If not specified, a subdirectory of <USER_HOME>/.Xanitizer is used.
Change Build State on Missing Search PathshaltOnMissingSearchPathsSpecifies, whether the build should be marked as unstable or failed in the case of a missing search path or not. Marking the build as unstabel or failed can be used to detect if the analyzed project does not match the provided configuration any longer.
Set Build tobuildStatusOnMissingSearchPathsset build to
Change Build State on New FindingshaltOnNewFindingsSpecifies, whether the build should be marked as unstable or failed in the case of new findings with a critical rating. A finding is new if there is no corresponding finding in an earlier snapshot. A finding is critical if its rating is equal or higher than the specified threshold.
Set Build tobuildStateOnNewFindingsset build to
For New Findings With ThresholdnewFindingsRatingThresholdfor new findings with threshold
Change Build State on Any FindinghaltOnFindingsSpecifies, whether the build should be marked as unstable or failed in the case of findings with a critical rating. It does not matter if this finding is new or old. A finding is critical if its rating is equal or higher than the specified threshold.
Set Build tobuildStateOnFindingsset build to
For Any Finding With ThresholdfindingsRatingThresholdfor any finding with threshold
Generate ReportsgenerateReportsgenerate reports
Overview Report FilesoverviewReportOutputFilesList of report files containing an overview about the security vulnerabilities in the project. The file extension specifies the format. Admissible formats are “pdf”, “html”, “doc”, or “odt”.
Note: If more than one report file should be generated, separated the files by comma, semicolon, or line ending characters.
Findings List Report FilesfindingsListReportOutputFilesList of report files containing a list of all findings. The file extension specifies the format. Admissible formats are “pdf”, “html”, “doc”, “odt”, “xml”, or “csv”.
Note: If more than one report file should be generated, separated the files by comma, semicolon, or line ending characters.
... Export Only Problems?onlyProblemsInFindingsListReportIf enabled, only problem findings will be listed in the findings list report. By default, both problem findings and mere informational findings are listed.
... Export Details?generateDetailsInFindingsListReportIf enabled, all the details of a finding are written to the findings list report. Note that this flag is only relevant for reports with the file extensions “xml” or “html”.
Archive Reports?archiveReportsWhether all generated reports have to be copied into the subdirectory 'xanitizer' in the archive directory of the current build or not.
Create SnapshotcreateSnapshotSpecifies if a snapshot should be generated after parsing and analyzing the current version.
Note that the snapshot can be enhanced with an optional comment.
Snapshot Comment (optional)snapshotCommentsnapshot comment (optional)
Export ProjectexportProjectIf enabled, the analysis results are exported into a zip archive file in the export directory.
Note that the exported zip archive file can be protected by an optional password.
Export DirectoryexportDirectoryexport directory
Password (optional)exportPassphrasepassword (optional)
Root DirectoryrootDirectoryRoot directory from where to construct a default configuration to run a security analysis based on it.
Project Name (optional)projectNameOptional name of the project. If not specified, the simple name of the root directory is used as default.
Configuration File DirectoryconfigFileDirectoryOptional path to the newly created Xanitizer configuration file. If not specified, a subdirectory of <USER_HOME>/.Xanitizer is used.
Overwrite Configuration File?overwriteConfigFileSpecifies if, when the default Xanitizer configuration file is being created, an existing file should be overwritten. If a file with the same name already exists and this flag is false, the build will be marked as instable.
Update OWASP Dependency Check DB?updateOWASPDbSpecifies whether the OWASP Dependency Check repository should be updated or not.
Note that the OWASP Dependency Check is based on vulnerability data stored in a local repository. It is recommended to update the local OWASP Dependency Check repository on a regular basis. This update needs remote access to the US National Vulnerability Database (NIST).
If a proxy server is used to access the internet, please specify the proxy server settings. If no proxy server settings are specified, the settings from the Xanitizer properties file will be used.
Log LevellogLevelSpecifies which logging level should be used for the Xanitizer run.
License Server Retry CountlicenseServerRetryCountSpecifies the number of attempts to get a license token from the license server.
Note: If the used Xanitizer license is a floating license it may happen that all tokens are in use or the connection to the license server is not available at startup. In such cases, no license token can be requested successfully from the license server to start Xanitizer and the headless process would terminate with a license error. Setting this parameter to a value greater than zero, Xanitizer attempts every minute to request a license token until the specified count has been reached. Setting this parameter to zero disables the repetition.
If the used Xanitizer license is a machine bound license, this parameter will be ignored.
Proxy Necessary?proxySettingsOnly in the cases that the Xanitizer license file is a floating license and the public Xanitizer license server is used or the OWASP Dependency Check database should be updated, Xanitizer needs access to the internet.
If a proxy server is used to access the internet, please specify the proxy server settings. If no proxy server settings are specified, the settings from the Xanitizer properties file will be used.
Proxy ServerproxyServerproxy server
Proxy PortproxyPortproxy port
Proxy UserproxyUserproxy user
Proxy PasswordproxyPasswordproxy password

TitleParameterDescription
Installation DirectoryinstallDirectoryPath to the Xanitizer installation directory.
License File (optional)licenseFileOptional path to the Xanitizer license file. If not specified, the license in the <USER_HOME>/.Xanitizer directory is used.
Run Security AnalysissecurityAnalysisConfigChoose whether the security analysis is disabled, is executed based on an existing Xanitizer configuration file, or is executed based on a root directory from where to construct a default configuration.
Configuration FileconfigFilePath to the Xanitizer configuration file to run a security analysis based on it.
Project Data Directory (optional)projectDataDirectoryOptional path where Xanitizer stores the project data. If not specified, a subdirectory of <USER_HOME>/.Xanitizer is used.
Change Build State on Missing Search PathshaltOnMissingSearchPathsSpecifies, whether the build should be marked as unstable or failed in the case of a missing search path or not. Marking the build as unstabel or failed can be used to detect if the analyzed project does not match the provided configuration any longer.
Set Build tobuildStatusOnMissingSearchPathsset build to
Change Build State on New FindingshaltOnNewFindingsSpecifies, whether the build should be marked as unstable or failed in the case of new findings with a critical rating. A finding is new if there is no corresponding finding in an earlier snapshot. A finding is critical if its rating is equal or higher than the specified threshold.
Set Build tobuildStateOnNewFindingsset build to
For New Findings With ThresholdnewFindingsRatingThresholdfor new findings with threshold
Change Build State on Any FindinghaltOnFindingsSpecifies, whether the build should be marked as unstable or failed in the case of findings with a critical rating. It does not matter if this finding is new or old. A finding is critical if its rating is equal or higher than the specified threshold.
Set Build tobuildStateOnFindingsset build to
For Any Finding With ThresholdfindingsRatingThresholdfor any finding with threshold
Generate ReportsgenerateReportsgenerate reports
Overview Report FilesoverviewReportOutputFilesList of report files containing an overview about the security vulnerabilities in the project. The file extension specifies the format. Admissible formats are “pdf”, “html”, “doc”, or “odt”.
Note: If more than one report file should be generated, separated the files by comma, semicolon, or line ending characters.
Findings List Report FilesfindingsListReportOutputFilesList of report files containing a list of all findings. The file extension specifies the format. Admissible formats are “pdf”, “html”, “doc”, “odt”, “xml”, or “csv”.
Note: If more than one report file should be generated, separated the files by comma, semicolon, or line ending characters.
... Export Only Problems?onlyProblemsInFindingsListReportIf enabled, only problem findings will be listed in the findings list report. By default, both problem findings and mere informational findings are listed.
... Export Details?generateDetailsInFindingsListReportIf enabled, all the details of a finding are written to the findings list report. Note that this flag is only relevant for reports with the file extensions “xml” or “html”.
Archive Reports?archiveReportsWhether all generated reports have to be copied into the subdirectory 'xanitizer' in the archive directory of the current build or not.
Create SnapshotcreateSnapshotSpecifies if a snapshot should be generated after parsing and analyzing the current version.
Note that the snapshot can be enhanced with an optional comment.
Snapshot Comment (optional)snapshotCommentsnapshot comment (optional)
Export ProjectexportProjectIf enabled, the analysis results are exported into a zip archive file in the export directory.
Note that the exported zip archive file can be protected by an optional password.
Export DirectoryexportDirectoryexport directory
Password (optional)exportPassphrasepassword (optional)
Root DirectoryrootDirectoryRoot directory from where to construct a default configuration to run a security analysis based on it.
Project Name (optional)projectNameOptional name of the project. If not specified, the simple name of the root directory is used as default.
Configuration File DirectoryconfigFileDirectoryOptional path to the newly created Xanitizer configuration file. If not specified, a subdirectory of <USER_HOME>/.Xanitizer is used.
Overwrite Configuration File?overwriteConfigFileSpecifies if, when the default Xanitizer configuration file is being created, an existing file should be overwritten. If a file with the same name already exists and this flag is false, the build will be marked as instable.
Update OWASP Dependency Check DB?updateOWASPDbSpecifies whether the OWASP Dependency Check repository should be updated or not.
Note that the OWASP Dependency Check is based on vulnerability data stored in a local repository. It is recommended to update the local OWASP Dependency Check repository on a regular basis. This update needs remote access to the US National Vulnerability Database (NIST).
If a proxy server is used to access the internet, please specify the proxy server settings. If no proxy server settings are specified, the settings from the Xanitizer properties file will be used.
Log LevellogLevelSpecifies which logging level should be used for the Xanitizer run.
License Server Retry CountlicenseServerRetryCountSpecifies the number of attempts to get a license token from the license server.
Note: If the used Xanitizer license is a floating license it may happen that all tokens are in use or the connection to the license server is not available at startup. In such cases, no license token can be requested successfully from the license server to start Xanitizer and the headless process would terminate with a license error. Setting this parameter to a value greater than zero, Xanitizer attempts every minute to request a license token until the specified count has been reached. Setting this parameter to zero disables the repetition.
If the used Xanitizer license is a machine bound license, this parameter will be ignored.
Proxy Necessary?proxySettingsOnly in the cases that the Xanitizer license file is a floating license and the public Xanitizer license server is used or the OWASP Dependency Check database should be updated, Xanitizer needs access to the internet.
If a proxy server is used to access the internet, please specify the proxy server settings. If no proxy server settings are specified, the settings from the Xanitizer properties file will be used.
Proxy ServerproxyServerproxy server
Proxy PortproxyPortproxy port
Proxy UserproxyUserproxy user
Proxy PasswordproxyPasswordproxy password