Documentationbreadcrumb arrow breadcrumb arrow GlaberGraph documentationbreadcrumb arrow Administrationbreadcrumb arrow Plugin managementbreadcrumb arrow Plugin signatures

Plugin signatures

Plugin signature verification, also known as signing, is a security measure to make sure plugins haven’t been tampered with. Upon loading, Grafana checks to see if a plugin is signed or unsigned when inspecting and verifying its digital signature.

Learn more at plugin policies.

How does verification work?

At startup, Grafana verifies the signatures of every plugin in the plugin directory.

To see the result of this verification for each plugin, navigate to Configuration -> Plugins. A signature can have any of the following signature status:

Signature status Description
Core Core plugin built into Grafana.
Invalid signature The plugin has an invalid signature.
Modified signature The plugin has changed since it was signed. This may indicate malicious intent.
Unsigned The plugin is not signed.
Signed The plugin signature was successfully verified.

What happens if a plugin is not signed?

If a plugin is unsigned, then Grafana neither loads nor starts it. Grafana also writes an error message to the server log:

Bash 
WARN[05-26|12:00:00] Some plugin scanning errors were found   errors="plugin '<plugin id>' is unsigned, plugin '<plugin id>' has an invalid signature"

How Grafana finds the signing key

To verify a signature, Grafana needs the public key that matches the key ID of the plugin. The signed manifest in MANIFEST.txt stores this key ID in the keyId field. Grafana resolves the key ID against two key sources, in this order:

  1. Downloaded keys. When dynamic key retrieval is enabled, Grafana reads the key from the plugin.publickeys keyspace in its database. Grafana fills that keyspace from the API server, so it only holds the keys that the catalog publishes.
  2. Built-in keys. Grafana falls back to the key set compiled into the binary when the first source has no entry for the key ID. This set contains the Grafana Labs key and any other key that the build includes.

Grafana queries the downloaded keys first, and uses the built-in keys only when the dynamic source fails to return a key. A plugin signed with a key that the catalog doesn’t publish is therefore still verified, as long as that key is part of the build. The reverse applies too: a plugin signed with a catalog key that the build doesn’t include can’t be verified when dynamic retrieval is disabled.

Note

Dynamic key retrieval fails inside an isolated network, because Grafana can’t reach the API server. Grafana writes Error downloading plugin manifest keys to the server log at startup in that case. Refer to public_key_retrieval_disabled to stop the download and verify plugin signatures with the built-in keys only.

Plugin signature levels

All plugins are signed under a signature level. The signature level determines how the plugin can be distributed.

Plugin Level Description
Private

Private plugins are for use on your own Grafana. They may not be distributed to the Grafana community, and are not published in the Grafana catalog.
Community

Community plugins have dependent technologies that are open source and not for profit.

Community plugins are published in the official Grafana catalog, and are available to the Grafana community.
Commercial

Commercial plugins have dependent technologies that are closed source or commercially backed.

Commercial plugins are published on the official Grafana catalog, and are available to the Grafana community.

Allow unsigned plugins

Note

Unsigned plugins are not supported in Grafana Cloud.

We strongly recommend that you don’t run unsigned plugins in your Grafana instance. However, if you’re aware of the risks and you still want to load an unsigned plugin, refer to Configuration.

If you’ve allowed loading of an unsigned plugin, then Grafana writes a warning message to the server log:

Bash 
WARN[06-01|16:45:59] Running an unsigned plugin   pluginID=<plugin id>

Note

If you’re developing a plugin, then you can enable development mode to allow all unsigned plugins.

Sign a plugin you’ve developed

If you are a plugin developer and want to know how to sign your plugin, refer to Sign a plugin.