How the Snyk plugin puts vulnerability findings on entity pages
Developers already use Backstage to find who owns a service and where its documentation lives, but they still have to leave the portal to learn whether that service has open vulnerabilities. The Snyk-maintained Backstage plugin displays Snyk project issues on entity pages once each catalog component is linked to its Snyk project. The work is configuration of a vendor plugin plus one credential decision, not a custom build. The plugin's own documentation is the authority for annotation keys, package names and supported Backstage versions, so confirm those against the version you plan to run before you write any catalog descriptors.
The data path matters for planning. The Backstage frontend requests issue data through the Backstage backend, and the backend calls Snyk's API using a token that your organization provisions and stores as a backend secret. Browsers never hold that token, which is the main reason the credential decision deserves attention early. Ask Snyk and your security team which token type fits the plugin, which Snyk organization it can read, and whether the scope is limited to the projects you intend to show. Confirm these points in the plugin documentation and with your Snyk account owner rather than assuming a default. Also confirm that your Backstage sign-in resolves users in a way that matches who should see vulnerability detail.
Mapping is where most rollouts stall. Each component entity needs an annotation that points to the matching Snyk project, and that mapping must stay accurate as teams rename repositories or split services. Start with a small set of components owned by one team, check that the issue counts on each entity page match what Snyk shows directly, and only then extend the mapping across the catalog. Treat unmapped components as a visible gap for the owning team to close, because a page that shows no findings can look like a clean result when the link is simply missing.
What you need in place before installing the Snyk plugin
The Snyk plugin sits on top of three things you already run: a Backstage instance, a Snyk organization that holds your projects, and a catalog that maps those projects to components. Most install problems trace back to a gap in one of these, so confirm each before you touch the plugin configuration.
A supported Backstage release line
Install the plugin against a Backstage release line it supports, and confirm that in the plugin README against the versions listed in the Backstage release notes. Backstage ships a main line monthly and a next line weekly, so check which line your instance is on before you add packages. Use yarn backstage-cli versions:bump to keep all @backstage packages on the same version, and avoid pinning one package by hand.
Matching Node.js runtime
Backstage supports exactly two adjacent even-numbered Node.js releases at a time. Confirm the Node.js version your Backstage release line expects, and run the backend and any build pipeline on that version, since a mismatch fails at install or at startup. Check the runtime in your container image as well as on your workstation.
A Snyk organization with the projects
Snyk displays only what sits in the organization your token can read. Confirm that the organization holds the projects for the repositories behind your components, and that each project is imported and scanned. Note the organization identifier, because the plugin needs it to scope its queries. Projects that live in another organization will not appear on entity pages.
Catalog entities with ownership
Each component you want to see Snyk issues for needs its own catalog entity, with a spec.owner set to a group or user that exists in the catalog. Ownership is what turns vulnerability data into a work queue, so an entity with no owner shows findings that nobody is accountable for. Decide how project-to-entity mapping will be recorded before you start, because the plugin reads it from entity annotations.
A service identity for the Snyk token
Issue the Snyk API token to a service account or a dedicated integration identity, not to an engineer's personal login, so the token survives staff changes. Give it read access to the organization that holds the projects and nothing broader. Store the token in your secrets manager and inject it into the backend at runtime, never into frontend configuration or the catalog itself.
Outbound access to the Snyk API
The Backstage backend must reach the Snyk API endpoint your contract uses from its network location. Confirm the exact endpoint with Snyk, including any regional or private deployment details that change the hostname, and check that your egress proxy and firewall allow it. Ask Snyk whether your tenant needs a different base URL, since a wrong endpoint fails silently in the entity view.
Configure the Snyk plugin from install to first issue on a page
This sequence takes a Backstage instance from no Snyk connection to a pilot component whose entity page shows its Snyk project and issue counts. Each step ends with a check so a failure is caught at the layer where it occurs.
Confirm the plugin source and versions
The platform engineer who owns the Backstage repository opens the Snyk plugin's own documentation and records which npm packages it names, which Backstage release line they target, and whether the plugin is published by Snyk or by the community. Confirm that the package versions match your installed @backstage packages, since mismatched versions are a common cause of startup failures. Done when the package names and version constraints are written down and reviewed against your Backstage version.
Install the frontend and backend plugin packages
From the root of the Backstage repository, the platform engineer adds the frontend and backend packages named in the plugin documentation using the package manager and workspace commands the README gives, then runs a dependency install. Check the lockfile diff so that only the expected packages changed. Done when the install completes without peer dependency errors and the packages appear in the relevant app and backend package.json files.
Add Snyk configuration with the token from the environment
The platform engineer adds the Snyk block to the backend configuration file, using the configuration keys listed in the plugin README, including the organization identifier and the regional API base URL if the README requires one. The API token is referenced through an environment variable or your secret store, never written into the YAML file or a committed config. Confirm each key name against the README rather than from memory. Done when the file contains no literal token value and the variable is set in the local development environment.
Register the backend plugin and start the backend
The platform engineer registers the Snyk backend module in the backend entry point, following the registration pattern the plugin documents, then starts the backend locally. Watch the startup log for configuration validation messages that name the Snyk block. Done when the backend starts without configuration errors and the plugin's routes are reported as mounted or listed in the log.
Test the Snyk endpoint with the token
Before touching the frontend, the platform engineer calls the Snyk proxy or plugin route on the backend with an authenticated request and checks the response. A valid response lists projects for the configured organization. An authorization error usually points to the token, its scope, or the organization identifier, so fix those before continuing. Done when the call returns project data for the expected organization and the token is still absent from the response body and logs.
Add the Snyk card to the entity page
The frontend developer imports the Snyk component named in the plugin documentation and places it on the component entity page in the app's entity page definition, usually inside a tab or a filtered card wrapper so it shows only for components with the annotation. Check that the component renders without errors in the browser console. Done when a component entity page loads and the Snyk card is present, even if it shows an empty state.
Annotate one pilot component and reload the catalog
The service owner of one pilot component adds the Snyk project annotation to its catalog-info descriptor, using the exact annotation key and value format from the plugin README and the project identifier shown in Snyk. Commit the change, then trigger a catalog refresh or wait for the scheduled refresh, and confirm the entity now carries the annotation. Choose a component with a known Snyk project so the expected results are easy to verify. Done when the entity in the catalog shows the annotation value.
Verify the pilot entity shows project and issue counts
The platform engineer opens the pilot component's entity page and compares the Snyk project name and issue counts with the Snyk web interface for the same project. A mismatch usually means the annotation points to a different project, the organization ID is wrong, or the cache has not refreshed. Done when the project name and counts match Snyk for the pilot entity, which confirms the full path from token to catalog to page works before wider rollout.
Mapping Backstage entities to Snyk organizations and projects
This table compares each Backstage element with its Snyk counterpart and shows how the two are linked and who keeps the link accurate. Read it before you write annotations, because a mismatch in any row leaves findings missing from the entity page or attached to the wrong team.
| Backstage element | Snyk element | How the link is set | Who owns it |
|---|---|---|---|
| Catalog component | Snyk project (one or more per repository or build target) | The component's catalog descriptor is the record the plugin reads. Confirm the exact annotation key in the Snyk plugin documentation before you add it to the descriptor. | Platform team sets the pattern, service team maintains each descriptor |
| Snyk project | Project inside a Snyk organization, identified by its project ID | The project ID or project name is copied into the component annotation so the plugin can query the Snyk API for that project's issues. | Security engineering creates projects, service team confirms the ID |
| Organization or group scope | Snyk organization (and group, if your tenancy uses groups) | The plugin is configured with the organization or group it may read. Each Backstage instance should only be granted the scopes it needs. Confirm the configuration keys in the plugin docs. | Platform team configures the plugin, security team approves the scope |
| Annotation linking entity to Snyk | Project identifier used by the plugin's API queries | Add the annotation to the component descriptor (illustrative: a snyk annotation holding an organization and project reference). Confirm the key name in the plugin docs, since it can change between plugin versions. | Service team, reviewed through the normal pull request process |
| Owner in the catalog | Project tags or ownership metadata in Snyk, where your organization maintains them | The component's owner field should name the team that fixes findings, not a shared mailbox. Use the same group reference that appears in your identity directory. | Engineering manager of the owning team, checked by the catalog owner |
| One component mapped to several Snyk projects | Multiple projects, for example a monorepo with separate manifests or container and code scans | List each project reference in the annotation if the plugin supports multiple values. Otherwise, split the component into subcomponents so each project has one owner. Confirm multi-value support first. | Service team decides the split, platform team reviews the catalog model |
| Snyk project with no matching entity | Project that has no component descriptor referencing it | Findings stay visible in Snyk but do not appear on any Backstage page. Run a periodic comparison of Snyk projects against catalog annotations and register missing components or retire stale projects. | Security engineering reports the gap, catalog owners register the entity |
| Renamed or moved repository | Snyk project name or ID that no longer matches the component | Update the annotation in the same change that moves the repository, so the entity page does not go blank or show another team's findings. | Service team making the change, reviewed by platform team |
| Token scope for the mapping | Snyk API token with read access to the mapped organization | The token is kept on the backend and never placed in the annotation or the frontend. Its scope should match only the organizations listed in the plugin configuration. Confirm the minimum permissions in the plugin docs. | Platform team holds the secret, security team audits the scope |
Securing the Snyk token and what the plugin can expose
The Snyk plugin reads vulnerability data through a token, and anyone who can open an entity page can see what that token returns. The cards below cover where the token lives, how narrowly it is scoped, who can see the results, and how the plugin itself is vetted before it runs inside your portal.
Keep the token in a secret manager
Store the Snyk token in a secret manager, then inject it into the Backstage backend as an environment variable at runtime. It must never appear in the frontend bundle, in app-config.yaml committed to Git, or in a container image layer. Check the built frontend assets and your Git history for the token string before go-live, and rotate it if it has ever been committed.
Issue a service identity token
Create the token under a dedicated service identity rather than a personal account, so it survives staff changes and its activity is attributable. Confirm in Snyk's documentation which token types and role scopes are available for your plan, then choose the narrowest read-only role that still returns project issues for the groups you map. Avoid org admin roles.
Restrict who sees entity pages
Snyk findings appear on entity pages, so the portal's own access controls decide who sees them. Configure Backstage permissions so catalog entity reads are limited where needed, and use sign-in resolvers so each identity maps to the expected catalog user. Do not enable guest access in production, because an anonymous visitor could otherwise read vulnerability data.
Review what findings reveal
Vulnerability titles, package names, affected versions and fix versions can be visible to people who have no access to the source repository. Decide whether that is acceptable for your organization, especially for security-sensitive services. If it is not, limit which projects are mapped to entities or restrict entity visibility to the owning teams.
Plan rotation and revocation
Set a rotation schedule for the token and record who holds the secret manager path that supplies it. When a team member leaves or a service identity changes owner, revoke the old token in Snyk and issue a replacement through the secret manager, then confirm the backend picks it up. Test this procedure once before you need it.
Vet the maintainer and backend code
The plugin's backend runs unsandboxed inside your Backstage process and can read the token it is given. Before installing, confirm who maintains the package, whether it comes from Snyk or a community repository, how recently it was released, and what permissions and network calls its backend code makes. Pin the version and review changes during each Backstage upgrade.
How to verify that the right issues appear on the right pages
Start verification with one pilot component that has a known, current Snyk project. Open its Snyk project view and record the open issue count broken down by severity, then open the same component's entity page in Backstage and compare the counts and severities side by side. Repeat the comparison for two or three different severities so you know the plugin is not only matching totals. If the numbers differ, check first whether the plugin filters out ignored or fixed issues, whether it reads the same Snyk organization, and whether the project annotation points at the project you expected. Record the result as your baseline before you change anything else, because every later check depends on it.
Then test the four failure cases that cause most wrong-page problems. First, use a component with no Snyk project and confirm the entity page shows an empty or clearly labeled state rather than another component's issues. Second, rename a Snyk project and confirm whether the page still resolves after you update the annotation, and whether a stale annotation shows an error. Third, sign in as a user who cannot view the entity or the Snyk organization and confirm that no issue data leaks into the page. Fourth, let a token expire or revoke it in a test environment and confirm the page reports an authorization failure instead of showing stale data as current. Confirm with the plugin's repository whether it ships test fixtures or mock servers for these cases, and what each one covers.
Repeat the full comparison after every Backstage version bump and after every change to the Snyk organization, such as a new group, a moved project or a rotated service account. Treat a mismatch after either change as a release blocker for that environment. Keep the baseline counts, the annotation values and the test results in your change record, since an auditor or security reviewer may ask how you know vulnerability data is attached to the correct owner. Confirm the supported Backstage and Snyk plugin versions in the plugin's documentation before each upgrade, because the comparison only proves something if both sides are on versions you have tested together.
Why the Snyk card is empty or shows errors
This table maps the symptoms teams see on entity pages to their most likely causes and the configuration or permission checks that fix them. Work through the rows in order, since a backend registration or token problem often hides behind an empty card. Confirm exact error text against the plugin's backend logs before changing anything.
| Symptom | Likely cause | Fix |
|---|---|---|
| Snyk card shows no data | Entity has no Snyk project annotation, or the annotation value does not match a project in the Snyk organization | Add the project annotation to the entity descriptor, copy the project identifier from Snyk, and confirm the project exists in the organization the token can read |
| Backend returns 401 or an authentication error | Snyk API token is missing, expired, revoked, or set in a config key the backend does not read | Check the token config key in app-config for the environment, store the token in a secret, and reissue it in Snyk if it was rotated |
| Card shows another team's project or none at all | Annotation points to a project in a different Snyk organization, or the entity is matched to a sibling component | Confirm the organization identifier in config, and verify the annotation on the component entity rather than on a parent system or group |
| Plugin fails to load after a Backstage upgrade | Plugin version does not match the upgraded @backstage packages, or the frontend and backend packages are on different versions | Bump all @backstage packages together with the Backstage CLI, update the Snyk plugin to a release compatible with the new version, and check the upgrade notes for plugin changes |
| Frontend card appears but backend returns nothing | Backend plugin package is not added to the backend index file, so API routes are never mounted | Add the backend package to the backend entry point, restart the backend, and confirm the plugin route responds in the backend logs |
| Annotation present but ignored | Typo in the annotation key, wrong key namespace, or annotation placed under metadata labels instead of annotations | Compare the key character by character with the plugin README, move it under annotations, and re-ingest the entity from the catalog |
| Users see issues they should not see | Shared backend token grants read access wider than the portal's audience, and the card does not check user identity | Narrow the token scope in Snyk, restrict who can view the component, and review what the plugin exposes before widening access |
Questions teams ask before connecting Snyk to Backstage
How much effort does a Snyk plugin setup take?
Effort depends mainly on how many components you map, how consistently your catalog already describes ownership, how you design identity and permissions, and how often you upgrade. A pilot covering a handful of components in one Snyk organization is a contained job. Each additional component needs the correct annotation, a verified project mapping and a check that the right issues appear on its entity page. Permission design often takes longer than teams expect, because the token scope and the question of who may see which findings both need decisions. Upgrade cadence adds recurring work. Ask for a written scope that lists component count, Snyk organizations and the verification steps, and price it from that list.
Can our team set up the Snyk plugin without outside help?
Yes. A team with Backstage experience and administrator access to Snyk can build the integration in-house, since the plugin is open source and its setup steps are documented by its maintainers. Internal teams most often stall on three things: mapping Snyk projects to catalog entities consistently, handling tokens securely, and keeping the plugin working through Backstage upgrades. Check whether your engineers can own the plugin after handover, because an integration nobody maintains will drift. Outside help makes most sense when you want fixed deliverables agreed in writing, or when the catalog itself is still being built. DeployOpen plans, implements and supports self-hosted platforms in your own infrastructure, and most engagements are fixed-scope.
What do we need to provide before the Snyk setup starts?
Prepare four things before work begins:
- Snyk administrator access to the organization and projects, so you can create a scoped token and confirm exact project names
- Catalog ownership, meaning entities with named owners and clear component boundaries
- A secret store that your Backstage backend reads from, where the Snyk token will live
- A pilot team willing to review findings and report mismatches between Snyk and the portal
The pilot team matters because only people who know the components can tell whether a displayed issue belongs to the right service. Confirm access and secret store ownership with your security team early, since approvals often set the start date more than the technical work does.
Is the Snyk plugin free to use with Backstage?
Backstage itself is open source under the Apache License 2.0, and the project does not offer a paid edition, so the framework carries no license fee. Confirm the license and any terms of the Snyk plugin in its own repository before adoption, since plugins can differ from the core project. Snyk billing is a separate matter. The findings the plugin displays come from your Snyk account, so your plan's limits on projects, API use and users determine what you can show. Read Snyk's published pricing and terms directly, and ask your Snyk account team whether your plan covers the API access the plugin needs at your scale.
How long does the first working Snyk setup take?
The duration depends on scope. The main drivers are the number of components and Snyk organizations, the identity and permission design, and whether your catalog already carries the annotations the plugin needs. A team with a clean catalog and one Snyk organization will finish faster than one that must first agree on ownership and project naming. Your change approval process and access to non-production environments also set the pace. Ask for a written quote that splits the work into project mapping, token and identity configuration, verification on a test instance, and handover. The timeline should follow from that written scope, not from a general estimate.
What happens to the Snyk setup when Backstage or the plugin is upgraded?
Backstage upgrades move all @backstage packages together with yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions. Your Snyk plugin sits alongside those packages, so each upgrade can require checking plugin compatibility, configuration keys and how the entity page extension is wired. Backstage's versioning policy backports high and critical vulnerability fixes to releases from the last six months where feasible, which makes staying on a supported line important. Test every upgrade on a non-production instance first, read the plugin's release notes, and confirm that your project mappings still resolve after the change. Plan this as recurring work, not a one-time task.
How should the Snyk token be stored so it stays out of the browser?
Keep the Snyk token in backend configuration that reads from your secret store, and never place it in frontend configuration, because Backstage's frontend code runs in users' browsers. Use a token scoped to read only the findings the portal needs, and confirm with Snyk which token types the plugin accepts. Authentication design matters here too. The Backstage authentication documentation advises sign-in resolvers that map every provider to the same identity, and it advises against guest access in production. Limit who can reach the backend route that returns Snyk data, rotate the token on a schedule, and review backend logs for failed calls that could expose it.
What usually breaks when mapping Snyk projects to catalog entities?
Most failures come from naming and boundaries, not from the plugin itself. Common causes include a Snyk project name that differs from the value in the entity annotation, a monorepo where one component maps to several Snyk projects, entities that carry no annotation at all, and tokens without access to the right Snyk organization. Start with one component whose Snyk project name you have confirmed, then check that its entity page shows the expected issue counts. Use the annotation key that the plugin's documentation specifies, and keep a short mapping table that your catalog owners review each time a component is renamed or split.
How DeployOpen scopes and supports the Snyk plugin integration
DeployOpen plans and builds the Snyk plugin integration inside your Backstage instance, in infrastructure you control. The work starts with a written scope that fixes which Snyk projects map to which catalog entities, how tokens are stored, and how the result is verified before handover.
How we scope
- Inventory the Snyk organizations, projects and entity owners that the portal must show before any code changes.
- Agree in writing which catalog entities receive Snyk annotations and which remain out of scope.
- Define the token type, its owner, and the secret store that will hold it, with a named rotation owner.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- Install the Snyk plugin maintained by Snyk and pin it to the Backstage release line your instance runs.
- Configure the backend so the Snyk API token stays server side and never reaches the browser.
- Add the agreed project annotations to sample and production catalog descriptors and confirm each one resolves.
- Test empty states, wrong project keys and permission errors so entity pages fail in a visible, predictable way.
How we hand over
- Deliver a written mapping of each annotated entity to its Snyk project, with the owner of each mapping.
- Document the token scope, storage location, rotation steps and the person accountable for each.
- Provide an operations note covering upgrade steps for the plugin, including how to test it after a Backstage version bump.
- Walk your platform and security teams through the verification checklist and the open items before sign-off.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- A retainer can cover plugin version updates alongside Backstage upgrades, so the Snyk integration keeps working.
- Ask any provider to confirm plugin compatibility with your exact Backstage version before a upgrade is scheduled.
