Refactor Command Run Attestation with Enhanced Tracing and Multi-Exporter Support

[colek42]

Refactor Command Run Attestation with Enhanced Tracing and Multi-Exporter Support

Overview

This issue tracks the comprehensive refactoring of the command run attestation to improve its architecture, add network tracing capabilities, support cross-platform program hashing, and implement the multi-exporter pattern for better attestation granularity.

Motivation

The current command run attestation has several limitations:

• Tracing is Linux-only with limited syscall coverage (only EXECVE and OPENAT)
• No network activity tracking
• Process trace data is embedded in the main attestation, making it bulky
• No cross-platform support for program hash calculation
• Limited visibility into script execution and interpreter usage

Goals

1. Implement Multi-Exporter Pattern: Separate trace data from the main command attestation into a single trace attestation containing the complete process tree
2. Enhanced Tracing: Add network syscall tracing and file write tracking
3. Cross-Platform Support: Implement program hash calculation for Windows and macOS
4. Improved Schema: Add timing, network operations, and process relationship data
5. Clean Architecture: Create platform-agnostic interfaces with OS-specific implementations
6. Performance Optimization: Make expensive operations like file hashing configurable to balance security and performance

Detailed Requirements

1. Multi-Exporter Implementation

• Make CommandRun implement the MultiExporter interface
• Create new TraceAttestation type for trace-specific data containing the complete process tree
• Export trace data as a single attestation representing the full execution tree from the entry point command
• Ensure exported attestation follows naming convention: command-run/trace

2. Enhanced Linux Tracing

New System Calls to Trace:

• SYS_SOCKET - Socket creation
• SYS_CONNECT - Outbound connections
• SYS_BIND - Port binding
• SYS_LISTEN - Server setup
• SYS_ACCEPT/SYS_ACCEPT4 - Incoming connections
• SYS_SEND/SYS_SENDTO/SYS_SENDMSG - Data transmission
• SYS_RECV/SYS_RECVFROM/SYS_RECVMSG - Data reception
• SYS_WRITE/SYS_WRITEV - File write operations

Additional Process Information:

• Process start/end timestamps
• CPU usage (user/system time)
• Child process relationships (maintaining full process tree structure)
• Signal handling events

Performance Configuration:

• Add option to enable/disable file hashing in tracer (high CPU overhead)
• Make program digest calculation configurable
• Allow selective enablement of expensive operations

3. Cross-Platform Program Hashing

Linux Enhancements:

• Improve current /proc/[pid]/exe approach
• Add script interpreter detection and hashing

Windows Support:

• Implement using GetModuleFileNameEx or QueryFullProcessImageName
• Handle PE executable hashing
• Support PowerShell and batch script detection

macOS Support:

• Implement using proc_pidpath or sysctl with KERN_PROCARGS2
• Handle Mach-O executable hashing
• Support shell and Python script detection

4. Updated Schema

type ProcessInfo struct {
    // Existing fields...
    
    // New fields
    StartTime        time.Time                       `json:"starttime,omitempty"`
    EndTime          time.Time                       `json:"endtime,omitempty"`
    UserTime         time.Duration                   `json:"usertime,omitempty"`
    SystemTime       time.Duration                   `json:"systemtime,omitempty"`
    NetworkActivity  []NetworkOperation              `json:"networkactivity,omitempty"`
    FileWrites       map[string]cryptoutil.DigestSet `json:"filewrites,omitempty"`
    ChildProcesses   []int                           `json:"childprocesses,omitempty"`
    SignalsReceived  []SignalInfo                    `json:"signalsreceived,omitempty"`
}

type NetworkOperation struct {
    Syscall     string    `json:"syscall"`
    Timestamp   time.Time `json:"timestamp"`
    LocalAddr   string    `json:"localaddr,omitempty"`
    RemoteAddr  string    `json:"remoteaddr,omitempty"`
    Protocol    string    `json:"protocol,omitempty"`
    BytesSent   int64     `json:"bytessent,omitempty"`
    BytesRecv   int64     `json:"bytesrecv,omitempty"`
    SocketFD    int       `json:"socketfd,omitempty"`
}

5. Architecture Refactoring

Create clean abstractions:

// tracer.go
type TracerOptions struct {
    EnableHashing      bool  // Enable file/program digest calculation
    EnableNetworkTrace bool  // Enable network syscall tracing
}

type Tracer interface {
    Start(cmd *exec.Cmd) error
    Wait() error
    GetProcessTree() []ProcessInfo  // Returns complete process tree
}

// Platform-specific implementations:
// - tracer_linux.go (ptrace-based)
// - tracer_windows.go (WMI/ETW-based)
// - tracer_darwin.go (dtrace/libproc-based)

Implementation Plan

Phase 1: Multi-Exporter Support

• Implement MultiExporter interface on CommandRun
• Create TraceAttestation type that contains the complete process tree
• Export single trace attestation per command execution
• Update attestation collection logic to exclude trace data from main attestation
• Add configuration options for tracing features

Phase 2: Enhanced Linux Tracing

• Add network syscall tracing
• Implement file write tracking
• Add timing and process relationship data
• Update process info collection

Phase 3: Cross-Platform Support

• Design and implement Tracer interface
• Add Windows process monitoring
• Add macOS process monitoring
• Implement script detection across platforms

Phase 4: Testing and Documentation

• Comprehensive test suite
• Performance benchmarks
• Update documentation
• Migration guide for schema changes

Testing Strategy

Local Development (macOS ARM)

• Use Docker Desktop for Linux testing with --privileged flag
• Native macOS tests for Darwin-specific code
• Cross-platform unit tests

Test Infrastructure

# Linux tracing tests
docker run --rm -it --privileged \
  --platform linux/arm64 \
  -v "$(pwd)":/workspace \
  golang:1.21-alpine \
  sh -c 'apk add gcc musl-dev linux-headers && go test -v -tags=linux ./attestation/commandrun/...'

CI/CD Pipeline

• Matrix testing across Linux/Windows/macOS
• Architecture testing (amd64/arm64)
• Performance regression tests

Success Criteria

• All existing tests pass
• New tracing features work on Linux with minimal performance impact
• Cross-platform program hashing works on all supported OS
• Multi-exporter produces valid attestations (main command attestation + single trace attestation)
• Schema changes are backward compatible
• Documentation is updated
• Performance overhead is < 20% for typical commands

Risks and Mitigations

1. Performance Impact: Network tracing and file hashing add significant overhead

   • Mitigation: Make network tracing opt-in via configuration
   • Mitigation: Make file/program hashing optional (can be disabled for performance-sensitive uses)

2. Platform Compatibility: Different OS have different APIs

   • Mitigation: Graceful degradation with clear error messages

3. Security: Ptrace restrictions (Yama LSM) on Linux

   • Mitigation: Detect and report restrictions clearly

4. Large Process Trees: Complex builds may spawn hundreds of processes

   • Mitigation: Single trace attestation maintains context while keeping main attestation lightweight

References

• Current implementation: /attestation/commandrun/
• Multi-exporter pattern: /attestation/factory.go
• Example exporter: /attestation/sbom/sbom.go

Related Issues

• #[previous issue number] - Add multi-exporter support
• #[previous issue number] - Improve attestation schema versioning

---

Labels: enhancement, refactoring, command-run, tracing, multi-platform
Assignees: TBD
Milestone: v0.2.0

[jkjell]

Have you considered using SCAI attestations for the evidence a Command Run Attestation could create? There's a great example here: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md#attestation-for-evidence-collection. Multiple pieces of evidence could be referenced in a single SCAI attestation.

It's not clear to me how a policy can be written for the MultiExporter. It would be interesting to see an example of how this additional attestation data is consumed.

[mikhailswift]

Design and implement Tracer interface

I don't believe we need an interface here. The framework for multiplatform tracing is already in place with the compile flags. We just don't have implementations for windows or darwin

[colek42]

Have you considered using SCAI attestations for the evidence a Command Run Attestation could create? There's a great example here: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md#attestation-for-evidence-collection. Multiple pieces of evidence could be referenced in a single SCAI attestation.

It's not clear to me how a policy can be written for the MultiExporter. It would be interesting to see an example of how this additional attestation data is consumed.

I think SCAI could work, but right now we want to keep all of the existing fields until we figure out versioning.

[colek42]

It's not clear to me how a policy can be written for the MultiExporter. It would be interesting to see an example of how this additional attestation data is consumed.

Correct, right now we do not have a policy language that can support any exported attestations. Having the data available and searchable is what most users of Witness seem to care about.