UpGuard Plugin for Steampipe

Use SQL to query vendors, risks, domains, IPs, vulnerabilities, and breaches from UpGuard CyberRisk.

• Get started →
• Community: Join #steampipe on Slack →
• Get involved: Issues

Quick start

Install

Install the plugin with Steampipe:

steampipe plugin install ghcr.io/vthiery/upguard

Configure

Copy the sample config and set your API key:

cp config/upguard.spc ~/.steampipe/config/upguard.spc

Edit ~/.steampipe/config/upguard.spc:

connection "upguard" {
  plugin  = "ghcr.io/vthiery/upguard"

  # API key from your UpGuard CyberRisk Account Settings → API keys
  # Required API key permissions depend on the tables you query:
  # - Platform: Required for upguard_available_risk, upguard_organisation
  # - VendorRisk: Required for upguard_vendor* tables
  # - BreachRisk: Required for upguard_domain, upguard_ip, upguard_organisation_risk, upguard_vulnerability
  # - IdentityBreaches: Required for upguard_breach
  # See https://cyber-risk.upguard.com/api/docs for details
  api_key = "YOUR_API_KEY"
}

API Permissions

Different tables require different API key permissions:

Permission	Required For
Platform	upguard_available_risk, upguard_organisation
VendorRisk	upguard_vendor, upguard_vendor_risk, upguard_vendor_domain, upguard_vendor_ip
BreachRisk	upguard_domain, upguard_ip, upguard_organisation_risk, upguard_vulnerability
IdentityBreaches	upguard_breach

You can configure API key permissions in your UpGuard CyberRisk account settings.

Run a query

steampipe query

-- List all monitored vendors with their security scores
select
  name,
  primary_hostname,
  score,
  tier,
  industry_group
from
  upguard_vendor
order by
  score desc;

Tables

Table	Description
upguard_vendor	List and inspect monitored vendors.
upguard_vendor_risk	List active risks for a specific vendor.
upguard_vendor_domain	List domains for a specific vendor.
upguard_vendor_ip	List IP addresses for a specific vendor.
upguard_domain	List and inspect domains in your account.
upguard_ip	List and inspect IP addresses in your account.
upguard_available_risk	List all available risk types in the platform.
upguard_organisation	Get information about your organization.
upguard_organisation_risk	List active risks for your organization.
upguard_vulnerability	List potential vulnerabilities detected.
upguard_breach	List identity breaches detected.

Development

Prerequisites

• Steampipe
• Golang

Build and Install

make install

Configure the plugin:

cp config/upguard.spc ~/.steampipe/config/upguard.spc
vi ~/.steampipe/config/upguard.spc

Testing

Run a smoke query against every table:

make test

The test script (scripts/test_tables.sh) builds the plugin, queries each table, and reports pass/fail/skip (scope-restricted tables are skipped rather than failed).

Important Notes

API Behavior

Some tables exhibit different behavior depending on how you query them due to UpGuard API design:

• upguard_vendor: Querying by id or primary_hostname returns full details including first_monitored and reassessment_date. Listing vendors (e.g., by tier) returns summary data where some fields may be NULL.

• upguard_domain: Querying by hostname returns full details including automated_score and scanned_at. Listing domains returns only basic fields.

This is expected behavior. See docs/API_INCONSISTENCY.md for technical details.

Developer Documentation

• API_INCONSISTENCY.md - How the plugin handles LIST vs GET endpoint differences
• FIELD_MAPPING_FIXES.md - Field mapping corrections and API investigations

Further reading

• Writing plugins
• UpGuard API reference