> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/tools/grafana-datasource.md).

# Grafana Data Source

The Nullify Grafana data source plugin (`nullify-grafana-datasource`) lets you visualize your Nullify scan results and trends directly in Grafana. Point the data source at the Nullify API and build dashboards for SAST, SCA, and Secrets findings and events.

{% hint style="info" %}
This plugin can only be installed on a self-hosted (local / on-prem) Grafana instance. Grafana Cloud is **not** currently supported.
{% endhint %}

## Installation

1. Install the plugin into your Grafana server instance following the [Grafana plugin management guide](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-plugin-on-local-grafana).
2. Add a new **Nullify** data source. See the [Grafana data source management guide](https://grafana.com/docs/grafana/latest/administration/data-source-management/).
3. On the Nullify data source settings page, configure the connection (see below).
4. Import a dashboard JSON to start visualizing your data. See the [Grafana import dashboards guide](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).

## Configuration

The data source settings page ("Nullify API Settings") has three fields:

| Field                    | Description                                                                                                                                                                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nullify API Host URL** | The host name for the Nullify API, e.g. `https://api.YOUR_NULLIFY_ID.nullify.ai`.                                                                                                                                                              |
| **GitHub Owner ID**      | The globally unique numerical GitHub ID for your individual/organization account. This is the numeric ID, not your username or organization name. You can find it at `https://api.github.com/users/YOUR_GITHUB_USERNAME_OR_ORGANIZATION_NAME`. |
| **Nullify API Key**      | An API key for the Nullify API. Create one at `https://app.YOUR_NULLIFY_ID.nullify.ai/`. The key is stored as a secret and used only by the plugin's backend.                                                                                  |

## Query types

Each query targets one of six Nullify endpoints. Every query type supports scoping by repository (GitHub repository IDs or query strings) and by owner (team/user names or query strings), so panels can be filtered to a service, team, or repository. The **summary** queries report current finding state; the **events** queries report a time series of changes (new findings, fixes, allowlisting, and so on).

| Query type          | Endpoint          | Description                                                                                              |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| **SAST Summary**    | `sast/summary`    | Current SAST findings, filterable by repositories, owners, and severity.                                 |
| **SAST Events**     | `sast/events`     | Time series of SAST events, filterable by repositories, owners, branch, and event types.                 |
| **SCA Summary**     | `sca/summary`     | Current SCA findings, filterable by repositories, owners, and package.                                   |
| **SCA Events**      | `sca/events`      | Time series of SCA events, filterable by repositories, owners, branch, and event types.                  |
| **Secrets Summary** | `secrets/summary` | Current Secrets findings, filterable by repositories, owners, branch, secret type, and allowlist status. |
| **Secrets Events**  | `secrets/events`  | Time series of Secrets events, filterable by repositories, owners, branch, and event types.              |

### Event types

The events queries can be filtered to specific event types:

* **SAST events:** New Branch Summary, New Finding, New Fix, New Allowlisted Finding, New Unallowlisted Finding, New Pull Request Finding, New Pull Request Fix, New Pull Request Allowlisted Finding, New Pull Request Unallowlisted Finding.
* **SCA events:** New Branch Summary, New Finding, New Allowlisted Finding, New Fix, New Pull Request Finding, New Pull Request Fix.
* **Secrets events:** New Finding, New Allowlisted Finding.

## Template variables

The plugin ships a variable query editor with two variable types you can use to build dynamic, filterable dashboards:

* **Repository** — populate a variable with your repositories.
* **Owner** — populate a variable with owners (teams and users).