platform-doctor

platform-doctor is a lightweight platform sanity checker for small teams that want fewer infrastructure surprises.

It scans a repository for common platform risks and writes a practical report with a score, prioritized findings, and next steps.

What It Checks

• GitHub Actions workflows with missing or broad token permissions.
• Dockerfiles that do not set a non-root USER.
• Kubernetes workloads missing resource requests or limits.
• Missing runbook or rollback documentation.
• Missing budget, cost alert, anomaly alert, or spend-limit documentation.

Install

From this repository:

go install ./cmd/platform-doctor

Or run without installing:

go run ./cmd/platform-doctor scan /path/to/repo --output platform-doctor-report.md

Usage

platform-doctor scan /path/to/repo --output platform-doctor-report.md

JSON output is also available:

platform-doctor scan /path/to/repo --output platform-doctor-report.json
platform-doctor scan /path/to/repo --format json --output -

The command exits with a nonzero status when critical findings exist, so it can run in CI.

Example Output

# Platform Doctor Report

Platform Doctor Score: 48/100

- Target: `/repo`
- Findings: 2 critical, 2 high, 1 medium, 0 low

## Critical

### GitHub Actions workflow grants write-all permissions

- Category: `security`
- File: `.github/workflows/deploy.yml`
- Detail: `permissions: write-all` grants every available token scope write access for the workflow.
- Next step: Replace `write-all` with explicit read/write scopes required by each job.

## Next 7 Days

1. Replace `write-all` with explicit read/write scopes required by each job.
2. Document the exact command or procedure for rolling back a failed deploy.
3. Add cost guardrail documentation with budget owners, alert thresholds, and the expected response when spend spikes.

Development

Run tests:

go test ./...