| Table of Contents |
|---|
| Info | ||
|---|---|---|
| ||
This plugin is an Open Source project in Github and is offered "As Is". This means that it does not have official support from Kiuwan or Idera. Any support provided is based on our best effort. There is no SLA associated with this plugin or any of the incumben components, such as Microsoft Azure Devops environment, Team Foundation Server or the Agents executing the pipelines. |
How to get it
The extension is published in the Microsoft Visual Studio Marketplace. You can install it in your Azure DevOps account directly from there, or download it to install it in your TFS server 2017 (15.0.*) or higher (Azure DevOps Server now).
| Info | ||
|---|---|---|
| ||
The minimum TFS version supported is 2015 Update 2 (14.95.25122.0). For TFS 2005 there may be some minor supporting features of the extension that may not fully work. This does not affect the automation of tasks and displaying the Kiuwan results after the builds. The extension is still fully operational. |
What you need to know before installing it
This extension works with the Kiuwan Application Security platform in the cloud. So you need a Kiuwan account to use it.
The included build tasks will work on TFS Windows, Linux or MacOS agents and Azure DevOps private or hosted Windows, Linux, and MacOS agents.
For Azure DevOps Server and Azure DevOps private agents, you don't need to pre-install the Kiuwan Local Analyzer (KLA). The first time you run a Kiuwan task the KLA will be downloaded and installed in the agent's tools directory (in a Windows host it is typically C:\agent\_work\_tool) that ran the Kiuwan build task. Next time the same agent runs a Kiuwan task it will use that installation.
If there are any issues with the KLA installation or you need to remove it to have fresh install in the next task run, go to that directory and just delete the KiuwanLocalAnalyzer folder found there.
For hosted agents (that are provisioned dynamically), the KLA is downloaded and installed every time a Kiuwan task runs.
What you get with the extension
A service endpoint type and 2 build tasks. One to run Kiuwan baseline analyzes to analyse your releases. And one to run Kiuwan delivery analyses for your change or pull requests.
New Service Endpoint type
To connect to the Kiuwan platform form TFS/Azure DevOps. You can define a new service endpoint to the Kiuwan platform. You just need to select the Kiuwan Platform service connection type from the "New Service Endpoint" pulldown in the TFS/Azure DevOps Services configuration tab.
Then you just configure a name for the Kiuwan connection and your Kiuwan account credentials to use to connect to Kiuwan.
Additionally, if you have configured your Kiuwan account to use SSO authentication you have to configure your Kiuwan Domain ID provided by your Kiuwan administrator.
| Info | ||
|---|---|---|
| ||
For any TFS 2015 version, You have to set the Kiuwan Domain ID to 0 (number zero) even is your Kiuwan account is not using SSO. This is a short-coming of this TFS version that requires all fields in the endpoint configuration to be set. The side effect of this is that the combo with the available applications in your Kiuwan account will be empty. Just type the name manually in this case. |
Proxy Support
The plugin supports those environments where the Azure Agent (the piece of software executing the pipelines) is installed and configured in a local environment behind a corporate proxy.
The proxy support is for web proxy with or without basic authentication, like the Kiuwan Local Analyzer is currently providing.
To see more information, see Configuration for Networks with Proxy or Local Authentication
The Microsoft official documentation about how to configure the Agent to run behind a proxy is located at the following URL:
https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/proxy?view=azure-devops&tabs=windows
The Kiuwan plugin takes the proxy information from the Agent configuration automatically, so no additional operation is needed in the plugin or on server side.
Build Tasks
The extension adds 2 new build tasks to your TFS/Azure DevOps Task Catalogue in the Build category. While editing a build definition, click "Add build step" to open the catalog and look for the Kiuwan tasks.
Select the one you want to use and configure it.
Kiuwan credentials for your build tasks
In both build tasks, you have to select a Kiuwan connection previously configured in the project service endpoints configuration (see above). The credentials configured in the selected Kiuwan connection will be used to run the analysis.
For backward compatibility, if you don't configure the Kiuwan connection in the task, the build definition variables: KiuwanUser and KiuwanPasswd, will be used for credentials. These variables can be used as well to override the Kiuwan connection credentials. This can be useful if you want a particular build definition to run analyses with a different user.
Kiuwan Baseline Analysis Task
This task will run a Kiuwan baseline analysis as part of your build definition. To make it work you first need to decide if you are using the credentials in the Kiuwan service endpoint or override them with variables as described above. Next, you have to set other analysis options. First, decide what is going to be the name of the application in Kiuwan you want to associate the results to. There are 3 options
Kiuwan application name
- Use the TFS/Azure DevOps Project name. This is the default. We use the $(System.TeamProject) variable for the Kiuwan application name. If an application with the same name as the project doesn't exist in Kiuwan it will be automatically created.
- Pick the Kiuwan application from a list. This option associates the results to an existing application in your Kiuwan account. The list is populated from your account using the Kiuwan connection selected in the task. The applications listed are the ones you have, at least, read permissions in the account based on the credentials set in the Kiuwan service endpoint selected.
- Set a new application name. With this option, you can create a new application in your Kiuwan account with the name you enter here.
Analysis label
This is the label to identify your analysis in Kiuwan. The build number is automatically appended to the label you set here.
Security analysis performance
When running security analyses only, you can improve the performance by skipping some analysis steps such as:
- Duplication of code detection that is not relevant for security
- Architecture analysis. If you have the architecture product available in your Kiuwan account you can skip the architecture analysis as well. The default is to skip it always.
Database code analysis
If your project includes database code such as stored procedures for Oracle, SQLServer or Informix you have to select what kind of stored procedures they are if you want to analyze it.
Advanced analysis settings
You can as well set some advanced settings to control the analysis:
- Encoding of the source code (use java encoding strings)
- Include patterns. Ant like patterns to specify the directories and files you want to analyze from your source code structure.
- Exclude patterns. Ant like patterns to specify the directories and files you don't want to analyze from your source code structure. These are applied after the include patterns.
- Maximum memory to allocate for the analysis. Increase it for very large analyses.
- Analysis timeout. The default of 1 hour should be enough for most applications. Increase it for very large applications.
Results
After a successful run of a build definition with a Kiuwan baseline task, the results are immediately available in your Kiuwan account.
The results are automatically uploaded to your Kiuwan account in the cloud where you can see them and browse through the security vulnerabilities and other relevant defects found in your applications.
Kiuwan Delivery Analysis
To use this task you need to have the Life Cycle module in your Kiuwan account. It allows you to audit the deliveries of your application's change requests. The task runs a Kiuwan delivery analysis as part of your build definition. The results are automatically uploaded to your Kiuwan account and the defined audit is run comparing the results with the latest existing application baseline. The OK or Not OK (OK/NOK) audit result is what the task will return. You can decide if you want to fail the build step or not based on the audit result.
Like with the baseline analysis tasks, you can specify some analysis options.
The Kiuwan service connection, the Kiuwan application name, the analysis label, the security analysis performance, the database analysis, and advanced analysis settings behave exactly the same as in the baseline analysis task described and explained in the previous chapter. The specific options of the delivery analysis are as follows.
Analysis scope
Here you decide if this is a complete delivery (all the code base including the changes) or a partial delivery (just the changes)
Fail on Kiuwan audit
If this is set the builds task will fail if the Kiuwan audit that is run automatically after the analysis fails. Uncheck this if you want to run the analysis and the audit but don't want to break the build
Change request status
With Kiuwan change request deliveries you can tag the analysis as In progress, when the changes haven't been completely finished, or Resolved when you consider the changes finished.
Results
Remember that the overall result of the audit is retuned by the task and you can conditionally break your build.
Once the task runs you can immediately see the results in your Kiuwan account. Including all the details of the audit and the defects and vulnerabilities that need to be fixed to pass it.
