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

test fixes and new product advisories work

Browse Source
This commit is contained in:
master
2026-01-28 02:30:48 +02:00
parent 82caceba56
commit 644887997c
288 changed files with 69101 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
docs/reachability/deployment-guide.md Normal file
View File

@@ -0,0 +1,397 @@
# Deployment Guide
## Prerequisites
### Kernel Requirements
**Minimum:** Linux 4.14 with eBPF support
**Recommended:** Linux 5.8+ with BTF and ring buffer support
#### Verify Kernel Configuration
```bash
# Check eBPF support
zcat /proc/config.gz 2>/dev/null | grep -E "CONFIG_BPF|CONFIG_DEBUG_INFO_BTF" || \
cat /boot/config-$(uname -r) | grep -E "CONFIG_BPF|CONFIG_DEBUG_INFO_BTF"
# Required settings:
# CONFIG_BPF=y
# CONFIG_BPF_SYSCALL=y
# CONFIG_BPF_JIT=y (recommended)
# CONFIG_DEBUG_INFO_BTF=y (for CO-RE)
```
#### Verify BTF Availability
```bash
# Check for BTF in kernel
ls -la /sys/kernel/btf/vmlinux
# If missing, check BTFHub or kernel debug packages
```
### Container Runtime
Supported runtimes:
- containerd 1.4+
- Docker 20.10+
- CRI-O 1.20+
Verify cgroup v2 is available (recommended):
```bash
mount | grep cgroup2
# Expected: cgroup2 on /sys/fs/cgroup type cgroup2
```
### Permissions
The collector requires elevated privileges:
**Option 1: Root**
```bash
sudo stella signals start
```
**Option 2: Capabilities (preferred)**
```bash
# Grant required capabilities
sudo setcap cap_bpf,cap_perfmon,cap_sys_ptrace+ep /usr/bin/stella
# Or run with specific capabilities
sudo capsh --caps="cap_bpf,cap_perfmon,cap_sys_ptrace+eip" -- -c "stella signals start"
```
Required capabilities:
- `CAP_BPF`: Load and manage eBPF programs
- `CAP_PERFMON`: Access performance monitoring (ring buffer)
- `CAP_SYS_PTRACE`: Attach uprobes to processes
## Installation
### Standard Installation
```bash
# Install StellaOps CLI
curl -fsSL https://stella.ops/install.sh | bash
# Verify installation
stella version
stella signals --help
```
### Air-Gap Installation
For disconnected environments, use the offline bundle:
```bash
# Download bundle (on connected machine)
stella bundle create --include-probes ebpf-reachability \
--output stellaops-offline.tar.gz
# Transfer to air-gapped system
scp stellaops-offline.tar.gz airgap-host:
# Install on air-gapped system
tar -xzf stellaops-offline.tar.gz
cd stellaops-offline
./install.sh
```
The bundle includes:
- Pre-compiled eBPF probes for common kernel versions
- BTF files for kernels without built-in BTF
- All runtime dependencies
### Pre-Compiled Probes
If CO-RE probes fail to load, use kernel-specific probes:
```bash
# List available pre-compiled probes
stella signals probes list
# Install probes for specific kernel
stella signals probes install --kernel $(uname -r)
# Verify probe compatibility
stella signals probes verify
```
## Configuration
### Basic Configuration
Create `/etc/stellaops/signals.yaml`:
```yaml
signals:
enabled: true
# Output directory for evidence files
output_directory: /var/lib/stellaops/evidence
# Ring buffer size (default 256KB)
ring_buffer_size: 262144
# Maximum events per second (0 = unlimited)
max_events_per_second: 0
# Rotation settings
rotation:
max_size_mb: 100
max_age_hours: 1
# Signing configuration
signing:
enabled: true
key_id: fulcio # or KMS key ARN
submit_to_rekor: true
```
### Probe Selection
Enable specific probes:
```yaml
signals:
probes:
# Tracepoints
sys_enter_openat: true
sched_process_exec: true
inet_sock_set_state: true
# Uprobes
libc_connect: true
libc_accept: true
openssl_read: false # Disable if not needed
openssl_write: false
```
### Filtering
Configure what to capture:
```yaml
signals:
filters:
# Target specific containers (empty = all)
target_containers: []
# Target specific namespaces
target_namespaces: []
# File path filtering
paths:
allowlist:
- /etc/**
- /var/lib/**
- /home/**
denylist:
- /proc/**
- /sys/**
- /dev/**
# Network filtering
networks:
# Capture connections to these CIDRs
allowlist:
- 10.0.0.0/8
- 172.16.0.0/12
# Exclude these destinations
denylist:
- 127.0.0.0/8
```
### Resource Limits
Prevent runaway resource usage:
```yaml
signals:
resources:
# Maximum memory for caches
max_cache_memory_mb: 256
# Symbol cache entries
symbol_cache_max_entries: 100000
# Container cache TTL
container_cache_ttl_seconds: 300
# Event rate limiting
max_events_per_second: 50000
```
## Starting the Collector
### Systemd Service
```bash
# Enable and start
sudo systemctl enable stellaops-signals
sudo systemctl start stellaops-signals
# Check status
sudo systemctl status stellaops-signals
# View logs
sudo journalctl -u stellaops-signals -f
```
### Manual Start
```bash
# Start with default configuration
stella signals start
# Start with custom config
stella signals start --config /path/to/signals.yaml
# Start with verbose logging
stella signals start --verbose
# Start in foreground (for debugging)
stella signals start --foreground
```
### Docker Deployment
```dockerfile
FROM stellaops/signals-collector:latest
# Mount host systems
VOLUME /sys/kernel/debug
VOLUME /sys/fs/cgroup
VOLUME /proc
# Evidence output
VOLUME /var/lib/stellaops/evidence
# Run with required capabilities
# docker run --privileged or with specific caps
```
```bash
docker run -d \
--name stellaops-signals \
--privileged \
-v /sys/kernel/debug:/sys/kernel/debug:ro \
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
-v /proc:/host/proc:ro \
-v /var/lib/stellaops/evidence:/evidence \
stellaops/signals-collector:latest
```
### Kubernetes DaemonSet
```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: stellaops-signals
namespace: stellaops
spec:
selector:
matchLabels:
app: stellaops-signals
template:
metadata:
labels:
app: stellaops-signals
spec:
hostPID: true
hostNetwork: true
containers:
- name: collector
image: stellaops/signals-collector:latest
securityContext:
privileged: true
volumeMounts:
- name: sys-kernel-debug
mountPath: /sys/kernel/debug
readOnly: true
- name: sys-fs-cgroup
mountPath: /sys/fs/cgroup
readOnly: true
- name: proc
mountPath: /host/proc
readOnly: true
- name: evidence
mountPath: /var/lib/stellaops/evidence
volumes:
- name: sys-kernel-debug
hostPath:
path: /sys/kernel/debug
- name: sys-fs-cgroup
hostPath:
path: /sys/fs/cgroup
- name: proc
hostPath:
path: /proc
- name: evidence
hostPath:
path: /var/lib/stellaops/evidence
type: DirectoryOrCreate
```
## Verification
### Verify Probes Attached
```bash
# List attached probes
stella signals status
# Expected output:
# Probes:
# tracepoint/syscalls/sys_enter_openat: attached
# tracepoint/sched/sched_process_exec: attached
# tracepoint/sock/inet_sock_set_state: attached
# uprobe/libc.so.6:connect: attached
# uprobe/libc.so.6:accept: attached
```
### Verify Events Flowing
```bash
# Watch live events
stella signals watch
# Check event counts
stella signals stats
# Expected output:
# Events collected: 15234
# Events/second: 847
# Ring buffer usage: 12%
```
### Verify Evidence Files
```bash
# List evidence chunks
ls -la /var/lib/stellaops/evidence/
# Verify chain integrity
stella signals verify-chain /var/lib/stellaops/evidence/
```
## Troubleshooting
See [operator-runbook.md](operator-runbook.md) for detailed troubleshooting procedures.
### Quick Checks
```bash
# Check kernel support
stella signals check-kernel
# Verify permissions
stella signals check-permissions
# Test probe loading
stella signals test-probes
# Validate configuration
stella signals validate-config --config /etc/stellaops/signals.yaml
```