Feature/bb post webhooks (#694) (#700)

checkmarx-ltd · Apr 10, 2021 · e1034fc · e1034fc
1 parent 64ae217
commit e1034fc
Show file tree

Hide file tree

Showing 34 changed files with 1,534 additions and 597 deletions.
diff --git a/docs/Delete-Branch.md b/docs/Delete-Branch.md
@@ -1,7 +1,7 @@
 
 ### Deleting CxSAST Project upon Branch Deletion
 
-xFlow is able to create a new CxSAST project when initiating scan, if the project doesn't exist yet.
+CxFlow is able to create a new CxSAST project when initiating scan, if the project doesn't exist yet.
 
 When working with CxFlow in web service mode and using webhook events to trigger CxSAST scan, CxFlow will create a new CxSAST project for each SCM feature branch which open a pull request into scanned branch. This might cause flood of projects on CxSAST for feature branch and unexpected consumption of licenses.
 
@@ -59,4 +59,10 @@ if the user delete feature-branch manually without complete pull request - CxFlo
 [[/Images/ADO_delete_branch.png|github delete webhook event]]
 
 
+## Bitbucket Server
+
+Bitbucket Server will delete a SAST project **only when using the Post Webhooks plugin**.  The current implementation is limited in that:
+
+* Project delete not work if using Config-As-Code given the settings for team and/or project name have been deleted from the branch.
+* Project delete will work if the project name is calculated or scripted and the team assigned to the project matches the default team in the CxFlow YAML configuration.
 
diff --git a/docs/Frequently-Asked-Questions.md b/docs/Frequently-Asked-Questions.md
@@ -59,6 +59,7 @@ The table below lists all the supported integrations, features and states the re
 |        | Pipelines |               |
 |        | Work Items |               |
 | **BitBucket** | WebHooks | >= 1.4.3 |
+|               | Post Webhooks (plugin) | >= 3.14.18 |
 |               | Merge Requests Scanning |         |
 |               | Pull Events |          |
 |               | Issue Tracker |         |

diff --git a/docs/Images/bb_multi_scm.png b/docs/Images/bb_multi_scm.png
diff --git a/docs/Images/postwebhooks_password.png b/docs/Images/postwebhooks_password.png
diff --git a/docs/Prerequisites-and-Requirements.md b/docs/Prerequisites-and-Requirements.md
@@ -21,7 +21,7 @@ The following applications are required:
 * Self-signed certificates must be explicitly trusted by installing them into the Java JRE trustsore (cacerts)
 * To enable automated scanning orchestration and project creation (WebHook Web Service integration), the source repository must be capable of supporting WebHooks, specifically:
   * GitLab
-  * BitBucket Servr/Cloud
+  * BitBucket Server/Cloud
   * GitHub
   * Azure DevOps
   * TFS

diff --git a/docs/SCM-Multi-instance.md b/docs/SCM-Multi-instance.md
@@ -1,5 +1,5 @@
 
-Cx-Flow supports multiple SCM’s accounts: GitHub, GitLab & Azure Devops (instances)
+Cx-Flow supports multiple SCM’s accounts: BitBucket, GitHub, GitLab & Azure Devops (instances)
 
 [[/Images/github_multi_instance.png|thresholds screenshot]]
 
@@ -23,8 +23,17 @@ In order to override the default SCM’s properties with an optional properties,
 [[/Images/multi_instance_url_payload.png|thresholds screenshot]]
 
 * In this example we are settings the scm-instance parameter key with **‘instance2’** value.
-* In case the ‘instance2’ name do exists on the configuration file, the default SCM configuration will be overridden with the ‘instance2’ properties.
-* In case a not exists scm-instance is defined an exception will be thrown.
-* In case none scm-instance was defined as a webhook query parameter, the default configuration will be used.
+* If the optional SCM ‘instance2’ configuration is found, the default SCM configuration will be overridden with the ‘instance2’ properties.
+* If the specified scm-instance is not defined, an exception will be thrown.
+* The default SCM configuration is used if the **scm-instance** query parameter is not provided.
 
 
+## BitBucket Multi-Instance Configuration
+
+Configuring SCM multi-instance with BitBucket has a slightly different requirement for configuration.
+
+The default BitBucket SCM configuration uses the **url** and **api-path** configuration options to access the API and form URLs that reference the repository.  Using SCM multi-instance would generally imply that the **url** configuration option would be overridden.  For BitBucket, it is required that the **api-url** configuration option is also provided in each optional SCM configuration.  
+
+The **api-url** configuration option must have the full URL for the BitBucket REST API.  The image below shows a default BitBucket server configuration with an optional SCM configuration for a separate on-premise BitBucket server and BitBucket cloud.
+
+[[/Images/bb_multi_scm.png|BitBucket multi-SCM configuration]]
diff --git a/docs/WebHook-Registration.md b/docs/WebHook-Registration.md
@@ -67,13 +67,39 @@ WebHook Events
   * When registering Push Events, use http://<cxflow>/ado/push 
 **Note** Only Push/Pull Create events are currently supported. Token should be sent as Basic Authentication Header.
 
+## <a name="bitbucketcloud">Bitbucket Cloud</a>
+Bitbucket cloud does not support a shared key/secret for digitally signing and verifying the request, so we require the token parameter to be passed:
+<br> example: http://cxflow?token=XXXXX
+<br>XXXX is the pre-shared token value set for `bitbucket.webhook-token` that the CxFlow webservice is using to validate and authenticate requests.
+
+When configuring the API token in CxFlow YML config using the `bitbucket.token` configuration value, the expected format is `<userid>:<access token>`. 
+
+
 ## <a name="bitbucketserver">Bitbucket Server</a>
-Similar to cloud, but requires a shared secret field, which is used to sign/authenticate the request.
 
-## <a name="bitbucketcloud">Bitbucket Cloud</a>
-Bitbucket cloud does not support a shared key/secret for digitally signing and verifying the request, so we require the token paramater to be passed:
-<br> example: http://cxflow?token=XXXXX)
-<br>XXXX is the pre-shared token that the CxFlow webservice is using to validate and authenticate requests.
-<br>When configuring the API token in CxFlow YML config, the <userid>:<access token> is the expected value.
+### Native Webhooks
+Similar to cloud, but requires a shared secret field, which is used to sign/authenticate the request.  The `token` webhook URL parameter used in Bitbucket Cloud is therefore not necessary.
+
+### Post Webhooks
+The [Post Webhooks plugin](https://marketplace.atlassian.com/apps/1215474/post-webhooks-for-bitbucket?hosting=server&tab=overview) for Bitbucket server is supported by appending the path `/postwebhook` to the CxFlow webhook URL in the Post Webhooks configuration.
+
+example: `http://cxflow/postwebhook`
+
+
+Post Webhooks allows global, per-project and per-repository webhook configurations.  The native Bitbucket Server webhook configurations are not as flexible.  Using Config As Code with a single global webhook configuration may be an effective way to deploy CxFlow to your development organization.
+
+
+
+The Post Webhooks plugin does not support signature authentication, so one of the following two options must be used to present the shared key to CxFlow:
+
+* Use the `token` URL parameter<br>
+example: `http://cxflow/postwebhook?token=XXXXX`<br><br>
+
+
+* Use the "Basic Authentication" feature in the Post Webhooks configuration.  The username can be omitted from the configuration; the password should be configured to match the `bitbucket.webhook-token` configured value.  Example:
+
+[[/Images/postwebhooks_password.png | Post Webhooks token config]]
+
+