spectre/v1 Schema

← spectrehub.dev · docs

All Spectre family tools emit a unified JSON format called spectre/v1. This page documents the format, its constraints, and how to validate against it.

Download: spectre-v1.schema.json (JSON Schema draft 2020-12)

Why a published schema

Neither Checkov, Trivy, kube-bench, nor Steampipe publishes a formal versioned JSON schema. This creates friction for anyone building tooling on top of these tools. A stable, published schema turns SpectreHub from a product into a standard.

Third-party tools can validate their output against the schema
CI can reject malformed reports before aggregation
Schema stability builds trust — if the format changes, it gets a new version

Envelope structure

{
  "schema": "spectre/v1",
  "tool": "vaultspectre",
  "version": "0.3.1",
  "timestamp": "2026-02-24T10:30:00Z",
  "target": {
    "type": "vault",
    "uri_hash": "a1b2c3..."
  },
  "findings": [
    {
      "id": "vault-missing-secret",
      "severity": "high",
      "location": "secret/api/stripe-key",
      "message": "Secret referenced in config but missing from Vault"
    }
  ],
  "summary": {
    "total": 1,
    "high": 1,
    "medium": 0,
    "low": 0,
    "info": 0
  }
}

Required fields

Field	Type	Description
schema	string	Must be exactly "spectre/v1"
tool	string	Tool name (e.g., vaultspectre)
version	string	Semver of the tool
timestamp	string	ISO 8601 datetime
target.type	string	One of: s3, postgres, kafka, clickhouse, vault, mongodb, aws-account, gcp-project, gcs, gcp-projects
findings	array	Array of finding objects (may be empty)
summary.total	integer	Must equal len(findings)

Finding fields

Field	Type	Required	Description
id	string	yes	Stable identifier for drift tracking
severity	string	yes	high, medium, low, or info
location	string	yes	Resource path where finding was observed
message	string	yes	Human-readable description

Validation

Use spectrehub validate to check any JSON file against the schema:

$ spectrehub validate report.json
VALID: conforms to spectre/v1

$ spectrehub validate bad.json
INVALID: findings[0]: missing required field 'id'

Or validate with any JSON Schema toolchain:

# Python
pip install jsonschema
python -c "
import json, jsonschema
schema = json.load(open('spectre-v1.schema.json'))
report = json.load(open('report.json'))
jsonschema.validate(report, schema)
print('valid')
"

# Node.js
npx ajv validate -s spectre-v1.schema.json -d report.json

Target type mapping

Tool	target.type
vaultspectre	vault
s3spectre	s3
kafkaspectre	kafka
clickspectre	clickhouse
pgspectre	postgres
mongospectre	mongodb
awsspectre	aws-account
iamspectre (AWS)	aws-account
iamspectre (GCP)	gcp-project
gcsspectre	gcs
gcpspectre	gcp-projects

Versioning

The schema identifier is spectre/v1. If breaking changes are needed, a new version (spectre/v2) will be published alongside. SpectreHub will continue to accept spectre/v1 reports indefinitely.

Non-breaking additions (new optional fields) do not change the version number. The schema uses additionalProperties: false in the formal JSON Schema to enforce strictness, but SpectreHub's runtime validator is lenient with unknown fields.