Some changes to command line runner for better usability

Added initial end user documentation

.gitignore

@@ -54,3 +54,4 @@ processrunner-bugtracker-root/target/
 processrunner-bugtracker-root/processrunner-bugtracker/dependency-reduced-pom.xml
 .scannerwork/
 sonar-project.properties
+processrunner-bugtracker-root/processrunner-bugtracker-doc/target/

processrunner-bugtracker-root/pom.xml

@@ -60,6 +60,7 @@
 		<module>processrunner-bugtracker-target-tfs</module>
 		<module>processrunner-bugtracker-target-archer</module>
 		<module>processrunner-bugtracker-target-octane</module>
+		<module>processrunner-bugtracker-doc</module>
 		<module>processrunner-bugtracker</module>
 	</modules>
 	<dependencyManagement>

processrunner-bugtracker-root/processrunner-bugtracker-common/src/main/java/com/fortify/processrunner/common/AbstractBugTrackerProcessRunnerConfiguration.java

@@ -41,19 +41,21 @@
  * @author Ruud Senden
  *
  */
-public class AbstractBugTrackerProcessRunnerConfiguration {
+public abstract class AbstractBugTrackerProcessRunnerConfiguration {
 	@Bean
 	public BugTrackerProcessRunner submitVulnerabilities() {
-		return new BugTrackerProcessRunner(ProcessRunnerType.SUBMIT);
+		return new BugTrackerProcessRunner(getSourceSystemName(), ProcessRunnerType.SUBMIT);
 	}
 
 	@Bean
 	public BugTrackerProcessRunner submitVulnerabilitiesAndUpdateIssueState() {
-		return new BugTrackerProcessRunner(ProcessRunnerType.SUBMIT_AND_UPDATE);
+		return new BugTrackerProcessRunner(getSourceSystemName(), ProcessRunnerType.SUBMIT_AND_UPDATE);
 	}
 
 	@Bean
 	public BugTrackerProcessRunner updateIssueState() {
-		return new BugTrackerProcessRunner(ProcessRunnerType.UPDATE);
+		return new BugTrackerProcessRunner(getSourceSystemName(), ProcessRunnerType.UPDATE);
 	}
+
+	protected abstract String getSourceSystemName();
 }

processrunner-bugtracker-root/processrunner-bugtracker-common/src/main/java/com/fortify/processrunner/common/BugTrackerProcessRunner.java

@@ -47,6 +47,7 @@
  *
  */
 public class BugTrackerProcessRunner extends ProcessRunner {
+	private final String sourceSystemName;
 	private final ProcessRunnerType type;
 	protected IProcessorSubmitVulnerabilities submitVulnerabilitiesProcessor;
 	protected IProcessorUpdateState updateStateProcessor;
@@ -55,7 +56,8 @@ public enum ProcessRunnerType {
 		SUBMIT, UPDATE, SUBMIT_AND_UPDATE
 	}
 
-	public BugTrackerProcessRunner(ProcessRunnerType type) {
+	public BugTrackerProcessRunner(String sourceSystemName, ProcessRunnerType type) {
+		this.sourceSystemName = sourceSystemName;
 		this.type = type;
 	}
 
@@ -65,19 +67,19 @@ public void postConstruct() {
 		case SUBMIT:
 			this.setProcessors(getSubmitVulnerabilitiesProcessor());
 			this.setEnabled(isSubmitVulnerabilitiesProcessorEnabled());
-			this.setDescription("Submit SSC vulnerabilities to "+getBugTrackerName());
+			this.setDescription("Submit "+sourceSystemName+" vulnerabilities to "+getBugTrackerName());
 			this.setDefault(isSubmitVulnerabilitiesProcessorEnabled() && !isUpdateBugTrackerStateProcessorEnabled());
 			break;
 		case SUBMIT_AND_UPDATE:
 			this.setProcessors(getUpdateStateProcessor(), getSubmitVulnerabilitiesProcessor());
 			this.setEnabled(isSubmitVulnerabilitiesProcessorEnabled() && isUpdateBugTrackerStateProcessorEnabled());
-			this.setDescription("Submit SSC vulnerabilities to "+getBugTrackerName()+" and update issue state");
+			this.setDescription("Submit "+sourceSystemName+" vulnerabilities to "+getBugTrackerName()+" and update issue state");
 			this.setDefault(isSubmitVulnerabilitiesProcessorEnabled() && isUpdateBugTrackerStateProcessorEnabled());
 			break;
 		case UPDATE:
 			this.setProcessors(getUpdateStateProcessor());
 			this.setEnabled(isUpdateBugTrackerStateProcessorEnabled());
-			this.setDescription("Update "+getBugTrackerName()+" issue state based on SSC vulnerability state");
+			this.setDescription("Update "+getBugTrackerName()+" issue state based on "+sourceSystemName+" vulnerability state");
 			this.setDefault(!isSubmitVulnerabilitiesProcessorEnabled() && isUpdateBugTrackerStateProcessorEnabled());
 			break;
 		}

processrunner-bugtracker-root/processrunner-bugtracker-doc/pom.xml

@@ -0,0 +1,82 @@
+<!-- (c) Copyright 2017 Hewlett Packard Enterprise Development LP Permission 
+	is hereby granted, free of charge, to any person obtaining a copy of this 
+	software and associated documentation files (the Software"), to deal in the 
+	Software without restriction, including without limitation the rights to 
+	use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
+	of the Software, and to permit persons to whom the Software is furnished 
+	to do so, subject to the following conditions: The above copyright notice 
+	and this permission notice shall be included in all copies or substantial 
+	portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY 
+	OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+	OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
+	IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
+	DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
+	ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+	DEALINGS IN THE SOFTWARE. -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<artifactId>processrunner-bugtracker-doc</artifactId>
+	<packaging>pom</packaging>
+	<parent>
+		<groupId>com.fortify.processrunner.bugtracker</groupId>
+		<artifactId>processrunner-bugtracker-root</artifactId>
+		<version>3.0</version>
+	</parent>
+	<organization>
+		<name>HPE Security Fortify</name>
+		<url>http://www8.hp.com/us/en/software-solutions/application-security/</url>
+	</organization>
+	<licenses>
+		<license>
+			<name>MIT License</name>
+			<url>http://www.opensource.org/licenses/mit-license.php</url>
+			<distribution>repo</distribution>
+		</license>
+	</licenses>
+	<developers>
+		<developer>
+			<id>rsenden</id>
+			<name>Ruud Senden</name>
+			<organization>HPE Security Fortify</organization>
+		</developer>
+	</developers>
+	<inceptionYear>2016</inceptionYear>
+	<description>This module provides the documentation for FortifyBugTrackerUtility.</description>
+	<url>https://github.com/HPFOD/FoDBugTrackerUtility</url>
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-site-plugin</artifactId>
+				<version>3.6</version>
+				<executions>
+					<execution>
+						<phase>package</phase>
+						<goals>
+							<goal>site</goal>
+						</goals>
+						<configuration>
+							<generateProjectInfo>false</generateProjectInfo>
+							<generateReports>false</generateReports>
+							<generateSitemap>false</generateSitemap>
+							<relativizeDecorationLinks>false</relativizeDecorationLinks>
+						</configuration>
+					</execution>
+				</executions>
+				<dependencies>
+					<dependency>
+						<groupId>org.apache.maven.doxia</groupId>
+						<artifactId>doxia-module-markdown</artifactId>
+						<version>1.7</version>
+					</dependency>
+				</dependencies>
+			</plugin>
+			<!-- <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-pdf-plugin</artifactId> 
+				<version>1.3</version> <executions> <execution> <id>pdf</id> <phase>package</phase> 
+				<goals> <goal>pdf</goal> </goals> <configuration> <outputDirectory>${project.reporting.outputDirectory}</outputDirectory> 
+				<includeReports>false</includeReports> </configuration> </execution> </executions> 
+				</plugin> -->
+		</plugins>
+	</build>
+</project>

processrunner-bugtracker-root/processrunner-bugtracker-doc/src/site/markdown/config-cli-default-values.md

@@ -0,0 +1,19 @@
+# Default values for command line options
+Every configuration file can contain a util:map bean with id `contextProperties`. This bean can contain a map of
+default values for one or more action-specific command line options. In this map, the key specifies the name of the 
+command line option, and the value specifies the corresponding default value. For example, you can use this approach
+for defining default values for source and target system URL's and credentials, such that these no longer need to be
+manually specified on the command line.
+
+For example, you could define default SSC URL and credentials using the following bean definition in your configuration
+file. Note that all example configuration files already contain a contextProperties bean, so you can just add the 
+entries to the existing bean definition.
+
+```xml
+<util:map id="contextProperties">
+	<entry key="SSCBaseUrl" value="https://fortify-ssc.mycompany.com/ssc"/>
+	<entry key="SSCAuthToken" value="688d24c3-a7ef-4ea1-b76f-5ee666393ebc"/>
+</util:map>
+```
+
+

processrunner-bugtracker-root/processrunner-bugtracker-doc/src/site/markdown/config-fod.md

@@ -0,0 +1,5 @@
+# FoD Configuration
+
+TODO; for now see the SSC configuration as this works somewhat similar
+
+

processrunner-bugtracker-root/processrunner-bugtracker-doc/src/site/markdown/config-ssc.md

@@ -0,0 +1,117 @@
+# SSC Configuration
+The SSC-related configuration in each configuration file consists of the following elements:
+
+- `<context:component-scan base-package="com.fortify.processrunner.ssc"/>`  
+  Automatically loads various components required for loading vulnerability data from SSC. This line
+  should always be present for configurations that load vulnerability data from SSC.
+- `<bean ... class="com.fortify.processrunner.ssc.processor.composite.SSCBugTrackerProcessorConfiguration">`
+  This bean definition should always be present, and contains various SSC-related configuration settings. For example:
+    - Vulnerability selection criteria
+    - Criteria for considering a vulnerability either open or closed
+    - How to store the submitted issue link in SSC
+    - Additional custom tags to be set, based on the current state of the submitted issue
+- One or more optional bean definitions for defining the application versions to be automatically processed, and how to generate
+  additional action-specific command line options (context properties) for each application version being processed.
+
+The following sections describe these configuration options in more detail.
+
+## Vulnerability selection criteria
+Vulnerabilities to be exported can be filtered either by SSC directly, or by FortifyBugTrackerUtility itself. Having the filtering 
+performed by SSC directly provides the best performance, as this reduces the amount of data returned by SSC. However, in some
+cases SSC-based filtering is not sufficient, so you can configure additional filters that will be evaluated by FortifyBugTrackerUtility
+on the data returned by SSC.
+
+The `com.fortify.processrunner.ssc.processor.composite.SSCBugTrackerProcessorConfiguration` bean provides
+the following properties to configure vulnerability filters:
+
+- `filterStringForVulnerabilitiesToBeSubmitted`  
+  This string is sent to SSC as-is to allow SSC to filter the list of vulnerabilities. The syntax for this search string is
+  the same as for the 'Search issues' box in the SSC web interface. As such, you can test your filter string in SSC itself
+  to verify that it returns the correct subset of issues. Please refer to the SSC search box syntax guide for more details.
+  The default configuration files use `analysis:exploitable` as the SSC filter string, meaning that only vulnerabilities
+  for which the Analysis custom tag has been set to 'Exploitable' will be submitted to the external system.
+- `regExFiltersForVulnerabilitiesToBeSubmitted`  
+  After SSC has returned the list of vulnerabilities to FortifyBugTrackerUtility, this list of vulnerabilities can optionally
+  be filtered further using regular expressions. This property takes a map with vulnerability field names as keys, and the
+  corresponding regular expressions to be matched as values. The default configuration files do not perform any regular expression 
+  based filtering.
+
+## Vulnerability open/closed expression
+For bug state management purposes, FortifyBugTrackerUtility needs to know whether a vulnerability is open or closed. This is
+determined by evaluating the expression that is configured through the `isVulnerabilityOpenExpression` property on the
+`com.fortify.processrunner.ssc.processor.composite.SSCBugTrackerProcessorConfiguration` bean. In the
+sample configuration files, vulnerabilities that are not suppressed and not removed are considered as 'open', all other vulnerabilities
+will be considered as 'closed'.
+
+## Storing the link to the submitted issue
+FortifyBugTrackerUtility needs to keep track of which SSC vulnerabilities have been submitted to which issue in the external
+system. This information is used for bug state management, as well as to avoid vulnerabilities from being submitted to the
+external system multiple times. 
+
+The only exceptions (at this moment) are the following integrations:
+
+- SSC to File export; all relevant vulnerabilities will be exported to the file on each invocation (independent of whether 
+  they have been exported before), and the file export does not support bug state management
+- Submitting vulnerabilities through native SSC bug tracker integrations; the native SSC bug tracker integration will
+  store information about the submitted issue for each vulnerability
+
+The SSC implementation can store the issue link in two ways; either in a custom tag of type 'Text', or as a native SSC bug tracker
+link. Both can be configured through properties on the `com.fortify.processrunner.ssc.processor.composite.SSCBugTrackerProcessorConfiguration` bean:
+
+- `bugLinkCustomTagName`  
+  This property allows you to specify the custom tag name in which the issue link should be stored. You will need to add
+  a custom tag with this name in SSC, and assign it to all application versions for which you want to use FortifyBugTrackerUtility.
+- `addNativeBugLink`  
+  This property can be set to 'true' if you want to store the issue link as a native SSC bug link, allowing users to click
+  the 'bug' icon in SSC to navigate to the corresponding issue in the external system. This option requires to have the
+  'Add Existing Bugs' native SSC bug tracker integration to be installed, and configured on all application versions for which
+  you want to use FortifyBugTrackerUtility.
+
+Note that SSC only allows one native bug tracker integration for each application version. When using the 'addNativeBugLink'
+approach, you will not be able to use any other native SSC bug tracker integration. If you want users to be able to also
+manually submit issues to a bug tracker through the native SSC integration, or if you want to submit issues to multiple 
+external systems, you should use the custom tag based approach.   
+
+## Bi-directional sync
+Optionally, the SSC implementation can make information about the current state of a submitted issue in an external system
+visible in SSC through custom tags. For example, this allows SSC users to see whether the submitted issue has state 'In Progress'
+or 'Closed'. This information can be stored in SSC custom tags.
+
+Custom tag contents can be configured through the `extraCustomTags` on the `com.fortify.processrunner.ssc.processor.composite.SSCBugTrackerProcessorConfiguration` bean. This property
+takes a map with custom tag name as the key, and an expression as the value. After submitting new issues, or during bug state
+management, FortifyBugTrackerUtility will evaluate the given expression(s) and update the custom tag values accordingly. 
+
+The fields that can be used in the expression is dependent on the target system being used; see the examples for more information.
+Note that FortifyBugTrackerUtility will silently ignore any custom tags that have not been defined in SSC, or that have not
+been assigned to the current application version. 
+
+## Processing multiple application versions
+The most straight-forward way for invoking FortifyBugTrackerUtility is by specifying an SSC application version on the command
+line, together with information about the location/project of the external system to which the vulnerabilities need to be 
+exported. For example, when exporting vulnerabilities to JIRA, you can specify both the SSC application version and corresponding 
+JIRA project key as command line options. 
+
+However, if you have a lot of application versions, it may become cumbersome to separately invoke FortifyBugTrackerUtility
+for each individual application version. Therefore FortifyBugTrackerUtility allows you to configure a mapping between
+SSC application versions and corresponding target system command line options. This mapping can either be hard-coded in
+the configuration file, or you can configure a mapping based on application version attributes:
+
+- A bean with class `com.fortify.processrunner.ssc.appversion.SSCApplicationVersionAttributeFilterAndMapper`
+  allows you to map application version attribute values to corresponding action-specific command line options. You can configure both 
+  `requiredAttributeMappings` and `optionalAttributeMappings` on this bean. Both properties can be configured with a 
+  map, where the key specifies the SSC application version attribute name, and the value specifies the corresponding command line
+  option to be set based on the value of this application version attribute.   
+  For example, you could have an application version attribute named 'Jira Project Key' that is automatically mapped to the
+  'JiraProjectKey' command line option. If you run FortifyBugTrackerUtility for a specific SSC application version, it will
+  automatically add the JiraProjectKey option based on the corresponding application version attribute. If you run 
+  FortifyBugTrackerUtility without specifying any SSC application version, it will automatically process all application versions
+  for which all application version attributes specified through `requiredAttributeMappings` have a non-empty value.
+
+- A bean with class `com.fortify.processrunner.ssc.appversion.SSCApplicationVersionNameFilterAndMapper`
+  allows you to hard-code a mapping between application version names and corresponding command line options. On this bean,
+  you can configure a property names `applicationVersionNameMappings` with a map, where the key specifies a regular
+  expression to match [application name]:[version name], and the value specifies a comma-separated list of command line options
+  together with their values. 
+
+
+