Hybrid Cloud Works Cloud Assessment
The lab edition of the Cloud Assessor: assess an Azure Resource Graph export against paraphrased FinOps, Well-Architected cost and Zero Trust criteria, in memory, with no cloud connectivity by design.
Upload the JSON that az graph query prints, or the CSV that Resource Graph Explorer downloads, and get a scorecard per
framework and pillar, a findings table with evidence, and a report bundle. The lab never connects to a cloud, never
asks for credentials and keeps nothing: an upload is processed in memory, returned only to the browser session that
holds its owner token, and expires after two hours or when deleted. Every scorecard states its coverage, because an
export cannot show spend, budgets, role assignments, diagnostic settings, policy state, Defender plans or traffic, and the
report says so in data (unknown), not only in prose. It is not an audit.
Where to try it. The pane is on the website at hybridcloudworks.com/tools/cloud-assessment;
you can also run it on your own machine with the Quick start below and open http://127.0.0.1:8080. Either way there is
no account and nothing to install in Azure: you export, you upload, you read.
Status: lab edition, not production. Limitations are recorded in VALIDATION.md. Every criterion's
reference link is marked [VERIFY] until the owner confirms it; the attribution wording awaits owner review
([REVIEW REQUIRED], R-005).
How the pieces relate
flowchart LR
App["HCW-CloudAssessor_App<br/>upstream: holds the engine and the appliance edition on Azure"]
subgraph AddOn["HCW-CloudAssessor_AddOn (this repository)"]
Core["packages/cloud-assessor-core<br/>engine seed: model · ingestion · catalog · evaluators · score · reports"]
Lab["src/cloud_assessment_lab<br/>lab edition: FastAPI, upload-only, in-memory"]
Pane["web/<br/>vanilla pane, HCW theme tokens"]
Core --> Lab --> Pane
end
Image["docker.io/hybridcloudworks/img-ca-lab-addon<br/>scanned, by digest"]
Host["lab host<br/>cloud-assessment.lab.hybridcloudworks.com (port 18083, loopback)"]
Site["hybridcloudworks.com<br/>/tools/cloud-assessment (sandboxed pane)"]
Lab -- "publish-images.yml on v* tags" --> Image
Image -- "website repo: addons Ansible role, digest in group_vars" --> Host
Host -- "frame + status proxy" --> Site
Core -. "seed adopted upstream (ADR-0001); the App now releases the engine" .-> App
App -. "every release: core-update PR (compatible / needs-adaptation)" .-> AddOn
The engine was seeded here so the lab could ship first, and the App has since adopted it unchanged
(docs/adr/ADR-0001-lab-edition-upload-only-and-python-engine-seed.md).
The App now owns the engine and has released it as v0.2.0 and v0.2.1. The dependency line in pyproject.toml
carries the marker CORE_REF v0.1.0-seed, so .github/workflows/core-update.yml (every six hours) sees the newer
release and opens the adoption pull request itself: it pins the wheel by URL, uv lock records its sha256, and the seed
copy is deleted. After that the same workflow brings each later release as a pull request tested against this edition's
suites.
What is behind, and the steps to adopt: docs/whats-new-upstream.md. Nothing here can reach Azure: tests/security/test_edition_boundary.py fails the build
if anything could, and publish-images.yml proves import azure fails inside the built image.
Connecting the website
| Concern | Where it is defined |
|---|
The catalogue row (id: cloud-assessment), the /tools/cloud-assessment route, the status proxy projection, the pane protocol (hcw-addon messages, four states), the sandbox and the downloads capability request, the environment table, the copy rules | docs/website-integration/integration-guide.md |
| The one site route, pre-render and route-inventory entry | docs/website-integration/routes.md |
The API the pane calls (/api/health, /api/config, /api/catalog, /api/sample.*, /api/assessments, bundle and file downloads, delete) | docs/api/openapi.yaml |
Hosting by the website's addons Ansible role: image by digest, env table, port 18083 on loopback, container hardening, the human-verification widget and vault key, Docker Hub publishing | docs/deployment/lab-host.md |
| Threats and controls (in-memory data, owner tokens, limits, fail-closed verification, edition boundary) | docs/security/threat-model.md |
Only public configuration crosses the boundary: the origin and the verification site key are public; the verification
secret lives in the lab host's vault (vault_addon_cloud_assessment_turnstile_secret), never in the site, Git or
Terraform state.
Quick start
Requires Python 3.14.6 or newer and uv 0.11.32 or newer.
uv python pin 3.14.6 && uv sync --all-packages
uv run pytest -q --cov=packages --cov=src # unit, contract, security, manifest; coverage gate 85
CA_ALLOW_NO_TURNSTILE=1 PORT=8080 uv run python -m cloud_assessment_lab # http://127.0.0.1:8080
curl -s http://127.0.0.1:8080/api/health
curl -s -X POST http://127.0.0.1:8080/api/assessments -H 'content-type: application/json' --data-binary @samples/sample-resource-graph.json
PowerShell:
uv python pin 3.14.6; uv sync --all-packages
uv run pytest -q --cov=packages --cov=src
$env:CA_ALLOW_NO_TURNSTILE = "1"; $env:PORT = "8080"; uv run python -m cloud_assessment_lab
Invoke-RestMethod http://127.0.0.1:8080/api/health
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/api/assessments -ContentType application/json -InFile samples/sample-resource-graph.json
CA_ALLOW_NO_TURNSTILE=1 is for local development and e2e only: without it and without TURNSTILE_SECRET, uploads
answer 503 turnstile_not_configured (fail closed). Browser suite: make e2e (Playwright chromium). Container:
docker compose up (hardened, loopback-only).
Repository map
| Path | What |
|---|
packages/cloud-assessor-core | The engine seed (pydantic only): model.py (MODEL_VERSION = 1), paths.py, ingestion/, catalog/ with criteria.json, schema.json, scoring.json, evaluate/ (six evaluator kinds), score.py, report/, redaction.py, and its tests |
src/cloud_assessment_lab | The lab application: config.py (CA_*), edition.py (import-time guard), store.py, security/ (verification, headers, CORS, limits, rate limit, content-free logging), routes/, app.py, __main__.py |
web/ | The pane: index.html, app.js, styles.css, theme.css (HCW tokens copied with provenance) |
samples/ | 40 fictional rows (subscription 00000000-0000-0000-0000-000000000001, hcw-sample-*, eastus2) in three export shapes; results pinned in a test |
tests/ | unit, contract (OpenAPI two-way), security (edition boundary, no secrets, content-free logs), end_to_end (manifest), e2e (Playwright, with a host page that applies the site's sandbox) |
docs/ | Website integration, API, lab-host deployment, appliance pointer, runbook, threat model, user guide, bundle, generated criteria catalog, ADRs |
infrastructure/ | Dockerfile (two stages, hash-pinned, uid 10001, HEALTHCHECK), |
Releases and artifacts
A v* tag builds the image, proves the edition boundary inside it, scans it (Trivy, HIGH/CRITICAL, fixed only), pushes
docker.io/hybridcloudworks/img-ca-lab-addon:v<version> with provenance and SBOM, attests it, and prints the
digest in the run summary. The website pins that digest in its lab-host group_vars; the digest is the only coupling.
The push is skipped unless the owner has enabled the Docker OIDC connection (docs/deployment/lab-host.md); v0.1.0 and
the release candidate v0.1.1-rc.1 were pushed that way. What each version contains is in CHANGELOG.md.
Release 0.1.1 is the first image that states its licence (org.opencontainers.image.licenses=MIT). It was published on
2026-10-27 by the tag v0.1.1: digest sha256:95082857e3b866743ffa5c827c7b897d085e945d80aa4b710f58926b03170456,
release, checks in VALIDATION.md.
What the export cannot show
Spend and forecasts; budgets and cost alerts (not in the resources table); role assignments and Entra posture
(authorizationresources); diagnostic settings; policy compliance; subscription-level Defender plans; network flow and
private DNS resolution. Each maps to a criterion that answers unknown with that reason, and to the "Unknown by design"
panel in the pane and report.md.
Contributing, security, license
CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md ·
MIT (LICENSE, NOTICE). Coding-agent guidance: AGENTS.md, CLAUDE.md.
