A. Integrating Azure DevOps
Organisation and Access Token
In order to authenticate with the Azure DevOps (ADO) API server you need your Organisation name and an active Access Token. You will need these details later, when configuring the integration in Phoenix Security.
Organisation Name
When you log into your ADO account you can see the list of organisations on the left-hand side. In the example below the Organisation name is “asp-test-org”.
Access Token
To create an Access Token you need to go to the Personal Access Tokens page. To get there, click on the user menu/icon in the top-right corner, then click on the user context menu (three dots) and select “User settings”. In the pop-up menu select “Personal access tokens” in the bottom section.
You would normally want to create a new token for this integration. Select “+ New Token” and fill in the details in the token configuration form. The two key points to keep in mind are:
- Make sure that you enter a fairly long, custom defined Expiration date. When the token expires the integration between Phoenix Security and ADO will stop working.
- In the Scopes section either select Full access or make sure that Work Items has “Read, write & manage” selected.
Make sure that you copy the token in the last step since this is the last time that it will be visible.
Integrating ADO within Phoenix Security
Before using ADO integration features within your Phoenix Security instance, you have to set it up first by configuring the ADO – Phoenix Security integration. Here are the steps to complete the integration process:
- On the Navigation Menu, go to Integrations > Workflow. Then click on the Create Workflow button.
- Select the Azure DevOps option from the available ones.
- On the second step you need to provide the ADO connection details discussed earlier in this article:
- For the Item Type enter the name of the type of ticket to be created – you can see the list in the drop-down of the “New Work Item” action in ADO. If you leave it blank it will default to “Issue“.
- Click the “Create Workflow” button.
B. Link ADO to an Application
In order to link an existing Phoenix Security Application to ADO, you need to edit the Application and enable the “Link to Issue Tracking Project” checkbox.
- On the Navigation Menu, select Risk Explorer > Applications.
- Select the Application List tab and scroll down to the Application that you want to update. Hover your mouse over the application entry, click on the three-dots icon than appears on the right, and select Edit (pencil icon).
- In the Update Application form, find that Integration section on the right-hand side and check the “Link to Issue Tracking Project”.
- Select the ADO Account and ADO Project that you want to link the Application to.
- Click the “Save Linking to Issue Tracking” button to save the changes.
By linking your application to an ADO project you will be able to create tickets in ADO for the application’s vulnerabilities with a single click.
Once the process is completed a blue ADO logo will appear next to the Application in the Applications list to indicate that the Application is currently linked to an ADO Project.
C. Link ADO to an Environment
In order to link an existing Phoenix Security Environment to ADO, you need to edit the Environment and enable the “Link to Issue Tracking Project” checkbox. The whole process is analogous to the one for Applications (above):
- On the Navigation Menu, select Risk Explorer > Environments.
- Select the Environment List tab and scroll down to the Environment that you want to update. Hover your mouse over the application entry, click on the three-dots icon than appears on the right, and select Edit (pencil icon)
- In the Update Environment form, find that Integration section on the right-hand side and check the “Link to Issue Tracking Project”.
- Select the ADO Account and ADO Project that you want to link the Environment to.
- Click the “Save Linking to Issue Tracking” button to save the changes.
Once the process is completed a blue ADO logo will appear next to the environment in the Environment list to indicate that the environment is currently linked to an ADO Project.
D. Create an ADO Ticket to Track a Vulnerability
Once ADO is fully integrated with your Phoenix Security account, you can create ADO tickets to keep track and monitor a Vulnerability identified in your Application. Here are the steps for you to follow:
- On the Navigation Menu, click Vulnerabilities.
- Scroll down until you see the Vulnerabilities section. Look for the Vulnerability you wish to track with ADO and click the blue ADO icon corresponding to it (marked with the white line in the screenshot below).
- Once a ticket has been successfully created, the ticket reference number and status will be displayed where the blue ADO icon was located in step 2. An example has been marked with a red line in the screenshot below.
- Click on the ticket reference number to open the incident ticket page in ADO.
You can monitor the progress of the ticket on ADO moving forward.
E. Webhooks and Issue Updates
Once a ticket has been created for a vulnerability Phoenix Security can keep track of the status changes and deletion of the ticket within Azure DevOps. For this to work you need to configure a webhook within ADO that tells the platform how to send updates to Phoenix Security.
In order to configure you webhooks you will need the unique URL create for your ADO integration. In the main menu select Integration > Workflows and then click on the ADO integration that you are configuring the webhooks for. In the details you will find the “Webhook URL” field, which is not editable but can be copied from here.
Once you have your webhook URL, select a Project within ADO and click on “Project settings” at the bottom-left corner of the page. In the vertical menu that appears, select “Service hooks” in the General section. Here you can create two webhooks, one for work item updates and another one for deletions.
Click in the plus (+) sign to create a new Service Hook (webhook) and select “Web Hooks” near the bottom of the list in the popup. Then click Next and configure the first screen as shown below. (The tag should be Phoenix_Security)
Then clink on “Next” and enter the webhook URL obtained from Phoenix Security earlier. The other fields can be configured as shown below.
For the deletions you can follow a similar process. Create a new Service Hook and configure the first step as shown.
On the second step enter your webhook URL and configure the rest as shown.
Once you have completed these steps, any status changes or deletions within ADO of Work Items (Issues) created through Phoenix Security will be updated automatically.