consolidation of some of the modules, localization fixes, product advisories work, qa work
This commit is contained in:
master
@@ -1,6 +1,6 @@
|
||||
# Developer Tools
|
||||
|
||||
> Collection of CLI utilities for fixture management, policy validation, smoke testing, and workflow generation.
|
||||
> Collection of CLI utilities, benchmarks, SDK generators, and dev portal for fixture management, policy validation, smoke testing, workflow generation, and developer experience.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -9,6 +9,7 @@ Developer Tools is a collection of standalone CLI utilities used by Stella Ops d
|
||||
## Quick Links
|
||||
|
||||
- [Architecture](./architecture.md)
|
||||
- [Supply-Chain Hardening Suite](./supply-chain-hardening-suite.md)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -27,6 +28,12 @@ Developer Tools is a collection of standalone CLI utilities used by Stella Ops d
|
||||
- LanguageAnalyzerSmoke: language detection tests
|
||||
- RustFsMigrator: filesystem migration for RustFS (S3-compatible) storage
|
||||
- WorkflowGenerator: CI workflow generation with F# DSL
|
||||
- Supply-chain hardening suite: deterministic mutation/negative-path security gates under `tests/supply-chain/`
|
||||
- StellaOps.Bench: performance benchmarks for LinkNotMerge, VEX, Notify, Policy, and Scanner subsystems (absorbed from `src/Bench/`)
|
||||
- StellaOps.Verifier: standalone offline evidence bundle verifier for air-gapped environments (absorbed from `src/Verifier/`)
|
||||
- StellaOps.Sdk.Generator: multi-language SDK code generation from OpenAPI spec (absorbed from `src/Sdk/`)
|
||||
- StellaOps.Sdk.Release: SDK release automation (absorbed from `src/Sdk/`)
|
||||
- StellaOps.DevPortal.Site: Astro-based interactive developer portal with API docs and Try-It console (absorbed from `src/DevPortal/`)
|
||||
|
||||
## Dependencies
|
||||
|
||||
@@ -34,8 +41,14 @@ Developer Tools is a collection of standalone CLI utilities used by Stella Ops d
|
||||
|
||||
- Policy Engine libraries - policy DSL parsing and schema definitions
|
||||
- Scanner libraries - language analyzer and SBOM processing
|
||||
- Notify libraries - notification model definitions (Bench.Notify)
|
||||
- TestKit - shared test infrastructure for benchmark test projects
|
||||
- System.CommandLine - CLI parsing for Verifier
|
||||
- Astro/Starlight (Node.js) - DevPortal static site framework
|
||||
|
||||
### Downstream
|
||||
|
||||
- CI pipelines - consume generated workflow definitions
|
||||
- Test suites - consume golden fixtures and SBOM/advisory pairs
|
||||
- SDK consumers - consume generated Go/Java/Python/TypeScript clients
|
||||
- Auditors - consume Verifier output in air-gapped verification workflows
|
||||
|
||||
@@ -26,6 +26,28 @@ src/Tools/
|
||||
Program.cs
|
||||
WorkflowGenerator/ # CI workflow generation (F# DSL)
|
||||
Program.fs
|
||||
StellaOps.Bench/ # Performance benchmarks (absorbed from src/Bench/)
|
||||
LinkNotMerge/ # Link-not-merge linkset benchmarks
|
||||
LinkNotMerge.Vex/ # VEX-enriched linkset benchmarks
|
||||
Notify/ # Notification pipeline benchmarks
|
||||
PolicyEngine/ # Policy engine evaluation benchmarks
|
||||
Scanner.Analyzers/ # Language analyzer benchmarks
|
||||
Determinism/ # Determinism fixture inputs/configs
|
||||
Graph/ # Graph benchmark scenarios and results
|
||||
StellaOps.Verifier/ # Standalone offline bundle verifier (absorbed from src/Verifier/)
|
||||
__Tests/
|
||||
StellaOps.Sdk.Generator/ # Multi-language SDK code generation (absorbed from src/Sdk/)
|
||||
go/ java/ python/ ts/
|
||||
postprocess/
|
||||
StellaOps.Sdk.Release/ # SDK release automation (absorbed from src/Sdk/)
|
||||
StellaOps.DevPortal.Site/ # Developer portal static site (absorbed from src/DevPortal/)
|
||||
src/ public/ scripts/
|
||||
tests/supply-chain/ # Deterministic supply-chain hardening lanes
|
||||
01-jcs-property/
|
||||
02-schema-fuzz/
|
||||
03-rekor-neg/
|
||||
04-big-dsse-referrers/
|
||||
05-corpus/
|
||||
```
|
||||
|
||||
## Tool Descriptions
|
||||
@@ -62,6 +84,39 @@ Migrates data stored in RustFS (S3-compatible object storage) between schema ver
|
||||
|
||||
Generates GitHub Actions and .NET test workflow definitions from an F# DSL. Ensures CI workflow files are consistent, auditable, and derived from a single source of truth rather than hand-edited YAML.
|
||||
|
||||
### StellaOps.Bench (Performance Benchmarks)
|
||||
|
||||
Collected from the former `src/Bench/` directory. Contains performance benchmarks for multiple subsystems:
|
||||
|
||||
- **LinkNotMerge** -- Benchmarks for linkset aggregation and link-not-merge scenario execution, with baseline tracking and Prometheus-compatible metrics export.
|
||||
- **LinkNotMerge.Vex** -- VEX-enriched variant of link-not-merge benchmarks.
|
||||
- **Notify** -- Benchmarks for the notification pipeline against `StellaOps.Notify.Models`.
|
||||
- **PolicyEngine** -- Benchmarks for policy engine evaluation against `StellaOps.Policy`.
|
||||
- **Scanner.Analyzers** -- Benchmarks for language analyzers (Node, Go, Java, Python, .NET, Bun) against `StellaOps.Scanner.Analyzers.Lang.*`.
|
||||
- **Determinism** -- Frozen fixture inputs and configurations for deterministic benchmark reproducibility.
|
||||
|
||||
Each benchmark subproject can be published as an independent `dotnet tool`.
|
||||
|
||||
### StellaOps.Verifier (Standalone Bundle Verifier)
|
||||
|
||||
Absorbed from the former `src/Verifier/` directory. A standalone CLI tool for offline verification of Stella Ops evidence bundles in air-gapped environments. Publishes as a single-file, self-contained executable (`stella-verifier`) targeting multiple RIDs: `win-x64`, `linux-x64`, `linux-musl-x64`, `osx-x64`, `osx-arm64`. Has no framework dependencies -- designed for minimal footprint in restricted environments.
|
||||
|
||||
### StellaOps.Sdk.Generator (SDK Code Generation)
|
||||
|
||||
Absorbed from the former `src/Sdk/StellaOps.Sdk.Generator/` directory. Generates typed SDK clients for Go, Java, Python, and TypeScript from the Stella Ops OpenAPI specification. Includes per-language `config.yaml`, generation scripts, postprocessing templates, and deterministic toolchain lockfile (`toolchain.lock.yaml`).
|
||||
|
||||
### StellaOps.Sdk.Release (SDK Release Automation)
|
||||
|
||||
Absorbed from the former `src/Sdk/StellaOps.Sdk.Release/` directory. Automates the release pipeline for generated SDK packages.
|
||||
|
||||
### StellaOps.DevPortal.Site (Developer Portal)
|
||||
|
||||
Absorbed from the former `src/DevPortal/` directory. An Astro-based static site providing interactive API documentation, SDK quickstarts, code examples, and a "Try It" console backed by RapiDoc. Includes offline build support (`build-offline.mjs`), link checking, accessibility audits, and performance checks. Not a .NET project -- uses Node.js/npm.
|
||||
|
||||
### Supply-Chain Hardening Suite
|
||||
|
||||
Deterministic multi-lane harness validating canonicalization invariants, mutation-fuzz crash resistance, Rekor negative-path diagnostics, and oversized DSSE/referrer reject behavior.
|
||||
|
||||
## Data Flow
|
||||
|
||||
Tools are consumers and producers of artifacts:
|
||||
@@ -71,6 +126,11 @@ Tools are consumers and producers of artifacts:
|
||||
3. **PolicySimulationSmoke** and **LanguageAnalyzerSmoke** execute tests against upstream services/libraries and produce pass/fail reports.
|
||||
4. **RustFsMigrator** reads from and writes to S3-compatible storage.
|
||||
5. **WorkflowGenerator** reads F# DSL definitions and writes CI workflow YAML files.
|
||||
6. **Supply-chain hardening suite** reads frozen corpus fixtures, executes deterministic lanes, and emits replay-ready artifacts for CI and local triage.
|
||||
7. **StellaOps.Bench** reads frozen inputs (SBOMs, VEX, graphs) and produces benchmark reports with latency/throughput metrics.
|
||||
8. **StellaOps.Verifier** reads evidence bundles from disk and produces pass/fail verification results for offline audit.
|
||||
9. **StellaOps.Sdk.Generator** reads the OpenAPI spec and produces typed SDK source code for Go, Java, Python, and TypeScript.
|
||||
10. **StellaOps.DevPortal.Site** reads the OpenAPI spec and SDK documentation, producing a static developer portal site.
|
||||
|
||||
## Database Schema
|
||||
|
||||
@@ -82,13 +142,20 @@ Not applicable. Tools are client-side CLI applications with no HTTP endpoints.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Library/Tool | Purpose |
|
||||
|---------------------|------------------------------------------------|
|
||||
| Policy Engine libs | Policy DSL parsing, schema definitions |
|
||||
| Scanner libs | Language analyzer, SBOM processing |
|
||||
| F# compiler | WorkflowGenerator DSL compilation |
|
||||
| DotNet.Glob | File pattern matching in fixture tools |
|
||||
| AWS SDK (S3) | RustFsMigrator object storage access |
|
||||
| Library/Tool | Purpose |
|
||||
|--------------------------|------------------------------------------------------|
|
||||
| Policy Engine libs | Policy DSL parsing, schema definitions |
|
||||
| Scanner libs | Language analyzer, SBOM processing |
|
||||
| F# compiler | WorkflowGenerator DSL compilation |
|
||||
| DotNet.Glob | File pattern matching in fixture tools |
|
||||
| AWS SDK (S3) | RustFsMigrator object storage access |
|
||||
| StellaOps.Policy | Bench.PolicyEngine benchmark target |
|
||||
| StellaOps.Scanner.Analyzers.Lang.* | Bench.ScannerAnalyzers benchmark targets |
|
||||
| StellaOps.Notify.Models | Bench.Notify benchmark target |
|
||||
| StellaOps.TestKit | Shared test infrastructure for benchmark tests |
|
||||
| System.CommandLine | Verifier CLI argument parsing |
|
||||
| Astro + Starlight | DevPortal static site generation |
|
||||
| openapi-generator-cli | Sdk.Generator multi-language code generation |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user