Set up Azure Boards integration

Integrate Endor Labs with Azure Boards to automatically create, update, and resolve work items for findings that violate an action policy or that have a remediation available. Endor Labs creates the work item in the Azure DevOps project associated with the repository. This gives teams that run entirely on Azure DevOps a way to triage findings alongside the rest of their backlog.

Endor Labs supports Azure Boards on Azure DevOps Cloud only.

You can set up the integration in the following ways:

Endor Labs user interface
endorctl or the REST API

Prerequisites

Ensure the following prerequisites are in place before you set up the Azure Boards integration.

You need a personal access token (PAT) with the required scopes. You can generate a new PAT or reuse the PAT from an existing Azure DevOps SCM integration if you add the required scope to it.
For each Azure DevOps project you configure, choose a parent work item type that includes a Description field. The default Epic, Issue, and Task types include this field, but a custom work item type might not.
Know the name of each Azure DevOps project you want to map to a repository in Endor Labs.

Generate a personal access token

Generate a PAT in Azure DevOps to authenticate the notification target.

Sign in to Azure DevOps and select User settings > Personal access tokens.
Click New Token.
Enter a name for the token and select the organization it applies to.
Under Scopes, select Custom defined, then grant the following:
- Project and Team: Read
- Work Items: Read & write
Click Create and copy the token. You can’t view the token again after you close this page.

The account that generates the token must have the Contributor role on the target projects. To reuse the PAT from an existing Azure DevOps SCM integration, add the Work Items: Read & write scope to that token first. If the token doesn’t have this scope, requests to create the notification target fail with an error that the PAT is missing the Work Item scope.

Add an Azure Boards integration using the Endor Labs user interface

You enter the organization details, select the Azure DevOps projects to connect, and then set the work item types for each project.

Open the ADO Boards integrations

To create a new Azure Boards integration:

Select User menu > Integrations from the left sidebar.
Under Notifications, click Manage for ADO Boards. The list shows each existing integration with its Name, Organization, Projects, and Policies.
Click Add Notification Integration.

Enter the organization details

Name the integration and connect your Azure DevOps organization.

In Name of ADO board, enter a name for the integration. The name can be up to 255 characters.
Choose how Endor Labs connects to your Azure DevOps organization.
- To reuse an Azure DevOps SCM integration that’s already configured in this namespace, toggle I want to add the board via an already integrated Azure DevOps SCM and select the organization in Organization URL.
- To connect an organization directly, enter the organization URL in Organization URL. The URL must be in the form https://dev.azure.com/<your-organization> or https://<your-organization>.visualstudio.com. You can append a project name to either form.
Optionally, enter your personal access token.
- When you reuse an Azure DevOps SCM integration, the token is optional and labeled Enter a different PAT from SCM integration (optional). Leave it empty to use the token from that SCM integration.
- When you connect an organization directly, enter the token in Enter a PAT. The token is required and can be up to 256 characters.
Click Next. Endor Labs uses the credentials to load the organization’s Azure DevOps projects. If the lookup fails, you stay on this step and Endor Labs shows the reason.

Select projects

Endor Labs lists the Azure DevOps projects in the organization you connected. Select the projects where Endor Labs creates work items.

In Search projects, enter a project name.
Select each Azure DevOps project you want to connect. Endor Labs shows how many of the available projects you selected.
Click Next.

You must select at least one project to continue. Click Back to return to the organization details with your selection intact. Changing the organization or the token clears the selection, because Endor Labs loads the projects again.

Set up work item types

Endor Labs lists the projects you selected with their ADO Project name, Primary work item, Child work item, and Tags.

Click the vertical three dots for a project and select Edit work items.
In Primary work item type, choose the work item type to create for the project.
In Child work item type, choose the work item type to create under the parent.
Optionally, enter one or more values in Tags to apply to every work item created for this project.
Click Update.
Repeat steps 1 through 5 for each project you selected.
Click Save Integration.

A project counts as configured only when it has both a primary and a child work item type, and Endor Labs saves only the configured projects. If you leave some projects unconfigured, Endor Labs asks you to confirm with Save with unconfigured projects? before saving. You can return later and configure the rest.If the work item types for a project fail to load, click the vertical three dots and select Refetch work items. To drop a project, select Remove project, which also clears it from your selection.

Manage an Azure Boards integration

You can edit an existing Azure Boards integration to update its configuration, or delete it when you no longer need it.

Edit an integration

Edit an integration to change its name, token, selected projects, or work item setup. Organization URL and the credential source are locked, so create a new integration to point at a different organization.

Select User menu > Integrations from the left sidebar.
Under Notifications, click Manage for ADO Boards.
Click the vertical three dots for the integration and select Edit Notification Integration.
Change the name, the token, the selected projects, or the work item setup.
Click Save Integration.

Keep the following in mind as you edit.

Endor Labs doesn’t display the stored token. If you enter a new token, it replaces the stored one and must have access to every project you configured.
Projects you already configured are selected and marked Configured. Clearing one removes its work item setup.
Projects that Azure DevOps no longer returns are marked No longer supported. You can’t select them, and Endor Labs drops them when you save.
A warning names any work item type that no longer exists in Azure DevOps. That project counts as unconfigured until you choose another type.

Delete an integration

Delete an integration to stop Endor Labs from creating work items through it. Existing work items in Azure DevOps remain.

Select User menu > Integrations from the left sidebar.
Under Notifications, click Manage for ADO Boards.
Click the vertical three dots for the integration and select Delete Notification Integration.

Endor Labs blocks deletion when the integration is still referenced by an action policy, a remediation policy, or a package firewall notification rule. Remove it from all referencing policies and rules, then try again.

Create an Azure Boards notification target

An Azure Boards notification target uses ACTION_TYPE_ADO_BOARDS. Every target requires at least one project mapping that specifies the parent work item type and, optionally, a child work item type and tags. A target authenticates with Azure DevOps in one of two ways:

Provide credentials directly: You supply the organization URL and a PAT in user_config, and the target stores them. Use this if you don’t have an Azure DevOps installation in Endor Labs, or if you want a dedicated PAT for this target.
Reuse an Azure DevOps installation: You supply the UUID of an existing installation in installation_uuid, and Endor Labs resolves the organization URL and PAT from it. The PAT on that installation must include the Work Items scope.

The following are the ado_boards_config fields.

Provide credentials directly

Create the target with the organization URL and PAT in user_config.

endorctl
curl

endorctl api create -r NotificationTarget -n <namespace> -d '{
  "meta": { "name": "azure-boards-notifications" },
  "spec": {
    "action": {
      "action_type": "ACTION_TYPE_ADO_BOARDS",
      "public": true,
      "ado_boards_config": {
        "user_config": {
          "org_url": "https://dev.azure.com/<your-organization>",
          "auth": {
            "pat": { "token": "<your-pat-token>" }
          }
        },
        "projects": [
          {
            "project_name": "<your-project-name>",
            "work_item_type": "Issue",
            "child_work_item_type": "Task",
            "tags": ["security", "endorlabs"]
          }
        ]
      }
    }
  },
  "propagate": true
}'

curl --request POST \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Content-Type: application/json" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/notification-targets" \
  --data '{
    "meta": { "name": "azure-boards-notifications" },
    "spec": {
      "action": {
        "action_type": "ACTION_TYPE_ADO_BOARDS",
        "public": true,
        "ado_boards_config": {
          "user_config": {
            "org_url": "https://dev.azure.com/<your-organization>",
            "auth": {
              "pat": { "token": "<your-pat-token>" }
            }
          },
          "projects": [
            {
              "project_name": "<your-project-name>",
              "work_item_type": "Issue",
              "child_work_item_type": "Task",
              "tags": ["security", "endorlabs"]
            }
          ]
        }
      }
    },
    "propagate": true
  }'

Reuse an Azure DevOps installation

Create the target with the UUID of an existing installation in place of user_config.

Find the installation UUID.

endorctl
curl

endorctl api list -r Installation -n <namespace> \
  | jq '.list.objects[] | select(.spec.platform_type=="PLATFORM_SOURCE_AZURE") | {uuid: .uuid, name: .meta.name}'

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --data-urlencode "list_parameters.filter=spec.platform_type==PLATFORM_SOURCE_AZURE" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/installations" \
  | jq '.list.objects[] | {uuid: .uuid, name: .meta.name}'

Create the notification target with the installation UUID.

endorctl
curl

endorctl api create -r NotificationTarget -n <namespace> -d '{
  "meta": { "name": "azure-boards-notifications" },
  "spec": {
    "action": {
      "action_type": "ACTION_TYPE_ADO_BOARDS",
      "public": true,
      "ado_boards_config": {
        "installation_uuid": "<your-installation-uuid>",
        "projects": [
          {
            "project_name": "<your-project-name>",
            "work_item_type": "Issue",
            "child_work_item_type": "Task",
            "tags": ["security"]
          }
        ]
      }
    }
  },
  "propagate": true
}'

curl --request POST \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Content-Type: application/json" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/notification-targets" \
  --data '{
    "meta": { "name": "azure-boards-notifications" },
    "spec": {
      "action": {
        "action_type": "ACTION_TYPE_ADO_BOARDS",
        "public": true,
        "ado_boards_config": {
          "installation_uuid": "<your-installation-uuid>",
          "projects": [
            {
              "project_name": "<your-project-name>",
              "work_item_type": "Issue",
              "child_work_item_type": "Task",
              "tags": ["security"]
            }
          ]
        }
      }
    },
    "propagate": true
  }'

You can add multiple projects to a single notification target. When a finding triggers a notification, Endor Labs matches the repository’s Azure DevOps clone URL to a configured project by name. If the project was renamed in Azure DevOps, Endor Labs falls back to matching by project GUID.

Manage Azure Boards notification targets

You can list the existing Azure Boards notification targets, update one to change its configuration, or delete one when you no longer need it.

List notification targets

List every Azure Boards notification target in a namespace.

endorctl
curl

endorctl api list -r NotificationTarget -n <namespace> \
  -f "spec.action.action_type==ACTION_TYPE_ADO_BOARDS"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --data-urlencode "list_parameters.filter=spec.action.action_type==ACTION_TYPE_ADO_BOARDS" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/notification-targets" \
  | jq '.list.objects'

Update a notification target

Updates use a field mask to specify which fields to change. Endor Labs changes only the fields listed in the mask. For example, to rotate the PAT on an existing target without changing its projects:

endorctl
curl

endorctl api update -r NotificationTarget -n <namespace> \
  --uuid <target-uuid> \
  --field-mask "spec.action.ado_boards_config.user_config.auth.pat.token" \
  -d '{
    "uuid": "<target-uuid>",
    "tenant_meta": { "namespace": "<namespace>" },
    "spec": {
      "action": {
        "action_type": "ACTION_TYPE_ADO_BOARDS",
        "ado_boards_config": {
          "user_config": {
            "org_url": "https://dev.azure.com/<your-organization>",
            "auth": {
              "pat": { "token": "<new-pat-token>" }
            }
          }
        }
      }
    }
  }'

curl --request PATCH \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Content-Type: application/json" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/notification-targets" \
  --data '{
    "request": {
      "update_mask": "spec.action.ado_boards_config.user_config.auth.pat.token"
    },
    "object": {
      "uuid": "<target-uuid>",
      "tenant_meta": { "namespace": "<namespace>" },
      "spec": {
        "action": {
          "action_type": "ACTION_TYPE_ADO_BOARDS",
          "ado_boards_config": {
            "user_config": {
              "org_url": "https://dev.azure.com/<your-organization>",
              "auth": {
                "pat": { "token": "<new-pat-token>" }
              }
            }
          }
        }
      }
    }
  }'

To switch a target from user_config to installation_uuid or back, the organization URL of the new credential source must match the organization URL already stored on the target. If the URLs differ, the update fails and you must create a new notification target instead.

Delete a notification target

Delete a target by its UUID.

endorctl
curl

endorctl api delete -r NotificationTarget -n <namespace> --uuid <target-uuid>

curl --request DELETE \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/notification-targets/<target-uuid>"

Endor Labs blocks deletion when the target is still referenced by an action policy, a remediation policy, or a package firewall notification rule. Remove the target from all referencing policies and rules, then retry the delete.

Associate a policy with Azure Boards

Endor Labs doesn’t create any work items until a policy references your Azure Boards configuration. Create an action policy or remediation policy that references your Azure Boards configuration. While creating the policy, configure the following settings:

Select Choose an Action as Send Notification.
From SELECT NOTIFICATION TARGETS, choose the Azure Boards notification target that you created.

From Select aggregation type, choose how findings are grouped into notifications.

None (Notify for each Finding) sends a separate notification for each finding.
Project sends a single notification for all findings in a project.
Dependency sends a notification for every dependency.
Dependency per Package Version sends a notification for every unique combination of dependency and package version.

See Create an action policy to configure a policy that sends notifications. See Manage work items in Azure Boards to learn how Endor Labs creates, updates, and resolves work items.

Introduction

Setup & Deployment

Inventory & Insights

Scan with Endor Labs

Risk Remediation

Integrations

Secure AI Coding

Platform Administration

Best Practices

Threat Center

Trust & Compliance

Prerequisites

Generate a personal access token

Add an Azure Boards integration using the Endor Labs user interface

Manage an Azure Boards integration

Edit an integration

Delete an integration

Create an Azure Boards notification target

Provide credentials directly

Reuse an Azure DevOps installation

Manage Azure Boards notification targets

List notification targets

Update a notification target

Delete a notification target

Associate a policy with Azure Boards

​Prerequisites

​Generate a personal access token

​Add an Azure Boards integration using the Endor Labs user interface

​Manage an Azure Boards integration

​Edit an integration

​Delete an integration

​Create an Azure Boards notification target

​Provide credentials directly

​Reuse an Azure DevOps installation

​Manage Azure Boards notification targets

​List notification targets

​Update a notification target

​Delete a notification target

​Associate a policy with Azure Boards

Prerequisites

Generate a personal access token

Add an Azure Boards integration using the Endor Labs user interface

Manage an Azure Boards integration

Edit an integration

Delete an integration

Create an Azure Boards notification target

Provide credentials directly

Reuse an Azure DevOps installation

Manage Azure Boards notification targets

List notification targets

Update a notification target

Delete a notification target

Associate a policy with Azure Boards