Files

master c2c6b58b41 feat: Add Promotion-Time Attestations for Stella Ops

- Introduced a new document for promotion-time attestations, detailing the purpose, predicate schema, producer workflow, verification flow, APIs, and security considerations.
- Implemented the `stella.ops/promotion@v1` predicate schema to capture promotion evidence including image digest, SBOM/VEX artifacts, and Rekor proof.
- Defined producer responsibilities and workflows for CLI orchestration, signer responsibilities, and Export Center integration.
- Added verification steps for auditors to validate promotion attestations offline.

feat: Create Symbol Manifest v1 Specification

- Developed a specification for Symbol Manifest v1 to provide a deterministic format for publishing debug symbols and source maps.
- Defined the manifest structure, including schema, entries, source maps, toolchain, and provenance.
- Outlined upload and verification processes, resolve APIs, runtime proxy, caching, and offline bundle generation.
- Included security considerations and related tasks for implementation.

chore: Add Ruby Analyzer with Git Sources

- Created a Gemfile and Gemfile.lock for Ruby analyzer with dependencies on git-gem, httparty, and path-gem.
- Implemented main application logic to utilize the defined gems and output their versions.
- Added expected JSON output for the Ruby analyzer to validate the integration of the new gems and their functionalities.
- Developed internal observation classes for Ruby packages, runtime edges, and capabilities, including serialization logic for observations.

test: Add tests for Ruby Analyzer

- Created test fixtures for Ruby analyzer, including Gemfile, Gemfile.lock, main application, and expected JSON output.
- Ensured that the tests validate the correct integration and functionality of the Ruby analyzer with the specified gems.

2025-11-11 15:30:22 +02:00

4.5 KiB

Raw Blame History

Ruby Capability & Source Predicates (SCANNER-POLICY-0001)

Status: Implemented · Owner: Policy Guild · Updated: 2025-11-10
Scope: Extend Policy Engine DSL to consume Ruby analyzer metadata (groups, declaredOnly, capabilities, git/path provenance) emitted in Sprint 138.

1. Goals

Allow policies to express intent around Bundler groups (e.g., blocking development gems in production promotes).
Expose Ruby capability evidence (exec/net/serialization/job schedulers) as first-class predicates.
Differentiate package provenance: registry, git, path/vendor cache.
Ensure new predicates work in offline/air-gapped evaluation and export deterministically.

Non-goals: UI wiring (handled by Policy Studio team), policy templates rollout (tracked separately in DOCS-POLICY backlog).

2. Source Metadata

Scanner now emits the following fields per Ruby component:

Field	Type	Example	Notes
`groups`	`string` (semi-colon list)	`development;test`	Aggregated from manifest + lockfile.
`declaredOnly`	`bool` (string `"true"/"false"`)	`"false"`	False indicates vendor cache evidence present.
`source`	`string`	`git:https://github.com/example/git-gem.git@<rev>`	Registry (`https://`), `git:`, `path:`, `vendor-cache`.
`artifact`	`string?`	`vendor/cache/path-gem-2.1.3.gem`	Only when cached artefact observed.
Capability flags	`string -> bool`	`capability.exec = "true"` etc.	Includes scheduler sub-keys.

3. Proposed Predicates

Predicate	Signature	Description
`ruby.group(name: string)`	`bool`	True if component belongs to Bundler group `name`.
`ruby.groups()`	`set<string>`	Returns all groups for aggregations.
`ruby.declared_only()`	`bool`	True when component has no vendor/installed evidence.
`ruby.source(kind?: string)`	`bool`	Kind matches prefix (`registry`, `git`, `path`, `vendor-cache`).
`ruby.capability(name: string)`	`bool`	Supported names: `exec`, `net`, `serialization`, `scheduler`, scheduler subtypes (`scheduler.activejob`, etc.).
`ruby.capability_any(names: set<string>)`	`bool`	Utility predicate to check multiple capabilities.

Implementation detail: compile-time validation ensures predicate usage only within Ruby component scope (similar to node.group pattern).

4. DSL & Engine Changes

Schema mapping: Update ComponentFacts model to surface new Ruby metadata in evaluation context.
Predicate registry: Add Ruby-specific predicate handlers to PolicyPredicateRegistry with deterministic ordering.
Explain traces: Include matched predicates + metadata in explain output.
Exports: Ensure Offline Kit bundles include updated predicate metadata (no runtime fetch).

5. Policy Templates (follow-up)

Create sample rules under policy/templates/ruby:

Block ruby.group("development") when promotion.target == "prod".
Flag ruby.capability("exec") components unless allowlisted.
Require ruby.source("git") packages to provide pinned hash allowlists.

Tracking: DOCS-POLICY follow-up (not part of SCANNER-POLICY-0001 initial kick-off).

6. Testing Strategy

Unit tests for each predicate (true/false cases, unsupported values).
Integration test tying sample Scanner payload to simulated policy evaluation.
Determinism run: repeated evaluation with same snapshot must yield identical explain trace hash.
Offline regression: ensure seed-data/analyzers/ruby/git-sources fixture flows through offline-kit policy evaluation script.

7. Timeline & Dependencies

Step	Owner	Target
Predicate implementation + tests	Policy Engine Guild	Sprint 138 (in progress)
Offline kit regression update	Policy + Ops	Sprint 138
Policy templates & docs	Docs Guild	Sprint 139

Dependencies: Scanner metadata in place (SCANNER-ENG-0016 DONE); no additional service contracts required.

8. Open Questions

Should declaredOnly interact with existing waiver semantics (e.g., treat as lower severity)? → Needs risk review.
Do we expose scheduler sub-types individually or aggregate under ruby.capability("scheduler") only? → Proposed to expose both for flexibility.
Is git URL normalization required (strip credentials, hash fragments)? → Ensure sanitization before evaluation.

Please comment in docs/modules/policy/design/ruby-capability-predicates.md or via SCANNER-POLICY-0001 sprint entry.

4.5 KiB Raw Blame History