Add self-service security analysis state for generated TraderX runtimes

## Summary

Create a new SpecKit state that teaches and automates self-service security analysis for generated TraderX runtimes. The state should show how a team can take a generated TraderX environment, wait for it to become truly ready, and run practical security-hardening analysis across both runtime behavior and supply chain inputs.

This should not be locked to one scanner. Vigolium is a useful concrete example from the C3 experiment, but the state should be designed as a repeatable security analysis workbench where tools can evolve.

Candidate state name, without assigning a state number yet:

```text
self-service-security-analysis
```

Note: this proposal intentionally does not reserve a numeric state ID. State numbering should be assigned later based on the active roadmap, because another proposal already targets state 015.

## Motivation

TraderX now has generated states that span local runtime, Compose, Kubernetes, observability, and C3 convergence. That makes it a good learning substrate for showing how teams can add security analysis to modern application/platform workflows.

A self-service security-analysis state would help users answer:

- Is the generated runtime actually ready before active scanners run?
- What URLs, API routes, and request shapes should be scanned?
- Which runtime findings are real hardening gaps vs expected learning-environment exposure?
- Which libraries, container base images, and package versions are in use?
- Which dependencies or images have known vulnerabilities?
- What should be patched first?
- How can an internal team reproduce and triage these checks without relying on a centralized security team?

## Relationship to existing work

Related issues/workstreams:

- #418 captured readiness and smoke-test hardening discovered during the C3 Vigolium experiment.
- The active #389 workstream is expected to handle smoke-test readiness, Apple Silicon guidance, and related runtime hardening details.

This proposal should not own those general runtime fixes. It should consume the resulting readiness guidance as a precondition for repeatable security analysis. The focus here is the security workbench: target inventory, runtime/request scanning, supply chain analysis, report generation, and triage guidance.

## Scope

The new state should demonstrate self-service security analysis over a selected generated TraderX state, with C3 (`012-platform-convergence-c3`) as the likely canonical example.

It should cover two major analysis tracks.

### 1. Runtime and request-surface analysis

The state should demonstrate tools and workflows for scanning a live generated runtime:

- URL/request-based scans
- ingress route scans
- API route scans from generated OpenAPI contracts or derived URL target lists
- browser/spider scans against the UI where useful
- bounded dynamic application security testing profiles
- scanner-safe readiness preflight before active scans
- output normalization into human-readable reports

Candidate tools/workflows:

- Vigolium native scans as one worked example
- generated URL target lists from known ingress/API routes
- curl/HAR/request-file based workflows
- optional agentic security-review workflows where locally available
- optional future integrations with Anthropic/Codex-style security analysis skills or other agentic scanners

The state should explicitly say that Vigolium is a candidate scanner, not the only blessed implementation.

## Candidate tool categories

The state should remain tool-neutral, but it should include a curated set of practical tools that teams might evaluate or swap in. The first implementation should pick a small reference path, while the docs explain alternatives.

### Runtime, URL, and request-surface scanning

Potential tools/workflows:

- Vigolium for native dynamic scans, browser/spider scans, URL-list scans, and optional agentic modes.
- OWASP ZAP baseline/API scans for a widely known open-source DAST path.
- Nuclei for template-based checks against exposed services, dashboards, known CVEs, and misconfigurations.
- Custom curl/HAR/raw-request target packs generated from SpecKit/OpenAPI route metadata.
- Playwright-assisted authenticated or UI-driven traffic capture, if later states need richer session flows.

### Supply chain, SBOM, and image analysis

Potential tools/workflows:

- Syft for SBOM generation from source trees, package manifests, and container images.
- Grype for vulnerability analysis from Syft SBOMs or images.
- Trivy for container image, filesystem, dependency, IaC, and secret scans.
- OSV Scanner for ecosystem vulnerability checks across package manifests and lockfiles.
- npm audit for Node/Nest/Angular packages where useful.
- Gradle dependency reports and/or OWASP Dependency-Check for Java/Spring services.
- `dotnet list package --vulnerable` for .NET services where present.
- Docker Scout or equivalent image analysis where available in local environments.

### Source and configuration review

Potential tools/workflows:

- Semgrep for deterministic source/config rules across Java, TypeScript, C#, YAML, and Dockerfiles.
- Gitleaks or TruffleHog for secret scanning.
- Checkov or Terrascan if future states introduce richer IaC/Kubernetes policy checks.
- Optional agentic security review using Codex/Anthropic-style workflows once deterministic scans and target inventories are stable.

### Report and policy normalization

Potential tools/workflows:

- SARIF output where supported, so reports can be consumed by GitHub code scanning or similar systems.
- CycloneDX and SPDX SBOM formats, ideally with one primary format and optional conversion.
- A small TraderX-specific normalization layer that groups findings by state, component, route/image/package, severity, and security posture profile.

The proposal should not require all of these tools in v1. A good first version would prove one runtime scan path, one SBOM path, one vulnerability-analysis path, and one consolidated human-readable report.

### 2. Supply chain and dependency analysis

The state should also demonstrate dependency, SBOM, and image analysis for generated TraderX states:

- Java/Gradle dependencies
- Node/Nest/Angular dependencies
- .NET dependencies where applicable
- container base images and runtime layers
- generated image tags and published GHCR images
- CVE triage by source: app dependency, transitive dependency, base image, runtime/tooling image
- upgrade/patch recommendation summaries

Candidate tools/workflows:

- Syft for SBOM generation
- Grype or Trivy for vulnerability analysis from SBOMs/images
- OSV Scanner for ecosystem vulnerabilities
- npm audit where appropriate
- Gradle dependency reports and/or OWASP Dependency-Check for Java services
- `dotnet list package --vulnerable` where .NET services are present

## Proposed artifacts

The state should produce a predictable report tree, for example:

```text
generated/security/state-012/
preflight/
readiness.md
target-inventory.json
runtime-scans/
vigolium/
ingress-balanced.jsonl
ingress-balanced.html
target-list.jsonl
target-list.html
summary.md
supply-chain/
sbom/
state-012.spdx.json
state-012.cyclonedx.json
vulnerabilities/
grype.json
trivy.json
osv.json
summary.md
triage/
findings-summary.md
patch-recommendations.md
```

Exact formats can evolve, but the state should separate generated reports from canonical app/runtime source artifacts.

## Readiness dependency

Security scans should run only after the selected generated runtime is warm and application-level readiness is confirmed. This proposal should reuse the readiness/smoke-test hardening from #389/#418 rather than redefining it.

The security-analysis state should provide a scanner preflight that calls or documents the canonical readiness gate, then records readiness evidence in the generated report bundle.

## Initial findings from C3 Vigolium experiment

The C3 experiment showed that Vigolium can scan the live ingress and produce useful signals, but also surfaced integration issues.

Working path:

- Start C3 with published images.
- Wait for application-level readiness.
- Run a bounded balanced ingress scan.
- Use generated URL target lists as a workaround for direct OpenAPI ingestion.

Observed Vigolium scan result from bounded ingress scan:

- 26 HTTP records
- 17 findings after grouping
- themes included exposed actuator/docs/metrics endpoints, missing policy/security headers, nginx path behavior, and ID-like parameters

Integration caveats:

- Vigolium OpenAPI ingestion did not work cleanly with generated specs in `0.1.37-beta`; direct `-T spec.yaml -I openapi -t ...` still reported a base URL parsing error.
- URL-list based scans worked reliably.
- Full dynamic scans need bounded profiles and conservative concurrency for local generated environments.
- Agentic modes require additional local setup and should be optional.

## Proposed implementation plan

1. Add a feature pack for a `self-service-security-analysis` state once the roadmap assigns an appropriate numeric state ID.
2. Define the state intent as analysis/report generation over an existing generated runtime, not as a runtime behavior mutation.
3. Add readiness preflight contracts and scripts.
4. Add target inventory generation from generated runtime metadata, OpenAPI specs, or explicit route catalogs.
5. Add a bounded runtime scan workflow with at least one concrete scanner example.
6. Add SBOM/dependency/image analysis workflows.
7. Generate a consolidated security-analysis summary report.
8. Add learning docs that explain how to interpret and triage results.
9. Document Apple Silicon and published-image caveats.
10. Keep tool choices modular so Vigolium or any one scanner can be replaced.

## Acceptance criteria

- A user can run a single command against a generated state and get a security-analysis report bundle.
- The command integrates with the canonical generated-runtime readiness gate before running active runtime scans.
- The state supports C3 as a canonical example target.
- Runtime scans include URL/request/ingress coverage, not just static source review.
- Supply chain scans include SBOM generation and vulnerability analysis for dependencies and/or images.
- Results are written to a generated reports area and do not mutate canonical generated app code as the primary output.
- Documentation explains how to triage findings and distinguish learning-environment exposure from actionable security hardening work.
- Tooling is modular: Vigolium may be included as an example, but the state is not architecturally dependent on Vigolium.

## Open questions

- What numeric state ID should be assigned, if any, given that state 015 is already proposed elsewhere? Should this instead live as an overlay/tooling state that can target any state ID?
- Should reports live under `generated/security/`, `generated/reports/security/`, or another generated artifact root?
- Which SBOM format should be primary: SPDX, CycloneDX, or both?
- Should the first version scan only local generated artifacts, published GHCR images, or both?
- Should agentic security analysis be included in v1, or documented as an optional extension after deterministic scans are stable?
- Should runtime exposure findings such as actuator/docs/metrics be classified as expected learning-state behavior, hardening recommendations, or state-specific policy decisions?

Start with the readiness and smoke-test guidance in #389 and #418, then use the C3 state (`012-platform-convergence-c3`) as the reference target. Define the preflight, target inventory, runtime scans, SBOM and vulnerability outputs under `generated/security/state-012/`, including `readiness.md` and `target-inventory.json`. Done means one command produces a modular report bundle after the canonical readiness gate and documents triage guidance.

Written by the indexing model from the issue text.