@kansodata/kansodata-grafana-plugin

OpenClaw external plugin and operational skill for secure Grafana diagnostics.

Current Scope (v0.1.0)

This version is read-focused and hardened by default:

• Read-only Grafana API tools for health, dashboards, datasources, alert rules, and folders
• Explicit action gates with fail-closed defaults for future write operations
• Config validation, token redaction, normalized HTTP errors, and timeout controls
• Operational skill for inspect/diagnose/propose workflows

Not Included Yet

• Real write operations (create/update dashboards or alert rules)
• Destructive actions (delete dashboards/rules)
• Grafana user/role/permission administration

Prerequisites

• Node.js >=22.14.0
• Access to a Grafana instance API
• Grafana service-account token with minimum required read permissions

Install

npm install
npm run build

Configuration

Primary configuration comes from env vars (or OpenClaw plugin config with same keys).

Action Gates (default policy)

{
  "read": true,
  "create": false,
  "update": false,
  "delete": false,
  "alerting_write": false
}

Available Tools

Read-only tools:

• grafana_health_check
• grafana_list_dashboards
• grafana_get_dashboard
• grafana_export_dashboard_json
• grafana_list_datasources
• grafana_list_alert_rules
• grafana_list_folders

Future-write stubs (explicitly disabled in v1):

• grafana_create_dashboard
• grafana_update_dashboard
• grafana_clone_dashboard
• grafana_create_alert_rule
• grafana_update_alert_rule

Usage Examples

See:

• docs/examples.md
• docs/scope.md
• skills/kansodata-grafana-authoring-operations/SKILL.md

Alert Rules Compatibility

grafana_list_alert_rules now uses safe endpoint fallback:

1. GET /api/v1/provisioning/alert-rules (primary)
2. GET /api/alert-rules (legacy fallback on 404)

The client also maps non-array grouped payloads into a flat compact output for agents.

Security Posture

• No token logging (redaction helper enforced)
• No sensitive header dump
• Fail-closed on invalid config
• Safe error normalization for 401/403/404/5xx and timeout
• Read-only by default with explicit gates for future writes

Quality Commands

npm run lint
npm run typecheck
npm run build
npm test
npm pack

Optional Real Integration Validation

When GRAFANA_URL and GRAFANA_TOKEN are available, integration tests run:

npm test

If env vars are missing, integration tests are skipped automatically and only unit tests run.

Short Roadmap

1. Implement gated create/update with dry-run and policy checks.
2. Add diff-based dashboard proposal/apply flow.
3. Add alert rule proposal/apply flow with stronger context checks.
4. Expand integration tests with real Grafana sandbox environment.