project tags

Manage risk more efficiently using Snyk’s new Project Tagging API

May 20, 2020 | in Product
| By Waleed Arshad

It’s always exciting to see how our users scale their security and compliance efforts by integrating more and more of their projects into Snyk. Some teams are managing security vulnerabilities and license issues across hundreds of thousands of projects. 

But as great as this is, it’s also time-consuming to find exactly what is the right thing to work on, and when. To make it easier for our users to triage issues at this scale, we’ve been working on a new way to categorize projects using tags.

Tagging projects is possible today via the API and allows you to group and filter your projects based on the tags you’ve applied. This feature will be available in the UI soon.

What are project tags?  

A project tag in Snyk is custom metadata which can be applied to a project in the form of a key-value pair. Given that it’s custom metadata, what you assign as the key and the value is completely up to you.

Once applied, the tags are returned from the Project API as a part of the response. Tags can also be applied as a filter to get back a list of projects that have a specific tag.

To give you a taste of what tags can do, I’m going to show you how to create and assign a tag to projects, and then filter through your organization to find the group of projects with that tag.   

Grouping projects together by team

We have quite a few teams here at Snyk and I’d love to be able to filter by them. For example, my team is working on some of the most critical, external-facing applications and I need to see the projects my team is working on, inside a specific org. 

First, I need to tag my team’s orgs, and then, through the API, I can apply an identifier to a project within an org that my team is working with. 

After I’ve found the project, I’ll call the following endpoint:

POST:api/v1/org/:orgId/project/:projectId/tags

The next step is to provide the following request to create and apply the tag to that project. Tags are key and value pairs, so in this situation the key is “Team” and the value is “Unicorn” because that’s the name of my team:

{
	"key": "team",
	"value": "unicorn"
}

This shows all tags currently applied to the project. Every time I add another tag to the project, the response list will grow:

{
    "tags": [
        {
            "key": "team",
            "value": "unicorn"
        }
    ]
}

All I have to do now is repeat the process for any other projects in the org which my team is working with. 

Find the group of projects my team is working with

Now that I’ve tagged all my team’s projects in the org, the next thing I want to do is find a way to quickly search for those projects and keep track of their vulnerability status. In order to do this, I’m going to call the following endpoint to grab all of the projects in the org:

POST:api/v1/org/:orgId/projects

Then I’m going to submit the following request to return all of the projects with the following tag assigned to it:

{
  "filters": {
    "tags": {
      "includes": [
        {
        	"key": "team",
        	"value": "unicorn"
        }
      ]
    }
  }
}

Overall, you can assign tags to lots of projects through the API in order to group them in whichever way you like. It can be anything from grouping projects by risk status, or grouping by the type of application a project is used for. This way you can find those groups of projects quickly and manage the risk more efficiently. 

For more information on the other actions you can perform with project tags, check out our official documentation.

This is just the beginning! Project Tags is still under development and we know that there are multiple additional ways in which this capability is going to help you manage issues more efficiently. Stay tuned for updates. 

Happy tagging, everyone!