Add self-service security analysis state for generated TraderX runtimes

[DovOps]

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:

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:

• Harden C3 readiness and smoke-test guidance for generated runtime scans #418 captured readiness and smoke-test hardening discovered during the C3 Vigolium experiment.
• The active Harden public Grafana access and deterministic log collection for generated observability states #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:

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?