SpectreHub Docs

← spectrehub.dev

Quick Reference

brew install ppiankov/tap/spectrehub     # install
spectrehub activate sh_live_...          # activate license
spectrehub run                           # scan (local only)
spectrehub run --store                   # scan + store locally + upload if licensed
spectrehub run --format json -o out.json # JSON output
spectrehub diff                          # what changed since last run
spectrehub diff --fail-new               # exit 1 if new issues (CI gate)
spectrehub export --format csv -o e.csv  # compliance evidence
spectrehub export --format sarif         # GitHub Advanced Security

Security & Data Model

What SpectreHub touches, what it doesn't, and when data leaves your machine.

Guarantees

• SpectreHub MUST be read-only. It runs audit tool binaries and reads their stdout. It does not modify infrastructure, write to databases, or change cloud resources.
• SpectreHub does not access or log environment variable contents. It checks presence only (e.g., is VAULT_ADDR set?) to determine which tools can run. Even with --verbose, SpectreHub never prints env var values. The audit tools themselves access infrastructure; SpectreHub only reads their JSON output.
• SpectreHub NEVER uploads without --store. spectrehub run prints results to stdout. Nothing leaves your machine. spectrehub run --store stores locally and uploads to the API only if a valid license key is configured.
• SpectreHub NEVER executes arbitrary commands. It runs only binaries from a hardcoded allowlist: vaultspectre, s3spectre, kafkaspectre, clickspectre, pgspectre, mongospectre, awsspectre, iamspectre, gcsspectre, gcpspectre. Each is invoked with its registered subcommand and --format json. If a binary is not in the allowlist, SpectreHub will not run it even if it is named *spectre.

Assumptions

• SpectreHub assumes the installed audit binaries are trusted (e.g., installed via Homebrew or GitHub Releases). If an attacker can replace vaultspectre in PATH, they can subvert results.
• Audit tools are responsible for not printing secrets in their JSON output. SpectreHub does not redact tool output. If a tool leaks a secret to stdout, that is a bug in the tool, not in SpectreHub.
• If a tool fails (crash, timeout, non-zero exit), SpectreHub logs the error, marks that tool as failed in the report, and continues with the remaining tools. Partial results are still aggregated.

What gets uploaded (with --store + license)

• Repo identifier (from --repo flag or config)
• Tool count, issue count, health score
• Aggregated JSON: issue categories, severities, resource identifiers, recommendations

Resource identifiers are infrastructure names like s3://bucket-name, kafka:topic-name, vault:secret/path, db.table_name. These are names, not contents. If your naming convention encodes sensitive information in resource names, be aware those names will be uploaded.

What never gets uploaded

• Secret values, tokens, passwords, connection strings
• Raw tool output (only the normalized aggregation)
• Source code, file contents, environment variable values

Getting Started

Install, activate, scan, review.

1. Install SpectreHub

brew install ppiankov/tap/spectrehub

Or from source:

go install github.com/ppiankov/spectrehub/cmd/spectrehub@latest

2. Install audit tools

Install the tools for the infrastructure you want to audit. Each is a standalone binary:

brew install ppiankov/tap/vaultspectre    # HashiCorp Vault
brew install ppiankov/tap/s3spectre       # AWS S3
brew install ppiankov/tap/awsspectre      # AWS resource waste (EC2, EBS, RDS, ALB, NAT GW)
brew install ppiankov/tap/iamspectre      # AWS & GCP IAM audit
brew install ppiankov/tap/gcsspectre     # GCP Cloud Storage
brew install ppiankov/tap/gcpspectre     # GCP Compute, Disks, SQL, IPs
brew install ppiankov/tap/kafkaspectre    # Apache Kafka
brew install ppiankov/tap/pgspectre       # PostgreSQL

Each tool requires its own environment variables to connect to infrastructure. See the tool configuration table below.

3. Check your setup

spectrehub doctor

Doctor validates everything end-to-end: config file, license key, API connectivity, repo identifier, installed tools, and storage. Fix any issues it reports before running your first scan.

4. Run your first scan

spectrehub run

No SpectreHub config file is required for a first run. SpectreHub discovers installed tool binaries in your PATH, checks which have their target environment variables set, and runs them.

$ spectrehub run
Discovered 4 tool(s), 4 runnable

  vaultspectre   ✓ ready
  pgspectre      ✓ ready
  kafkaspectre   ✓ ready
  clickspectre   ✓ ready

Total Issues: 40
Health Score: GOOD (91%)

Recommendations:
  1. [CRITICAL] Fix 8 missing Vault secrets
  2. [HIGH] Clean up 7 unused Kafka topics
  3. [MEDIUM] Review 18 stale ClickHouse tables

5. Activate your license (paid tiers)

After purchasing a Team or Organization plan, you receive a license key by email. Activate it:

spectrehub activate sh_live_your_key_here

This validates the key against the SpectreHub API and writes it to your config file. The default write path is ~/.spectrehub.yaml (or $XDG_CONFIG_HOME/spectrehub/spectrehub.yaml if XDG is set). Override with --config /path/to/file.yaml.

For CI, set the key as an environment variable instead:

export SPECTREHUB_LICENSE_KEY=sh_live_your_key_here

6. Store and upload reports

After activation, use --store to save reports locally and upload to the API. The --repo flag is required for upload:

spectrehub run --store --repo my-org/my-repo

Other output options:

spectrehub run --format json -o report.json   # JSON to file
spectrehub run --store --repo my-org/my-repo   # tag report with repo name
spectrehub diff                                 # compare last two runs

Configuration

Config file or environment variables. Both optional for local usage.

Config file

SpectreHub looks for config in this order:

• ./spectrehub.yaml (current directory)
• ~/.spectrehub.yaml (home directory)
• $XDG_CONFIG_HOME/spectrehub/spectrehub.yaml

Override with --config /path/to/spectrehub.yaml.

Sample config:

# ~/.spectrehub.yaml

# Directory to store reports locally
storage_dir: .spectre

# Fail if issues exceed this count (0 = disabled)
fail_threshold: 50

# Output format: text, json, or both
format: text

# Number of runs to keep for trend analysis
last_runs: 7

# Repository identifier (required for upload)
# Also settable via --repo flag or SPECTREHUB_REPO env var
repo: my-org/my-repo

# License key (paid features)
# Also settable via SPECTREHUB_LICENSE_KEY env var
license_key: sh_live_your_key_here

# API URL (change only for testing)
# api_url: https://api.spectrehub.dev

SpectreHub environment variables

All config values can be set via environment variables with the SPECTREHUB_ prefix:

Tool environment variables

Each audit tool reads its own environment variables to connect to infrastructure. SpectreHub checks whether these exist to determine which tools can run. It reads presence only, never values.

Health Score

Deterministic arithmetic. No ML, no heuristics.

Health score is the percentage of audited resources with zero issues:

affected   = count(unique resources with at least one issue)
score      = (total_resources - affected) / total_resources * 100
score      = clamp(score, 0, 100)

total_resources is the count of distinct resources across all tools (Vault references, S3 buckets, Kafka topics, database tables, etc.). affected is the count of unique resources that have at least one finding — a resource with 5 issues counts the same as a resource with 1. The result is clamped to 0–100.

Example: 100 resources, 7 have issues → score = (100 - 7) / 100 * 100 = 93.0 → GOOD

Run spectrehub explain-score to see the full calculation step by step after a stored run:

$ spectrehub explain-score
Health Score Breakdown
======================

1. Resources per tool:
   pgspectre        42 resources, 3 issues, 3 affected
   s3spectre        18 resources, 2 issues, 2 affected
   vaultspectre     40 resources, 2 issues, 2 affected
                    100 resources total

2. Affected resources: 7 distinct

3. Formula:
   score = (total - affected) / total * 100
   score = (100 - 7) / 100 * 100 = 93.0

4. Thresholds:
     ≥ 95%  excellent
   → ≥ 85%  good
     ≥ 70%  warning
     ≥ 50%  critical
     ≥ 0%   severe

Result: GOOD (93.0%)

Also available as JSON (spectrehub explain-score --format json) for scripting. Per-tool resource counts are under summary.score_percent, summary.health_score, and summary.total_issues in the report output.

Interactive TUI

Browse audit results interactively in your terminal.

When spectrehub summarize runs in a TTY, it automatically launches an interactive TUI built with bubbletea. You can also force it with --tui:

spectrehub summarize           # auto-TUI when in a terminal
spectrehub summarize --tui     # force TUI
spectrehub summarize -f json   # bypass TUI, output JSON

The TUI displays:

• Health score header with trend indicators
• Filterable table of findings by tool, severity, and status
• Detail view for individual findings

Keyboard shortcuts:

• ↑/↓ or j/k — navigate rows
• enter — open detail view
• esc — back / close
• / — filter
• q — quit

CI/CD Integration

GitHub Action or any CI runner.

GitHub Action

- name: SpectreHub Audit
  uses: ppiankov/spectrehub-action@v1
  with:
    threshold: 50
  env:
    SPECTREHUB_LICENSE_KEY: ${{ secrets.SPECTREHUB_LICENSE_KEY }}
    VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
    VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }}

The action installs tools, discovers configured targets from repository secrets, runs audits, and posts results as a PR comment. Exit code 1 if issues exceed your threshold.

Any CI system

SpectreHub is a single binary with deterministic exit codes (see Exit Codes for per-command details):

# GitLab CI, CircleCI, Jenkins, etc.
spectrehub run --store --repo org/name --fail-threshold 50 --format json -o report.json

Health Alerts

Team and Organization tiers. Email when health degrades.

Health alerts trigger when the API detects a significant score drop between consecutive reports for the same repo. No configuration needed — alerts activate automatically once you have a license key and at least two stored runs for a repo.

Alert conditions

• Score drop: health score falls 10+ points from the previous run for the same repo
• Critical threshold: health score drops below 60
• Cooldown: maximum one alert per repo per 24 hours
• Minimum runs: no alert on first run for a repo (requires at least two submissions to compare)

Who receives alerts

Alerts are sent to the email address associated with your license key (the email used at checkout). Recipients are not currently configurable per-repo.

Example alert

Subject: SpectreHub: health degraded for org/api

Score: 91 → 72
New issues: 14

Run spectrehub run to see full details.

PR Drift Delta

Team and Organization tiers. Catch regressions before merge.

The spectrehub diff command compares two audit runs and shows exactly what changed: new issues introduced and old issues resolved.

Basic usage

# Compare the two most recent stored runs
spectrehub diff

# Compare against a specific baseline file
spectrehub diff --baseline ./main-branch-report.json

# Fail CI if new issues were introduced
spectrehub diff --fail-new

Output

$ spectrehub diff
Drift Delta: 2 new, 1 resolved

New issues:
  [HIGH] kafkaspectre/unused_topic — events.dlq
  [MEDIUM] pgspectre/idle_role — readonly_user

Resolved:
  [HIGH] vaultspectre/missing_secret — config/db_password

Summary: +1 high, +1 medium, -1 high

CI gating

Use --fail-new in CI to block PRs that introduce new issues:

# In CI: run baseline scan on main, then diff on PR branch
spectrehub run --store --format json -o baseline.json
# (checkout PR branch, run again)
spectrehub diff --baseline baseline.json --fail-new

Exit code 1 if any new issues are found. JSON output available with --format json.

Compliance Exports

Organization tier. Evidence artifacts for SOC2, ISO 27001, and GitHub Security.

The spectrehub export command generates evidence artifacts from stored audit runs. These are supporting documents for compliance — not attestations or certifications. Your auditor determines how to use them.

Formats

Usage

# Export last run as CSV
spectrehub export --format csv -o audit-evidence.csv

# Export last 30 runs as JSON
spectrehub export --format json --last 30 -o evidence.json

# SARIF for GitHub Advanced Security
spectrehub export --format sarif -o results.sarif --last 1

CSV columns

Each row is one issue from one run:

run_timestamp, tool, category, severity, resource, evidence, status, health_score, score_percent

SARIF integration

Upload SARIF to GitHub to surface SpectreHub findings in the Security tab:

# In GitHub Actions
- name: Export SARIF
  run: spectrehub export --format sarif -o results.sarif --last 1

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Policy Enforcement

Organization tier. Define rules, fail CI on violations.

Create a .spectrehub-policy.yaml file in your repository root. SpectreHub evaluates it automatically during spectrehub run and exits with code 1 on violations.

Policy file

# .spectrehub-policy.yaml
version: "1"
rules:
  # Maximum total issues allowed
  max_issues: 100

  # Zero tolerance for critical findings
  max_critical: 0

  # Cap high-severity issues
  max_high: 10

  # Minimum health score (0-100)
  min_score: 70.0

  # Block specific issue categories
  forbid_categories:
    - missing_secret
    - public_access

  # Require these tools to be present in every run
  require_tools:
    - vaultspectre
    - s3spectre

Available rules

All rules are optional. Omit any rule to skip that check. The policy file is searched in the current directory and parent directories up to the filesystem root.

CI example

# .github/workflows/audit.yml
- name: SpectreHub Audit
  run: spectrehub run --store
  env:
    SPECTREHUB_LICENSE_KEY: ${{ secrets.SPECTREHUB_LICENSE_KEY }}
# Policy file in repo root is picked up automatically.
# Exit code 1 on any violation.

Billing & Subscription

Manage your plan, update payment, view invoices.

Plans

Managing your subscription

After purchasing, visit your welcome page on spectrehub.dev and click "Manage subscription" to access the Stripe billing portal. From there you can:

• Update your payment method
• View and download past invoices
• Cancel your subscription

License lifecycle

Your license stays active as long as your Stripe subscription is active. If you cancel, the license is deactivated at the end of your billing period. If payment fails, Stripe retries automatically — the license remains active during retries. Local CLI usage always works regardless of license status.

Repo limits

The --repo flag (or repo in config) is required for upload. The API rejects reports without a repo identifier because trends, policy, alerts, and repo-limit enforcement all depend on it.

The Team plan tracks up to 5 unique repositories. Once 5 distinct repos have submitted reports, new repos are rejected until you upgrade. Existing repos continue to work. Organization plan has no repo limit.

Exit Codes

Deterministic per-command exit codes for scripting and CI.

Without --fail-new, diff always exits 0 (drift is informational). export exits 0 even if the export is empty (no stored runs).

Troubleshooting

Common problems and how to fix them.

"Discovered 0 tool(s), 0 runnable"

SpectreHub found no audit tool binaries in your PATH. Check that at least one tool is installed:

which vaultspectre s3spectre kafkaspectre pgspectre clickspectre mongospectre awsspectre iamspectre gcsspectre gcpspectre

If tools are installed but outside your PATH, add their directory to PATH before running SpectreHub.

"Tool X: not runnable" or "missing env vars"

The tool binary was found but its required environment variables are not set. See the tool configuration table for which variables each tool needs. SpectreHub checks presence only — if the variable exists but has a wrong value, the tool will be marked runnable but may fail during execution.

"Tool X: failed" in results

The tool started but exited with an error. Common causes: wrong credentials, target unreachable, timeout. Run the tool directly to see the full error:

# Run a single tool directly to see its error output
vaultspectre audit --format json

# Run SpectreHub with verbose output
spectrehub run --verbose

"repo is required" on upload

The API requires a repo identifier for every report. Add --repo org/name to your command or set repo in your config file.

spectrehub run --store --repo my-org/my-repo

Running a single tool

To audit only one tool without running all discovered tools:

spectrehub run --tool vaultspectre

Where are local reports stored?

By default in .spectre/ under the current directory (or the storage_dir value in config). Each run creates a timestamped JSON file. To delete stored reports, remove the files from that directory:

ls .spectre/
rm -i .spectre/report-2026-01-15T10:30:00.json   # confirm before deleting

What SpectreHub is NOT

Boundaries prevent misunderstanding.

• Not a monitoring system. SpectreHub runs on demand (locally or in CI). It does not poll, schedule, or watch infrastructure in real time.
• Not a compliance certification. Exports are evidence artifacts. Your auditor, not SpectreHub, determines compliance status.
• Not a vulnerability scanner. SpectreHub audits operational hygiene (drift, waste, misconfiguration). It does not scan code, containers, or dependencies for CVEs.
• Not a web dashboard. The interactive TUI is terminal-only. There is no browser UI beyond the static site. Reports are JSON, text, or the TUI on stdout.
• Not a secrets manager. SpectreHub checks whether secrets exist where they should. It never reads, stores, or transmits secret values.
• Not a remediation engine. SpectreHub presents findings and lets you decide. It never modifies infrastructure.