@backstage-community/plugin-apiiro 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @backstage-community/plugin-apiiro
+
+## 0.1.0
+
+### Minor Changes
+
+- 8407557: Added new [Apiiro](https://apiiro.com/) plugin. Check out the plugins [README.md](https://github.com/backstage/community-plugins/tree/main/workspaces/apiiro/plugins/apiiro) for more details!
+
+### Patch Changes
+
+- Updated dependencies [8407557]
+  - @backstage-community/plugin-apiiro-common@0.1.0

package/README.md

@@ -0,0 +1,232 @@
+# Apiiro Plugin for Backstage
+
+The Apiiro plugin for Backstage integrates Apiiro's application risk management capabilities directly into your Backstage developer portal. This plugin empowers developers to code securely by automatically checking for security vulnerabilities and enables them to review and address newly introduced vulnerabilities directly in Backstage.
+
+## Plugin Compatibility
+
+The plugin has been successfully tested with Backstage v1.44.0 If you are using a newer version of Backstage, please file an issue, and we will provide guidance on the best integration practices for your specific version.
+
+## Features
+
+- **Dashboard View**: Repository list with statistics sourced from Apiiro
+- **Apiiro Tab**: In-depth view of repository open risks and detailed metrics
+- **Apiiro Widget**: High-level overview widget that can be embedded in custom entity tabs
+- **Permission Control**: Conditional permissions for fine-grained access control to Apiiro metrics
+
+## Views
+
+### Dashboard – Repository List
+
+Displays the list of integrated repositories along with statistics sourced from Apiiro. Clicking on a repository redirects you to the Apiiro tab for detailed insights.
+
+![Dashboard Repository List](../../assets/dashboard.png)
+
+### Apiiro Tab
+
+Provides an in-depth look at each repository's open risks and detailed metrics retrieved from Apiiro.
+
+![Apiiro Tab](../../assets/apiiro-tab.png)
+
+### Apiiro Widget
+
+Offers a high-level overview of the repository, including programming languages and top risk details. Can be added to any custom entity tab.
+
+![Apiiro Widget](../../assets/apiiro-widget.png)
+
+## Prerequisites
+
+- The entity for a repository must be present within Backstage to see Apiiro results
+- Appropriate access permissions to an entity in Backstage are required to view its Apiiro results
+- An Apiiro Access Token with at least read permissions
+
+### Dependencies
+
+> [!IMPORTANT]
+> Please note that the frontend plugin will not function without the backend plugin.
+
+## Getting Started
+
+### 1. Configure Apiiro Plugin for Backstage
+
+Add the following annotation into your catalog.
+To be able to use the Apiiro plugin you need to add the following annotation to any entities you want to use it with:
+
+```yaml
+apiiro.com/repo-id: <apiiro-repo-key>
+apiiro.com/allow-metrics-view: "true" or "false" (controls whether the Metrics view appears in the Apiiro tab and Apiiro widget)
+```
+
+Let's break this down a little: `<apiiro-repo-key>` will be the key of your repository in Apiiro.
+
+Here's what that will look like in action:
+
+```yaml
+# Example catalog-info.yaml entity definition file
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-component
+  annotations:
+    apiiro.com/repo-id: my-repo-key
+    apiiro.com/allow-metrics-view: 'true'
+```
+
+Please find the steps to add the annotation automatically [here](../apiiro-backend/README.md#automatically-adding-apiiro-annotations-optional).
+
+### 2. Install required plugins packages
+
+From your Backstage root directory, run:
+
+```bash
+yarn --cwd packages/app add @backstage-community/plugin-apiiro
+```
+
+**Note:** The Backstage frontend plugin will not function without the backend plugin. Please find the steps to add the backend plugin [here](../apiiro-backend/README.md#installation).
+
+### 3. Configuration
+
+Add your Apiiro Access Token to your `app-config.yaml` or `app-config.production.yaml`:
+
+```yaml
+apiiro:
+  accessToken: ${APIIRO_TOKEN}
+  defaultAllowMetricsView: true
+  # Optional: Configure default risk filters for the Apiiro Risk Table (Example configuration)
+  defaultRiskFilters:
+    RiskLevel:
+      - Critical
+      - High
+    RiskInsight:
+      - Internet exposed
+      - Deployed
+    RiskCategory:
+      - SAST findings
+      - Secrets
+    Provider:
+      - ApiiroSca
+      - AkamaiApiSecurity
+    PolicyTags:
+      - Security Code Review
+      - Compliance Review (PCI)
+```
+
+Where:
+
+- `accessToken` is your Apiiro Access Token
+- `defaultAllowMetricsView` is a boolean value that controls whether the Metrics view appears in the Apiiro Tab and Apiiro Widget by default. If annotation is not set, this value will be used. Default value is `true`.
+- `defaultRiskFilters` (optional) configures default filters for the Apiiro Risk Table. Please refer to the [backend documentation](../apiiro-backend/README.md#configure-default-risk-filters-optional) for more details.
+
+**How to Retrieve an Access Token from Apiiro:**
+
+1. Log in to your Apiiro instance
+2. Go to Settings → Access Token
+3. Create a new Access Token with a long expiration period (1 year) and grant at least read permissions
+4. Generate and securely save the token
+
+![Apiiro Access Token](../../assets/access-token.png)
+
+### 4. Add Apiiro Tab to Entity Page
+
+In `packages/app/src/components/Catalog/EntityPage.tsx`:
+
+```tsx
+// Import the Apiiro tab
+import {
+  ApiiroTab,
+  isApiiroRepoAvailable,
+} from '@backstage-community/plugin-apiiro';
+
+// Add the route to your service entity page
+const serviceEntityPage = (
+  <EntityLayout>
+    <EntityLayout.Route path="/" title="Overview">
+      {/* ... other elements */}
+    </EntityLayout.Route>
+
+    <EntityLayout.Route
+      if={isApiiroRepoAvailable}
+      path="/apiiro"
+      title="Apiiro"
+    >
+      <ApiiroTab />
+    </EntityLayout.Route>
+
+    {/* ... other elements */}
+  </EntityLayout>
+);
+```
+
+### 5. Add the Apiiro Sidebar with Repositories List (Optional)
+
+In `packages/app/src/App.tsx`:
+
+```tsx
+// Import the Apiiro page
+import { ApiiroPage } from '@backstage-community/plugin-apiiro';
+
+// Add the route
+const routes = (
+  <FlatRoutes>
+    <Route path="/" element={<Navigate to="catalog" />} />
+    <Route path="/catalog" element={<CatalogIndexPage />} />
+    {/* ... other elements */}
+    <Route path="/apiiro" element={<ApiiroPage />} />
+    {/* ... other elements */}
+  </FlatRoutes>
+);
+```
+
+Add Apiiro Sidebar Button
+
+In `packages/app/src/components/Root/Root.tsx`:
+
+```tsx
+// Import the Apiiro sidebar
+import { ApiiroSidebar } from '@backstage-community/plugin-apiiro';
+
+// Add to your sidebar
+export const Root = ({ children }: PropsWithChildren<{}>) => (
+  <SidebarPage>
+    <Sidebar>
+      {/* ... other elements */}
+
+      <ApiiroSidebar />
+
+      {/* ... other elements */}
+    </Sidebar>
+    {children}
+  </SidebarPage>
+);
+```
+
+### 6. Add Apiiro Widget to Custom Entity Tab (Optional)
+
+The Apiiro plugin for Backstage includes a widget that can be embedded in a custom tab of the Backstage entity. This widget provides an overview of the risk associated with that entity, alongside your other valuable insights.
+To add the widget, include the following component in your custom entity tab:
+
+```tsx
+// ... other imports here
+import {
+  ApiiroWidget,
+  isApiiroRepoAvailable,
+} from '@backstage-community/plugin-apiiro';
+// ... other components
+
+// add the following line to import the component at required position
+<EntitySwitch>
+  <EntitySwitch.Case if={isApiiroRepoAvailable}>
+    <Grid item md={12} xs={12}>
+      <ApiiroWidget />
+    </Grid>
+  </EntitySwitch.Case>
+</EntitySwitch>;
+```
+
+## Development
+
+To run the entire project including the backend, run `yarn start` from the workspace root directory.
+
+## Links
+
+- [Backend Plugin Documentation](../apiiro-backend/README.md)
+- [Add Annotation Automatically](../apiiro-backend/README.md#automatically-adding-apiiro-annotations-optional)

package/config.d.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 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 {
+  /**
+   * Apiiro plugin configuration.
+   * @visibility frontend
+   */
+  apiiro?: {
+    /**
+     * Default value for the allow metrics view annotation
+     * @visibility frontend
+     * @default true
+     */
+    defaultAllowMetricsView?: boolean;
+  };
+}

package/dist/App.esm.js

@@ -0,0 +1,12 @@
+import { jsx } from 'react/jsx-runtime';
+import { Routes, Route } from 'react-router-dom';
+import { Repositories } from './pages/Repositories/Repositories.esm.js';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { queryClient } from './api/index.esm.js';
+
+const App = () => {
+  return /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(Routes, { children: /* @__PURE__ */ jsx(Route, { path: "/", element: /* @__PURE__ */ jsx(Repositories, {}) }) }) });
+};
+
+export { App };
+//# sourceMappingURL=App.esm.js.map

package/dist/App.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.esm.js","sources":["../src/App.tsx"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { Routes, Route } from 'react-router-dom';\nimport { Repositories } from './pages/Repositories';\nimport { QueryClientProvider } from '@tanstack/react-query';\nimport { queryClient } from './api';\n\nexport const App = () => {\n  return (\n    <QueryClientProvider client={queryClient}>\n      <Routes>\n        <Route path=\"/\" element={<Repositories />} />\n      </Routes>\n    </QueryClientProvider>\n  );\n};\n"],"names":[],"mappings":";;;;;;AAoBO,MAAM,MAAM,MAAM;AACvB,EAAA,uBACE,GAAA,CAAC,mBAAA,EAAA,EAAoB,MAAA,EAAQ,WAAA,EAC3B,8BAAC,MAAA,EAAA,EACC,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAM,IAAA,EAAK,KAAI,OAAA,kBAAS,GAAA,CAAC,YAAA,EAAA,EAAa,CAAA,EAAI,GAC7C,CAAA,EACF,CAAA;AAEJ;;;;"}

package/dist/api/index.esm.js

@@ -0,0 +1,71 @@
+import { QueryClient } from '@tanstack/react-query';
+import { createApiRef } from '@backstage/core-plugin-api';
+
+const apiiroApiRef = createApiRef({
+  id: "plugin.apiiro.service"
+});
+class ApiiroClient {
+  discoveryApi;
+  configApi;
+  constructor(options) {
+    this.discoveryApi = options.discoveryApi;
+    this.configApi = options.configApi;
+  }
+  getDefaultAllowMetricsView() {
+    return this.configApi.getOptionalBoolean("apiiro.defaultAllowMetricsView") ?? true;
+  }
+}
+const queryClient = new QueryClient();
+function assembleUri(uri, params) {
+  if (!params) {
+    return uri;
+  }
+  const queryString = new URLSearchParams(params).toString();
+  return `${uri}?${queryString}`;
+}
+function buildHeaders(optionHeaders) {
+  const headers = new Headers();
+  headers.set("Content-Type" /* CONTENT_TYPE */, "application/json");
+  Object.keys(optionHeaders).forEach((header) => {
+    const headerValue = optionHeaders[header];
+    if (headerValue) {
+      headers.set(header, headerValue);
+    }
+  });
+  return headers;
+}
+function fetchRequest(fetchApi, method, url, opts) {
+  const { params, body, headers, signal } = opts;
+  const requestURL = params ? assembleUri(url, params) : url;
+  const requestParams = {
+    headers: buildHeaders(headers || {}),
+    method,
+    signal
+  };
+  if (body) {
+    requestParams.body = typeof body === "string" ? body : JSON.stringify(body);
+  }
+  return fetchApi(requestURL, requestParams);
+}
+function toJson(response) {
+  if (response.status === 204 || response.body === null) {
+    return Promise.resolve({});
+  }
+  return response.json().then((json) => {
+    return response.ok ? json : Promise.reject(json);
+  });
+}
+const defaultOpts = {
+  body: null,
+  headers: {},
+  params: null
+};
+function get(fetchApi, url, opts = defaultOpts) {
+  return fetchRequest(fetchApi, "GET" /* GET */, url, opts).then(toJson);
+}
+function post(fetchApi, url, opts = defaultOpts) {
+  return fetchRequest(fetchApi, "POST" /* POST */, url, opts).then(toJson);
+}
+
+export { ApiiroClient, apiiroApiRef, get, post, queryClient };
+//# sourceMappingURL=index.esm.js.map

package/dist/api/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../../src/api/index.ts"],"sourcesContent":["/*\n * Copyright 2024 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { QueryClient } from '@tanstack/react-query';\nimport {\n  ConfigApi,\n  createApiRef,\n  DiscoveryApi,\n} from '@backstage/core-plugin-api';\n\n/**\n * Plugin API\n */\nexport type ApiiroApi = {\n  discoveryApi: DiscoveryApi;\n  getDefaultAllowMetricsView: () => boolean;\n};\n\nexport const apiiroApiRef = createApiRef<ApiiroApi>({\n  id: 'plugin.apiiro.service',\n});\n\nexport class ApiiroClient implements ApiiroApi {\n  discoveryApi: DiscoveryApi;\n  private readonly configApi: ConfigApi;\n\n  constructor(options: { discoveryApi: DiscoveryApi; configApi: ConfigApi }) {\n    this.discoveryApi = options.discoveryApi;\n    this.configApi = options.configApi;\n  }\n\n  getDefaultAllowMetricsView(): boolean {\n    return (\n      this.configApi.getOptionalBoolean('apiiro.defaultAllowMetricsView') ??\n      true\n    );\n  }\n}\n\n/**\n * React Query Client\n */\nexport const queryClient = new QueryClient();\n\n/**\n * Fetch: GET, POST\n */\ntype QueryParams = Record<string, string>;\n\ntype RequestHeaders = Record<string, string>;\n\nenum ApiHeaders {\n  CONTENT_TYPE = 'Content-Type',\n}\n\nenum REQUEST_METHOD {\n  GET = 'GET',\n  POST = 'POST',\n}\n\ninterface RequestOptions {\n  body?: any;\n  headers?: RequestHeaders;\n  params?: Record<string, any> | null;\n  signal?: AbortSignal;\n}\n\nfunction assembleUri(uri: string, params?: QueryParams): string {\n  if (!params) {\n    return uri;\n  }\n\n  const queryString = new URLSearchParams(params).toString();\n  return `${uri}?${queryString}`;\n}\n\nfunction buildHeaders(optionHeaders: RequestHeaders): Headers {\n  const headers = new Headers();\n  headers.set(ApiHeaders.CONTENT_TYPE, 'application/json');\n\n  Object.keys(optionHeaders).forEach(header => {\n    const headerValue = optionHeaders[header];\n    if (headerValue) {\n      headers.set(header, headerValue);\n    }\n  });\n\n  return headers;\n}\n\nfunction fetchRequest(\n  fetchApi: typeof fetch,\n  method: REQUEST_METHOD,\n  url: string,\n  opts: RequestOptions,\n): Promise<any> {\n  const { params, body, headers, signal } = opts;\n\n  const requestURL = params ? assembleUri(url, params) : url;\n\n  const requestParams: RequestInit = {\n    headers: buildHeaders(headers || {}),\n    method,\n    signal,\n  };\n\n  if (body) {\n    requestParams.body = typeof body === 'string' ? body : JSON.stringify(body);\n  }\n\n  return fetchApi(requestURL, requestParams);\n}\n\nfunction toJson(response: Response): Promise<any> {\n  if (response.status === 204 || response.body === null) {\n    return Promise.resolve({});\n  }\n\n  return response.json().then(json => {\n    return response.ok ? json : Promise.reject(json);\n  });\n}\n\nconst defaultOpts: RequestOptions = {\n  body: null,\n  headers: {},\n  params: null,\n};\n\nexport function get<T>(\n  fetchApi: typeof fetch,\n  url: string,\n  opts: RequestOptions = defaultOpts,\n): Promise<T> {\n  return fetchRequest(fetchApi, REQUEST_METHOD.GET, url, opts).then(toJson);\n}\n\nexport function post<T>(\n  fetchApi: typeof fetch,\n  url: string,\n  opts: RequestOptions = defaultOpts,\n): Promise<T> {\n  return fetchRequest(fetchApi, REQUEST_METHOD.POST, url, opts).then(toJson);\n}\n"],"names":[],"mappings":"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"}