Conviso Azure Sync Task

Overview

The Conviso Azure Sync Task is an Azure Pipelines extension designed to seamlessly integrate your CI/CD pipelines with the Conviso Platform. This task enables you to trigger synchronization with external security tools such as Checkmarx, Dependency Track, and Fortify, ensuring that your project's security assessments are always up-to-date.

Features

• Easy Integration: Connect your Azure Pipelines to the Conviso Platform effortlessly.
• Support for Multiple Scanners: Compatible with various external tools like Fortify, Checkmarx, and Dependency Track.
• Build and Release Compatibility: Can be used in both build and release pipelines.
• Secure Authentication: Utilizes API keys to securely communicate with the Conviso GraphQL endpoint.

Inputs

1. Conviso API Key

• Name: API_KEY
• Type: string
• Required: Yes
• Description:
  • The API Key used to authenticate requests to the Conviso GraphQL endpoint.

2. Project ID in the External Tool

• Name: PROJECT_ID
• Type: string
• Required: No
• Description:
  • The Project ID from the external scanner (e.g., Fortify, Checkmarx). This associates the sync with a specific project in the external tool.

3. Integration Name

• Name: INTEGRATION
• Type: string
• Required: Yes
• Description:
  • The name of the integration as defined in Conviso's GraphQL schema (e.g., CONVISO_SCANNER). This specifies which external tool to sync with.

4. Company ID

• Name: COMPANY_ID
• Type: string
• Required: Yes
• Description:
  • The Company ID within the Conviso Platform. This links the sync to your organization's account on Conviso.

5. Repository URL

• Name: REPOSITORY_URL
• Type: string
• Required: No
• Default: the pipeline's Build.Repository.Uri
• Description:
  • The repository this scan belongs to (e.g., https://github.com/org/repo). When provided, the Asset in Conviso Platform is treated as a repository, and the BRANCH below is recorded as one of its branches.
  • Note: the Asset is then named after the repository (org/repo) instead of the project name reported by the scanner.

6. Branch

• Name: BRANCH
• Type: string
• Required: No
• Default: the branch that triggered the build
• Description:
  • The branch this scan covers, so findings land on the branch they came from.
  • Only takes effect together with REPOSITORY_URL. Sent on its own, Conviso Platform ignores it — the task logs a warning when it sees that combination.
  • In pull request builds the source branch is used, not the temporary merge ref.

Usage

To incorporate the Conviso Azure Sync Task into your Azure Pipeline, follow these steps:

1. Add the Task to Your Pipeline:

   • In your pipeline YAML file or via the Azure Pipelines UI, add the Conviso Azure Sync Task to the desired stage.

2. Configure the Inputs:

   • Conviso API Key: Enter your Conviso API key to authenticate the sync request.
   • Project ID in the External Tool: (Optional) Provide the Project ID from your external scanning tool if applicable.
   • Integration Name: Specify the integration name as per Conviso's GraphQL schema (e.g., CONVISO_SCANNER).
   • Company ID: Enter your Company ID from the Conviso Platform to associate the sync with your organization.

3. Run the Pipeline:

   • Execute your pipeline. The task will initiate a sync with the Conviso Platform, ensuring that the latest scan results from your external tools are integrated into your project's security overview.

Example

Below is an example of how to configure the Conviso Azure Sync Task in a YAML pipeline:

- task: convisoAzureSyncTask@1
  inputs:
    API_KEY: '$(CONVISO_API_KEY)'          # Use a secret variable, not a literal key
    PROJECT_ID: 'external-tool-project-id' # Optional
    INTEGRATION: 'CONVISO_SCANNER'
    COMPANY_ID: 'your-company-id'
    REPOSITORY_URL: 'https://github.com/org/repo' # Optional, defaults to this build's repository
    BRANCH: 'main'                                # Optional, defaults to this build's branch

Store the API key in a secret pipeline variable. Azure's task library writes every input to the build log when system.debug is enabled, so a key pasted literally into the YAML will appear there in plain text.

Versioning

• Current Version: 1.1.0

Author

Developed by Conviso Application Security.

Category

Utility

Support

For assistance or to report issues, please contact the Conviso Application Security team or visit our documentation.

Ensure that you have the necessary permissions and API keys before configuring the Conviso Azure Sync Task. Proper configuration guarantees secure and efficient synchronization between your Azure Pipelines and the Conviso Platform.