Add ASM OpenAPI 3.1 spec and CI linting workflow

[dmchaledev]

Problem

The README's Contents table advertises asm/openapi.yaml, sat/openapi.yaml, MCP definitions, guides, and SDK examples — but none of those files exist. Any developer or API consumer who visits this repo expecting a spec gets nothing. This is the highest-leverage gap to close first.

What this PR adds

asm/openapi.yaml — OpenAPI 3.1 scaffold for HailBytes ASM

A complete, valid OpenAPI 3.1 specification covering four resource groups:

Tag	Endpoints
Assets	GET /assets, GET /assets/{id}, PATCH /assets/{id}, DELETE /assets/{id}
Scans	GET /scans, POST /scans, GET /scans/{id}
Vulnerabilities	GET /vulnerabilities, GET /vulnerabilities/{id}, PATCH /vulnerabilities/{id}
Tags	GET /tags, POST /tags

Includes:

• Full request/response schemas with examples
• Pagination envelope (meta.total, meta.page, meta.per_page)
• Bearer auth security scheme
• Shared error shape and reusable $ref components
• Severity, status, and asset-type enums
• Detailed AssetDetail (open ports, certificates), ScanDetail (summary stats), VulnerabilityDetail (remediation, CVEs, audit history)

.github/workflows/validate-openapi.yml — Spectral CI linting

Runs @stoplight/spectral-cli against any */openapi.yaml file on every push/PR that touches a spec. Catches broken $refs, missing required fields, and OAS rule violations before they reach main. Conditionally skips specs that don't exist yet (so the sat/openapi.yaml step won't fail until that file is added).

Next steps

• Review and adjust endpoint shapes to match the real API
• Add sat/openapi.yaml for the SAT product
• Add mcp/README.md with MCP tool definitions
• Add Postman collection generated from this spec

https://claude.ai/code/session_01EAxtNqFuP97kjcQ9W88thh

---

Generated by Claude Code