Xanitizer » Integration » Command Line

Command Line Interface

Introduction

Xanitizers command line interface enables the integration of Xanitizers security analysis in any kind of build system to detect vulnerabilities in your applications.

The command line interface can be used to do the following actions in a single command line call or in separate command line calls:

  • Run Security Analysis to run a Xanitizer security analysis followed by the optional steps “export project”, “create report”, and “create snapshot”.
  • Create Report to generate reports with the results of a previous 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 to update the internal database of the OWASP Dependency Check, which is used to detect external libraries with known vulnerabilities.

Please note that “create snapshot” call has to be executed after all “create report” calls to show differences between the current version and the latest snapshot for trend monitoring in the reports. The “export project” call has to be executed after the “create snapshot” call so that the exported archive contains the snapshot, too.

Compatibility

Xanitizer Version
Task≥ 4.3.14.3< 4.3
Run Security AnalysisIcon check greenIcon check greenIcon check green
Create ReportIcon check greenIcon check green
Create SnapshotIcon check greenIcon check green
Export ProjectIcon check greenIcon check green
Update OWASP Dependency Check RepositoryIcon check greenIcon check green
Install License FileIcon check green

Download and Installation

The Xanitizer command line interface is part of the Xanitizer installation itself and no further download is necessary.

In Xanitizer's installation directory, there is an executable called <code>XanitizerHeadless</code> or <code>XanitizerHeadless.exe</code>. This executable is used for running Xanitizer without GUI interaction.

Single Command Line Call

If all parameters are set to do all steps in a single command line call, the execution order of the steps is: Install License File, Update OWASP Dependency Check Repository, Run Security Analysis, Create Report, Create Snapshot, and Export Project.

___XanitizerMessage___{<status message>}___XanitizerMessage___ status messages are printed to the standard output stream, when no exception occurs:

Status MessageDescription
RESULT:Batch run completed sucessfullyOnly when the call finished successfully
MISSING_SEARCH_PATHS:<details>Only when haltOnMissingSearchPaths=true and the condition is fulfilled
NEW_FINDINGS:<details>Only when haltOnNewFindings=true and the condition is fulfilled
FINDINGS:<details>Only when haltOnFindings=true and the condition is fulfilled

A description of all parameters can be found here.

Run Security Analysis

This call runs a Xanitizer security analysis followed by the optional steps “export project”, “create report”, and “create snapshot”. The security analysis can either be run for a specific Xanitizer configuration file or for a root directory with a default configuration.

XanitizerHeadless configFile="path to the Xanitizer configuration file"
XanitizerHeadless rootDir="path to the root directory of the project"

___XanitizerMessage___{<status message>}___XanitizerMessage___ status messages are printed to the standard output stream, when no exception occurs:

Status MessageDescription
RESULT:Batch run completed sucessfullyOnly when the call finished successfully
MISSING_SEARCH_PATHS:<details>Only when haltOnMissingSearchPaths=true and the condition is fulfilled
NEW_FINDINGS:<details>Only when haltOnNewFindings=true and the condition is fulfilled
FINDINGS:<details>Only when haltOnFindings=true and the condition is fulfilled

A description of all parameters can be found here.

Create Report

This call generates reports with the results of a previous Xanitizer security analysis.

XanitizerHeadless noAnalysis=true configFile="path to the Xanitizer configuration file" overviewReportOutputfile="path to the target overview report file"

___XanitizerMessage___{RESULT:Batch run completed sucessfully}___XanitizerMessage___ is printed to the standard output stream, only when the call finished successfully.

A description of all parameters can be found here.

Create Snapshot

This call creates a new snapshot of a Xanitizer project. Xanitizer can keep analysis results in a so called snapshot, and thus is able to compare results for different versions.

XanitizerHeadless noAnalysis=true configFile="path to the Xanitizer configuration file" createSnapshot=true snapshotComment="version x.y.z"

___XanitizerMessage___{RESULT:Batch run completed sucessfully}___XanitizerMessage___ is printed to the standard output stream, only when the call finished successfully.

A description of all parameters can be found here.

Export Project

This call exports the whole Xanitizer project with all snapshots and security analysis results as an optionally password protected single zip archive. This archive can be imported on another machine or by another user.

XanitizerHeadless noAnalysis=true configFile="path to the Xanitizer configuration file" exportDirectory="path to the export directory" exportPasswort="optional password"

___XanitizerMessage___{RESULT:Batch run completed sucessfully}___XanitizerMessage___ is printed to the standard output stream, only when the call finished successfully.

A description of all parameters can be found here.

Install License File

This call installs or updates a license file to run Xanitizer. If the license is a floating license and a proxy server is necessary to access the license server, please specify the proxy server settings. If no settings are specified, the settings from the Xanitizer properties file will be used.

XanitizerHeadless licenseFile="path to the license file"

___XanitizerMessage___{RESULT:Batch run completed sucessfully}___XanitizerMessage___ is printed to the standard output stream, only when the call finished successfully.

A description of all parameters can be found here.

Update OWASP Dependency Check Repository

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. To update the repository the call needs remote access to the National Vulnerability Database (NIST). If a proxy server is used to access the internet, please specify the proxy server settings. If no settings are specified, the settings from the Xanitizer properties file will be used.

XanitizerHeadless updateOwaspDependencyCheckRepository=true

___XanitizerMessage___{RESULT:Batch run completed sucessfully}___XanitizerMessage___ is printed to the standard output stream, only when the call finished successfully.

A description of all parameters can be found here.

Parameters

Parameters have to be specified in key-value-pair syntax, in the form <key>=<value>. Please note, that values with spaces have to be quoted like "value with space".

Either a configuration file, a root directory, a license file, or the parameter 'updateOwaspDependencyCheckRepository' must be specified in order to run XanitizerHeadless.

There are the following parameters for the Xanitizer command line call:

ParameterDefault ValueDescription
configFile<empty>The path to the Xanitizer configuration file of the project that should be analyzed.
Either this parameter or the parameter 'rootDirectory' must be specified, but not both.
rootDirectory<empty>The root directory, to be used for default set-ups.
Either this parameter or the parameter 'configFile' must be specified, but not both.
projectName<empty>The project name that should be used.
Only relevant if the parameter 'rootDirectory' is specified.
If not given, the simple name of the root directory is used.
configFileDirectory<empty>The directory where to put the generated configuration file.
Only relevant if the parameter 'rootDirectory' is specified.
If not given, the configuration file is generated in a subdirectory of the user's .Xanitizer directory.
overwriteConfigFilefalseBoolean flag specifying if an existing config file is to be overwritten.
Only relevant if the parameter 'rootDirectory' is specified.
projectDataDirectory<empty>Xanitizer's project data directory, if it is not the default one in <HOME>/.Xanitizer or the one specified in that default directory.
createSnapshotfalseBoolean flag specifying whether a snapshot should be created parsing and analyzing the current version or not.
snapshotComment<empty>Optional comment added to the newly created snapshot.
Only relevant if the parameter 'createSnapshot' is true.
overviewReportOutputFile<empty>The output location of the overview report.
This has to be either a file or the parameter has to be undefined or empty if no overview report should be written.
Allowed file extensions are: PDF, HTML, DOCX.
findingsListReportOutputFile<empty>The output location of the findings list report.
This has to be either a file or the parameter has to be undefined or empty if no findings list report should be written.
Allowed file extensions are: PDF, HTML, DOCX, XML, CSV.
onlyProblemsInFindingsListReportfalseBoolean flag specifying if only findings with problem classifications are written to the findings list report.
generateDetailsInFindingsListReportfalseBoolean flag specifying if all the details of a finding are written to the findings list report.
Note: Only relevant if the file extension of the parameter 'findingsListReportOutputFile' is XML or HTML.
exportDirectory<empty>The output directory of the project export.
Note: If the parameter is undefined or an empty string, the project is not exported.
exportPassphrase<empty>The pass phrase for the project export.
The parameter is only used if an export directory is set.
If the parameter is not set or empty, the exported project is not encrypted.
haltOnMissingSearchPathsfalseBoolean flag specifying whether the task should fail if there are search paths configured that do not exist anymore.
haltOnNewFindingsfalseBoolean flag specifying whether the task should fail if there are *NEW* findings with a rating equal or higher than the value defined for newFindingsRating.
newFindingsRatingThreshold5A rating value. Only used if haltOnNewFindings is set.
haltOnFindingsfalseBoolean flag specifying whether the task should fail if there are findings with a rating equal or higher than the value defined for findingsRating.
findingsRatingThreshold5A rating value. Only used if haltOnFindings is set.
licenseFile<empty>The path to the Xanitizer license file.
Note: If the license is a floating license and a proxy server is used to access the license server, please specify the proxy server settings.
If no settings are specified, the settings from the Xanitizer properties file will be used.
updateOwaspDependencyCheckRepositoryfalseBoolean flag specifying whether the OWASP Dependency Check repository should be updated or not.
Note: 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 via remote access to the National Vulnerability Database (NIST).
If a proxy server is used to access the internet, please specify the proxy server settings otherwise the settings from the Xanitizer properties file will be used.
proxyServer<empty>Optional proxy server to access the internet to update the OWASP Dependency Check repository or to request a license token from the public license server in case of a floating license via a proxy.
Note: If no settings are specified, the settings from the Xanitizer properties file will be used.
proxyPort-1Optional proxy server port to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
proxyUser<empty>Optional proxy server user name to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
proxyPassword<empty>Optional proxy server user password to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
logLevelINFOThe logging level to be used when running Xanitizer.
Values: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.
licenseServerRetryCount0Number of attempts to get a license token from the license server.
Note: If the used Xanitizer license is a machine bound license, this parameter will be ignored.
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.
noAnalysisfalseBoolean flag specifying if an analysis should not be executed for the config file or project root directory.
Note: This is only relevant for separate report generation, snapshot generation and project export.

Parameters have to be specified in key-value-pair syntax, in the form <key>=<value>. Please note, that values with spaces have to be quoted like "value with space".

Either a configuration file, a root directory, a license file, or the parameter 'updateOwaspDependencyCheckRepository' must be specified in order to run XanitizerHeadless.

There are the following parameters for the Xanitizer command line call:

ParameterDefault ValueDescription
configFile<empty>The path to the Xanitizer configuration file of the project that should be analyzed.
Either this parameter or the parameter 'rootDirectory' must be specified, but not both.
rootDirectory<empty>The root directory, to be used for default set-ups.
Either this parameter or the parameter 'configFile' must be specified, but not both.
projectName<empty>The project name that should be used.
Only relevant if the parameter 'rootDirectory' is specified.
If not given, the simple name of the root directory is used.
configFileDirectory<empty>The directory where to put the generated configuration file.
Only relevant if the parameter 'rootDirectory' is specified.
If not given, the configuration file is generated in a subdirectory of the user's .Xanitizer directory.
overwriteConfigFilefalseBoolean flag specifying if an existing config file is to be overwritten.
Only relevant if the parameter 'rootDirectory' is specified.
projectDataDirectory<empty>Xanitizer's project data directory, if it is not the default one in <HOME>/.Xanitizer or the one specified in that default directory.
createSnapshotfalseBoolean flag specifying whether a snapshot should be created parsing and analyzing the current version or not.
snapshotComment<empty>Optional comment added to the newly created snapshot.
Only relevant if the parameter 'createSnapshot' is true.
overviewReportOutputFile<empty>The output location of the overview report.
This has to be either a file or the parameter has to be undefined or empty if no overview report should be written.
Allowed file extensions are: PDF, HTML, DOCX.
findingsListReportOutputFile<empty>The output location of the findings list report.
This has to be either a file or the parameter has to be undefined or empty if no findings list report should be written.
Allowed file extensions are: PDF, HTML, DOCX, XML, CSV.
onlyProblemsInFindingsListReportfalseBoolean flag specifying if only findings with problem classifications are written to the findings list report.
generateDetailsInFindingsListReportfalseBoolean flag specifying if all the details of a finding are written to the findings list report.
Note: Only relevant if the file extension of the parameter 'findingsListReportOutputFile' is XML or HTML.
exportDirectory<empty>The output directory of the project export.
Note: If the parameter is undefined or an empty string, the project is not exported.
exportPassphrase<empty>The pass phrase for the project export.
The parameter is only used if an export directory is set.
If the parameter is not set or empty, the exported project is not encrypted.
haltOnMissingSearchPathsfalseBoolean flag specifying whether the task should fail if there are search paths configured that do not exist anymore.
haltOnNewFindingsfalseBoolean flag specifying whether the task should fail if there are *NEW* findings with a rating equal or higher than the value defined for newFindingsRating.
newFindingsRatingThreshold5A rating value. Only used if haltOnNewFindings is set.
haltOnFindingsfalseBoolean flag specifying whether the task should fail if there are findings with a rating equal or higher than the value defined for findingsRating.
findingsRatingThreshold5A rating value. Only used if haltOnFindings is set.
licenseFile<empty>The path to the Xanitizer license file.
Note: If the license is a floating license and a proxy server is used to access the license server, please specify the proxy server settings.
If no settings are specified, the settings from the Xanitizer properties file will be used.
updateOwaspDependencyCheckRepositoryfalseBoolean flag specifying whether the OWASP Dependency Check repository should be updated or not.
Note: 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 via remote access to the National Vulnerability Database (NIST).
If a proxy server is used to access the internet, please specify the proxy server settings otherwise the settings from the Xanitizer properties file will be used.
proxyServer<empty>Optional proxy server to access the internet to update the OWASP Dependency Check repository or to request a license token from the public license server in case of a floating license via a proxy.
Note: If no settings are specified, the settings from the Xanitizer properties file will be used.
proxyPort-1Optional proxy server port to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
proxyUser<empty>Optional proxy server user name to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
proxyPassword<empty>Optional proxy server user password to access the National Vulnerability Database (NIST) to update the OWASP Dependency Check repository via a proxy.
logLevelINFOThe logging level to be used when running Xanitizer.
Values: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.
licenseServerRetryCount0Number of attempts to get a license token from the license server.
Note: If the used Xanitizer license is a machine bound license, this parameter will be ignored.
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.
noAnalysisfalseBoolean flag specifying if an analysis should not be executed for the config file or project root directory.
Note: This is only relevant for separate report generation, snapshot generation and project export.

Examples

The Xanitizer tutorial uses the OWASP WebGoat project, which is part of each Xanitizer installation. WebGoat is a deliberately insecure web application maintained by OWASP designed to teach web application security lessons. The folder “scripts” of the Xanitizer installation contains some examples shell scripts which can be use to automatically detect security vulnerabilities inside the WebGoat project.