stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

Browse Source
This commit is contained in:
master
2026-01-19 09:02:59 +02:00
parent 8c4bf54aed
commit 17419ba7c4
809 changed files with 170738 additions and 12244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/technical/adr/0044-binary-delta-signatures.md
View File

@@ -54,18 +54,21 @@ Vulnerability scanners today rely on version string comparison to determine if a
### Disassembly Engine Selection
**Chosen: Plugin-based architecture with Iced (primary) + B2R2 (fallback)**
**Chosen: Plugin-based architecture with Iced (primary for disassembly) + B2R2 (primary for IR lifting)**
| Engine | Strengths | Weaknesses |
|--------|-----------|------------|
| **Iced** | Fastest x86/x86-64, MIT license, pure C# | x86 only |
| **B2R2** | Multi-arch (ARM, MIPS, RISC-V), IR lifting, MIT license | F# (requires wrapper) |
| Engine | Strengths | Weaknesses | Use Case |
|--------|-----------|------------|----------|
| **Iced** | Fastest x86/x86-64, MIT license, pure C# | x86 only | Fast disassembly for delta-sig normalization |
| **B2R2** | Multi-arch (ARM, MIPS, RISC-V), IR lifting, MIT license | F# (requires wrapper) | Semantic IR analysis, multi-arch |
**Rationale:**
- Iced for performance-critical x86/x86-64 path (90%+ of scanned binaries)
- B2R2 for ARM64, MIPS, RISC-V when needed
- Iced for performance-critical x86/x86-64 delta-sig path (90%+ of scanned binaries)
- B2R2 for ARM64, MIPS, RISC-V when needed for delta-sigs
- **B2R2 as primary backend for semantic IR lifting** (see `SPRINT_20260118_027_BinaryIndex_b2r2_full_integration.md`)
- Plugin architecture allows adding engines without core changes
**Update (2026-01-19):** B2R2 is now the primary backend for semantic IR lifting via `B2R2LowUirLiftingService`. This enables high-fidelity semantic analysis across x86, ARM64, MIPS, RISC-V, PowerPC, and SPARC architectures. See `docs/modules/binary-index/semantic-diffing.md` for details.
### Normalization Strategy
To compare binaries compiled by different toolchains/versions, we normalize:

237
docs/technical/architecture/runtime-agents-architecture.md
View File

@@ -714,9 +714,246 @@ This document describes the runtime observation layer in StellaOps, including eB
---
## Tetragon Integration
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TETRAGON eBPF INTEGRATION │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tetragon provides kernel-level security observability via eBPF TracingPolicies. │
│ StellaOps integrates Tetragon as a complementary runtime observation source. │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ ARCHITECTURE │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Tetragon Daemon (DaemonSet) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ kprobe │ │ tracepoint │ │ uprobe │ │ │ │
│ │ │ │ (syscalls) │ │ (scheduler) │ │ (userspace) │ │ │ │
│ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └─────────────────┼─────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────▼─────────┐ │ │ │
│ │ │ │ TracingPolicy │ │ │ │
│ │ │ │ CRD Enforcement │ │ │ │
│ │ │ └─────────┬─────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────▼─────────┐ │ │ │
│ │ │ │ Export API │ │ │ │
│ │ │ │ (gRPC/HTTP) │ │ │ │
│ │ │ └─────────┬─────────┘ │ │ │
│ │ │ │ │ │ │
│ │ └────────────────────────────┼────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────▼─────────┐ │ │
│ │ │ StellaOps Agent │ │ │
│ │ │ (Tetragon) │ │ │
│ │ └─────────┬─────────┘ │ │
│ │ │ │ │
│ │ ┌────────────────────────────┼───────────────────────────────────────┐ │ │
│ │ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌───────▼───────┐ ┌─────────────┐ │ │ │
│ │ │ │ Privacy │ │ Event │ │ Frame │ │ │ │
│ │ │ │ Filter │──│ Adapter │──│ Canonicalizer │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ └─────────────┘ └───────────────┘ └──────┬──────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌───────────────────────────────────────────┼────────────────┐ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ ┌─────────────────┐ ┌───────────────▼────────────┐ │ │ │ │
│ │ │ │ │ Hot Symbol │ │ Witness │ │ │ │ │
│ │ │ │ │ Bridge │ │ Bridge │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ └────────┬────────┘ └──────────────┬─────────────┘ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ └───────────┼─────────────────────────────┼──────────────────┘ │ │ │
│ │ │ │ │ │ │ │
│ │ └───────────────┼─────────────────────────────┼─────────────────────┘ │ │
│ │ │ │ │ │
│ │ ┌─────────▼─────────┐ ┌─────────────▼───────────┐ │ │
│ │ │ signals.hot_symbols│ │ RuntimeWitnessGenerator │ │ │
│ │ │ (PostgreSQL) │ │ (Signing Pipeline) │ │ │
│ │ └────────────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ TRACINGPOLICY CONFIGURATION │ │
│ │ │ │
│ │ The StellaOps TracingPolicy captures: │ │
│ │ │ │
│ │ • Process execution (execve) with full arguments │ │
│ │ • Network connections (connect, socket) │ │
│ │ • File operations (open, read, write) │ │
│ │ • Kernel and user-space stack traces │ │
│ │ │ │
│ │ Namespace selectors: stella-ops-*, application namespaces │ │
│ │ Pod selectors: Via labels (stellaops.io/observe=true) │ │
│ │ │ │
│ │ Policy file: devops/manifests/tetragon/stella-ops-tracing-policy.yaml │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ COMPONENT RESPONSIBILITIES │ │
│ │ │ │
│ │ TetragonAgentCapability: │ │
│ │ • Connects to Tetragon Export API (gRPC) │ │
│ │ • Implements IAgentCapability interface │ │
│ │ • Supports start/stop collection, status, flush tasks │ │
│ │ • Health checks via Tetragon health endpoint │ │
│ │ │ │
│ │ TetragonEventAdapter: │ │
│ │ • Converts TetragonEvent to RuntimeCallEvent format │ │
│ │ • Maps stack frames to canonical symbols │ │
│ │ • Extracts process/container context │ │
│ │ │ │
│ │ TetragonFrameCanonicalizer: │ │
│ │ • Resolves Build-ID for binaries │ │
│ │ • Demangles C++, Rust, Go symbol names │ │
│ │ • Computes function IDs matching static analysis │ │
│ │ • Format: buildid:function+offset │ │
│ │ │ │
│ │ TetragonHotSymbolBridge: │ │
│ │ • Records observations to hot_symbols index │ │
│ │ • Time-window aggregation (1-minute windows) │ │
│ │ • Confidence scoring (0.20-1.00 range) │ │
│ │ │ │
│ │ TetragonWitnessBridge: │ │
│ │ • Buffers observations by claim_id │ │
│ │ • Emits to RuntimeWitnessGenerator │ │
│ │ • Implements backpressure via SemaphoreSlim │ │
│ │ │ │
│ │ TetragonPrivacyFilter: │ │
│ │ • Argument redaction (passwords, tokens, PII) │ │
│ │ • Symbol-ID-only mode for privacy-sensitive envs │ │
│ │ • Namespace allowlisting │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ TETRAGON vs SIGNALS COMPARISON │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Aspect │ Signals (Native) │ Tetragon Integration │ │ │
│ │ │ ─────────────────┼──────────────────────┼────────────────────────│ │ │
│ │ │ Deployment │ Custom eBPF agent │ Standard Tetragon │ │ │
│ │ │ Configuration │ Code-level │ TracingPolicy CRD │ │ │
│ │ │ Policy management │ Recompile │ K8s-native (kubectl) │ │ │
│ │ │ Stack capture │ Custom unwinding │ Built-in │ │ │
│ │ │ Ecosystem │ StellaOps only │ CNCF, broad adoption │ │ │
│ │ │ Use case │ Deep integration │ Standard compliance │ │ │
│ │ └──────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Recommendation: Use Tetragon for Kubernetes environments with compliance │ │
│ │ requirements. Use native Signals for maximum control and non-K8s estates. │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ PERFORMANCE TARGETS │ │
│ │ │ │
│ │ Target KPIs for Tetragon integration: │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Metric │ Target │ Measurement │ │ │
│ │ │ ─────────────────────────┼──────────────────┼──────────────────────│ │ │
│ │ │ CPU overhead │ <5% │ Per monitored pod │ │ │
│ │ │ Memory overhead (agent) │ <100MB │ Agent container │ │ │
│ │ │ Capture latency (P95) │ <100ms │ Event to hot_symbols │ │ │
│ │ │ Throughput │ >10,000 events/s │ Per agent instance │ │ │
│ │ │ Privacy filter overhead │ <10% │ Compared to baseline │ │ │
│ │ │ Frame canonicalization │ <10ms per frame │ With symbol resolve │ │ │
│ │ │ Function ID computation │ <0.1ms per call │ Hash + format │ │ │
│ │ │ Demangling throughput │ >100,000 sym/s │ Mixed C++/Rust/Go │ │ │
│ │ └──────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Benchmarks: src/RuntimeInstrumentation/StellaOps.RuntimeInstrumentation. │ │
│ │ Tetragon.Tests/Benchmarks/TetragonPerformanceBenchmarks.cs │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
---
## Tetragon Deployment Guide
### Prerequisites
1. **Kubernetes cluster** with Linux nodes (kernel 5.8+)
2. **Tetragon installed** via Helm or operator
3. **StellaOps control plane** deployed
### Installation Steps
```bash
# 1. Install Tetragon (if not already installed)
helm repo add cilium https://helm.cilium.io
helm install tetragon cilium/tetragon -n kube-system
# 2. Apply StellaOps TracingPolicy
kubectl apply -f devops/manifests/tetragon/stella-ops-tracing-policy.yaml
# 3. Deploy StellaOps Tetragon Agent
kubectl apply -f devops/manifests/tetragon/stella-ops-tetragon-agent-daemonset.yaml
# 4. Verify deployment
kubectl get pods -n stella-ops -l app=stella-ops-tetragon-agent
kubectl logs -n stella-ops -l app=stella-ops-tetragon-agent --tail=50
```
### Configuration
The Tetragon agent is configured via ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: stella-ops-tetragon-config
namespace: stella-ops
data:
config.yaml: |
tetragon:
address: "tetragon.kube-system.svc:54321"
connectionTimeout: 30s
hotSymbols:
aggregationWindowSeconds: 60
minConfidenceThreshold: 0.2
flushIntervalSeconds: 30
privacy:
redactArguments: true
useDefaultRedactionPatterns: true
symbolIdOnlyMode: false
allowedNamespaces:
- stella-ops-workloads
- default
```
### Monitoring
The agent exposes Prometheus metrics at `:8080/metrics`:
- `tetragon_events_total` - Total events received
- `tetragon_events_filtered` - Events dropped by privacy filter
- `tetragon_hotsymbols_flushed` - Hot symbols written to DB
- `tetragon_witness_generated` - Runtime witnesses generated
- `tetragon_latency_seconds` - Event processing latency histogram
---
## Related Documentation
- [Policy Engine Data Pipeline](policy-engine-data-pipeline.md) - How runtime feeds policy
- [Reachability Drift Alert Flow](../../flows/19-reachability-drift-alert-flow.md) - Runtime-triggered alerts
- [Signals Module Architecture](../../modules/signals/architecture.md) - Signals module dossier
- [Zastava Architecture](../../modules/zastava/architecture.md) - Container observer dossier
- [Tetragon Integration Sprint](../../implplan/SPRINT_20260118_019_Infra_tetragon_integration.md) - Implementation details