c2c6b58b41
- 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.
83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 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
|
|
|
|
1. Allow policies to express intent around Bundler groups (e.g., blocking `development` gems in production promotes).
|
|
2. Expose Ruby capability evidence (exec/net/serialization/job schedulers) as first-class predicates.
|
|
3. Differentiate package provenance: registry, git, path/vendor cache.
|
|
4. 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
|
|
|
|
1. **Schema mapping:** Update `ComponentFacts` model to surface new Ruby metadata in evaluation context.
|
|
2. **Predicate registry:** Add Ruby-specific predicate handlers to `PolicyPredicateRegistry` with deterministic ordering.
|
|
3. **Explain traces:** Include matched predicates + metadata in explain output.
|
|
4. **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
|
|
|
|
1. Should `declaredOnly` interact with existing waiver semantics (e.g., treat as lower severity)? → Needs risk review.
|
|
2. Do we expose scheduler sub-types individually or aggregate under `ruby.capability("scheduler")` only? → Proposed to expose both for flexibility.
|
|
3. 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.
|