Skip to content

Commit

Permalink
Merge pull request #172 from snyk-tech-services/develop
Browse files Browse the repository at this point in the history
Release changes
  • Loading branch information
aarlaud authored Feb 5, 2024
2 parents 6809a94 + 88805ae commit 71fdbff
Show file tree
Hide file tree
Showing 32 changed files with 6,878 additions and 4,713 deletions.
4 changes: 2 additions & 2 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ jobs:
build-test-monitor:
docker:
# specify the version
- image: cimg/node:16.18.0
- image: cimg/node:18.19.0

steps:
- checkout
Expand All @@ -31,7 +31,7 @@ jobs:
build-test:
docker:
# specify the version
- image: cimg/node:16.18.0
- image: cimg/node:18.19.0

steps:
- checkout
Expand Down
2 changes: 1 addition & 1 deletion .clabot
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"contributors": ["aarlaud","punkle", "nicolasarnold12321","snyk-bot","erikvanbrakel","lili2311"]
"contributors": ["aarlaud","punkle", "nicolasarnold12321","snyk-bot","erikvanbrakel","lili2311","silthus","nnillni"]
}
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
node_modules/
dist
dist
.idea/
75 changes: 75 additions & 0 deletions DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# How to work on this plugin

## Note: This guide assumes you use yarn v1.

1. Clone this plugin repository

2. Create a backstage app (outside the plugin repository). If you already have one, skip this step.

```bash
npx @backstage/create-app
```

3. Link the react libraries from backstage to the plugin with the following commands

```bash
# Go to the root of the Backstage app/repository
yarn link --cwd node_modules/react
yarn link --cwd node_modules/react-dom
yarn link --cwd node_modules/react-router-dom
yarn link --cwd node_modules/react-router
yarn link --cwd node_modules/@material-ui/core

# Go to the root of the plugin repository
sh yarn-links.sh
```

4. Add the plugin to the Backstage app

```bash
# Go to the root of the Backstage repository
yarn add --cwd packages/app backstage-plugin-snyk
```

5. Build your plugin (and watch for changes)

```bash
# Go to the root of the plugin repository
yarn build --watch
```

6. Add the needed components in the Backstage app as the [README.md](../README.md) explains

7. Add Snyk configuration to the Backstage app

```yaml
proxy:
endpoints:
/snyk:
target: https://api.snyk.io/
headers:
User-Agent: tech-services/backstage-plugin/1.0
Authorization: token ${SNYK_TOKEN}
snyk:
# Set to "false" to use the real API
mocked: true
```
8. Make sure to add annotations to an entity so the plugin shows in the entity page
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: example-website
annotations:
snyk.io/org-id: 57059599-0459-4443-9cac-3116b5fb5549
snyk.io/project-ids: 33afab43-260a-498e-4432-f556843d2ebe
```
9. You can now start the Backstage app and work in both repositories to see the changes in real time!
```bash
# Root of the Backstage repository
yarn dev
```
90 changes: 59 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Snyk Backstage Plugin
[![Inactively Maintained](https://img.shields.io/badge/Maintenance%20Level-Inactively%20Maintained-yellowgreen.svg)](https://gist.github.com/cheerfulstoic/d107229326a01ff0f333a1d3476e068d)

[![Inactively Maintained](https://img.shields.io/badge/Maintenance%20Level-Inactively%20Maintained-yellowgreen.svg)](https://gist.github.com/cheerfulstoic/d107229326a01ff0f333a1d3476e068d)

**This repository is in maintenance mode, no new features are being developed. Bug & security fixes will continue to be delivered. Open source contributions are welcome for small features & fixes (no breaking changes)**

Expand All @@ -13,12 +13,14 @@ The Snyk plugin displays security details from [snyk.io](https://snyk.io/).
> **Requirements: Snyk API enabled (Paid plans only)**
1. Install plugin

```bash
# packages/app
yarn add --cwd packages/app backstage-plugin-snyk
```

2. Add plugin to the app

```typescript
// packages/app/src/App.tsx
import { EntitySnykContent } from 'backstage-plugin-snyk';
Expand All @@ -34,14 +36,20 @@ import { EntitySnykContent } from 'backstage-plugin-snyk';
```

3. Add Snyk card and tab to the entity page
The plugin is composed of 2 main parts
The plugin is composed of 2 main parts

- Snyk tile on the entity overview page
- Security tab in the entity displaying further details

a. Import the elements

```typescript
// packages/app/src/components/catalog/EntityPage.tsx
import { SnykOverview, EntitySnykContent, isSnykAvailable } from 'backstage-plugin-snyk';
import {
SnykOverview,
EntitySnykContent,
isSnykAvailable,
} from "backstage-plugin-snyk";
```

b. Add the overview card\
Expand All @@ -55,7 +63,7 @@ const entityWarningContent = (
...
<EntitySwitch>
<EntitySwitch.Case if={isSnykAvailable}>
<Grid item md={6}>
<Grid item md={3}>
<SnykOverview />
</Grid>
</EntitySwitch.Case>
Expand All @@ -66,54 +74,72 @@ const entityWarningContent = (
```

c. Add the tab (feel free to rename title to Security, snyk, vulns, whatever you think is best)

```typescript
const ServiceEntityPage = (
<EntityLayoutWrapper>
...
...
<EntityLayout.Route path="/snyk" title="Security">
<EntitySnykContent />
</EntityLayout.Route>
...
...
</EntityLayoutWrapper>
);
```

4. Add snyk proxy config to app-config.yaml file at the root directory. If using Snyk self hosted, adjust target to https://YOURHOSTNAME/api. User Agent helps us see how much API traffic comes from backstage setups so we can invest more in the plugin !

```yaml
proxy:
...

'/snyk':
target: https://api.snyk.io/
headers:
User-Agent: tech-services/backstage-plugin/1.0
Authorization: token ${SNYK_TOKEN}
...
endpoints:
...
/snyk:
# Host of the API to use on the calls.
# If you use EU or AU Snyk account, change this to https://api.eu.snyk.io/ or https://api.au.snyk.io/
target: https://api.snyk.io/
headers:
User-Agent: tech-services/backstage-plugin/1.0
Authorization: token ${SNYK_TOKEN}
...
```

Optional if using Snyk in other regions (not using app.snyk.io), set the hostname you're seeing in your address bar
You can also add the following optional configuration to your app-config.yaml

```yaml
snyk:
AppHost: app.eu.snyk.io
# Host of the Web UI to render links. Defaults to "app.snyk.io"
# If you use EU or AU Snyk account, change this to app.eu.snyk.io or app.au.snyk.io
appHost: app.snyk.io
# Version of the API to use on the calls. Defaults to "2023-06-19~experimental"
apiVersion: 2023-11-06
# Mocks the API calls, useful for development and for testing the plugin without a Snyk account. Defaults to "false"
mocked: false
# Will show resolved issues in all the graphs. Defaults to "false" to show only non-resolved issues
showResolvedInGraphs: false
```
5. Get your Snyk token (a service account with Viewer permission at your group level is preferred) and provide SNYK_TOKEN env var with the value "<YOURTOKEN>"
```bash
export SNYK_TOKEN="123-123-123-123"
```

6. Add this following annotation to your entities.
- `snyk.io/org-name` is the Snyk organization name where your project is. Use the slug (like in url, or in the org settings page), not the display name
6. Add one of the following annotation to your entities.

- `snyk.io/org-id` is the ID of the Snyk organization where your project is. You can find the ID in the Organization Settings in the Snyk dashboard.
- `snyk.io/org-ids` specify one or more Snyk organization ids, comma separated. This will try to find any of the targets or projects in any of the organizations. `snyk.io/org-id` is ignored when this annotation is set.

7. Then add one or more than one of the following annotations to your entities.

- `snyk.io/target-id` specify a single target by name or ID. Target ID will avoid an API call and be therefore faster. Use this [API endpoint](https://apidocs.snyk.io/?version=2023-06-19%7Ebeta#get-/orgs/-org_id-/targets) to get the Target IDs.
- `snyk.io/targets` specify one or more targets, by name or ID. Target ID will avoid an API call and be therefore faster. Use this [API endpoint](https://apidocs.snyk.io/?version=2023-06-19%7Ebeta#get-/orgs/-org_id-/targets) to get the Target IDs.
- `snyk.io/project-ids` are the project ID (see slug in url or ID in project settings)
If multiple projects (like multiple package.json or pom files, add them with increasing number), add them comma separated
If multiple projects (like multiple package.json or pom files, add them with increasing number), add them comma separated
- `snyk.io/exclude-project-ids` to exclude specific projects you might not want.
....
....

Example:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
Expand All @@ -132,28 +158,30 @@ spec:
owner: guest
....
```

Some more examples can be found in [here](https://github.com/snyk-tech-services/backstage-plugin-snyk/tree/develop/test/fixtures)

## Migration steps from version 1.x to 2.x
## Migration steps from plugin version 1.x to 2.x

- Update the proxy target to not contain /v1

## Troubleshooting

- Missing or wrong token set in the backend proxy.\

![Missing/wrong token](docs/assets/backstage_card_error_wrong_or_missing_token.png)

![Missing/wrong token](docs/assets/backstage_card_error_wrong_or_missing_token.png)

- 404s from Snyk API? Add [pathRewrite your app-config.yaml proxy](https://github.com/snyk-tech-services/backstage-plugin-snyk/issues/11) to the following

```yaml
'/snyk':
target: https://api.snyk.io/
headers:
User-Agent: tech-services/backstage-plugin/1.0
Authorization:
$env: SNYK_TOKEN
pathRewrite:
'^/proxy/snyk/': '/'
"/snyk":
target: https://api.snyk.io/
headers:
User-Agent: tech-services/backstage-plugin/1.0
Authorization:
$env: SNYK_TOKEN
pathRewrite:
"^/proxy/snyk/": "/"
```
## Limitations
Expand Down
2 changes: 1 addition & 1 deletion backstage.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"version": "1.0.1"
"version": "1.22.2"
}
48 changes: 39 additions & 9 deletions config.d.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,40 @@
/*
* Copyright 2021 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export interface Config {
/** Optional configurations for the ArgoCD plugin */
snyk?: {
/**
* The base url of the ArgoCD instance.
* @visibility frontend
*/
AppHost?: string;
};
}
/** Optional configurations for the Snyk plugin */
snyk?: {
/**
* @visibility frontend
*/
appHost?: string;
/**
* @visibility frontend
*/
AppHost?: string; // kept for backward compatibility
/**
* @visibility frontend
*/
apiVersion?: string;
/**
* @visibility frontend
*/
mocked?: boolean;
/**
* @visibility frontend
*/
showResolvedInGraphs?: boolean;
};
}
Loading

0 comments on commit 71fdbff

Please sign in to comment.