Charles Forsyth Projects
Skywalker

UCR Research Computing · v0.34.2

Skywalker

GCP audit and reporting for a research cloud fleet.

Skywalker walks the Google Cloud hierarchy to give administrators visibility into the research fleet: security risks, wasted spend and operational hygiene across hundreds of projects.

It ships as a Python CLI and as an MCP server that answers "what is happening in my Google Cloud project?" for AI assistants. Both are read-only by default; the CLI's one write path (--fix) asks for confirmation.

  • Python
  • Google Cloud client libraries
  • Pydantic schemas
  • uv
View on GitHub Release v0.34.2 Get started
skywalker 
# Audit specific services in specific regions
$ skywalker --project-id my-lab-project \
    --services compute storage --regions us-west1

# Find wasted resources across ALL projects in the org
$ skywalker --find-zombies

# Live dashboard of top CPU/Memory consumers
$ skywalker --monitor --limit 20

# Fleet-wide model usage, sorted by estimated cost
$ skywalker --all-projects --model-audit \
    --sort-by estimated_cost

# Report for stakeholders
$ skywalker --all-projects --html fleet_report.html

What it does

Key capabilities

Scan one project or the whole organization, then act on what it finds. Each mode is a CLI flag.

Deep audit

Resources across 9 GCP services: Compute Engine, Storage, IAM, Network, GKE, Cloud Run, Cloud SQL, Filestore and Vertex AI.

Fleet performance

Aggregates CPU, memory and GPU metrics from many VMs into one "Mission Control" dashboard. Finds overloaded instances and VMs missing the Ops Agent.

Zombie Hunter

Orphaned disks, unused static IPs and buckets with zero egress for 30 days, with an estimate of potential monthly savings.

Fix-It mode

Installs the Google Cloud Ops Agent on Linux VMs over SSH through IAP tunneling, to close monitoring blind spots. Interactive and scoped.

Model usage and cost

Queries Cloud Monitoring for Vertex AI and publisher model request and token counts, then prices them from a model price map.

API key audit

Deep API key audit with request counts and estimated cost per key (--api-key-audit).

Billing reports

Queries a BigQuery billing export for gross and net cost reports (--billing-report).

Reports and JSON

Render audits to HTML or PDF for stakeholders, export fleet data to CSV, or emit structured JSON.

MCP server

Questions about a project, answered in one call

The MCP server, built on the skywalker.intel library in this repo, exposes read-only tools for Claude, Gemini Enterprise, Hermes and other programs. Google's own remote MCP servers expose raw APIs one call per tool; Skywalker is the layer above them, joining APIs and the billing export into findings.

ToolRoleWhat it answers
skywalker_overviewreadFindings first, then spend and 7-day trend, budget, VMs and GPUs, idle disks and IPs, IAM risks, exposure, admin changes
skywalker_spendreadBilling export: gross, credits, net by service, SKU, day or region
skywalker_computereadVMs, GPUs, spot, external IPs, days stopped; unattached disks first
skywalker_recommendationsreadRecommender: idle resources, rightsizing, unused IAM roles, with monthly savings
skywalker_accessreadIAM policy with risky grants flagged
skywalker_exposurereadPublic IAM bindings, open admin ports, VMs with external IPs, SCC findings
skywalker_activityreadAdmin Activity audit log: who changed what
skywalker_fleetstaffEvery project: spend leaders, risers, budgets over 100%, running VMs, public access

A selection of the tools; the MCP server README lists all of them, plus endpoints, configuration and client setup for Claude Code, Hermes and claude.ai.

How it works

Walkers, schemas and modes

Modular "walkers" query each service through the official Google Cloud Python clients, results are validated against strict Pydantic schemas, and modes turn them into tables, dashboards and reports. A ThreadPoolExecutor scans many projects in parallel. The CLI always fetches fresh data.

Google Cloud

Compute, Storage, IAM, GKE, Run, SQL, Filestore, Vertex AI, Monitoring, Asset Inventory, BigQuery billing export.

Skywalker core

  • Centralized client factory
  • Walkers: one per service
  • Pydantic schemas
  • Parallel project scans
  • skywalker.intel: per-caller, JSON-only library

CLI modes

audit, monitor, zombies, fix, model usage, API keys, billing.

Outputs

Rich terminal tables, JSON, CSV, HTML and PDF reports.

MCP server

Streamable HTTP at /mcp, OAuth 2.1 sign-in, acting as the caller.

Safety

Read-only by default

  • CLI: read-only except --fixRemediation must be interactive and scoped; it asks for confirmation before installing anything.
  • MCP: read-only, enforced in codeThe intel layer refuses every request that is not a GET or one of three read RPCs before it leaves the process. There are no write tools.
  • Acts as the callerEvery MCP tool call runs on the signed-in person's own Google access token, so they see exactly what their account can see and Google's audit logs name them. The server's service account has no Google Cloud data roles.
  • Sealed tokensEach person's Google refresh token is sealed with AES-256-GCM in the store. Access and refresh tokens are stored hashed and sealed.
  • Roles, limits and auditRoles checked on every call, tool list filtered per caller, per-person and per-client rate limits, and one JSON audit line per sign-in and tool call.
  • Bounded billing queriesEvery billing query filters on the export's partition column and sets a maximum bytes billed cap.
  • No secrets in outputSecrets are never printed. API key strings are never read by the MCP tools. CI checks the repo for keys.
  • Tested guardsA mutation check verifies that disabling any guard makes a test fail.

Newer on master (after v0.34.2): per-person project scope for read users and an A2A agent for Gemini Enterprise that runs through the same role checks, limits and audit.

Quick start

Install and run

Skywalker is packaged with uv. From a clone of the repo, install the tool, then run it with your own Google Cloud credentials. Project names below are placeholders.

Install

git clone https://github.com/charles-forsyth/Skywalker.git
cd Skywalker
uv tool install . --force

Standard audit

# Audit a single project for all services
skywalker --project-id my-lab-project

# Model usage over the last 30 days, as JSON
skywalker --all-projects --model-audit --json

Remediation (Fix-It)

# Install Ops Agent on VMs in the monitoring scope missing it
skywalker --fix ops-agent --monitor

Add the MCP server to a client

claude mcp add --transport http skywalker <URL>/mcp
hermes mcp add skywalker --url <URL>/mcp --auth oauth

Contributing: feature branch, tests with pytest, typing with mypy src, formatting with ruff format ., then a pull request.