Skip to content

v0.6.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 11 Jan 22:26
· 832 commits to main since this release
v0.6.0
9ebabf3

v0.6.0 - Signal Interception & Filtering

This release adds signal interception capabilities, allowing policy-based control over which signals can be sent between processes. On Linux, signals can be blocked, redirected, or audited using seccomp user-notify.

Features

Signal Interception

Intercept and control signal delivery between processes using policy rules:

signal_rules:
  # Allow signals to self and children
  - name: allow-self
    signals: ["@all"]
    target:
      type: self
    decision: allow

  - name: allow-children
    signals: ["@all"]
    target:
      type: children
    decision: allow

  # Redirect SIGKILL to graceful SIGTERM
  - name: graceful-kill
    signals: ["SIGKILL"]
    target:
      type: descendants
    decision: redirect
    redirect_to: SIGTERM

  # Block fatal signals to external processes
  - name: deny-external-fatal
    signals: ["@fatal"]
    target:
      type: external
    decision: deny

Platform Support

Platform Blocking Redirect Audit
Linux ✅ seccomp user-notify ✅ ✅
macOS ❌ ❌ ✅ ES Framework
Windows ⚠️ Partial ❌ ✅ ETW

Signal Groups

Pre-defined signal groups for common use cases:

Group Signals
@all All signals (1-31)
@fatal SIGKILL, SIGTERM, SIGQUIT, SIGABRT
@job SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
@reload SIGHUP, SIGUSR1, SIGUSR2
@ignore SIGCHLD, SIGURG, SIGWINCH

Target Types

Control which processes can receive signals:

Target Description
self Process signaling itself
children Direct child processes
descendants All descendant processes
siblings Processes with same parent
session Any process in agentsh session
parent The agentsh supervisor
external PIDs outside session
system PID 1 and kernel threads
user Other processes owned by same user
process Match by process name pattern
pid_range Match by PID range

Decision Types

Decision Behavior
allow Signal delivered normally
deny Returns EPERM to sender
redirect Changes signal (e.g., SIGKILL → SIGTERM)
audit Allow + log event
approve Require manual approval
absorb Silently drop (no error to sender)

Implementation Details

Linux (seccomp user-notify)

  • Traps signal syscalls: kill, tkill, tgkill, rt_sigqueueinfo, pidfd_send_signal
  • PID registry tracks all session processes for target classification
  • Signal handler runs in parent process, evaluating policies in real-time
  • Supports redirect by modifying signal number before continuing syscall

Architecture

Agent Process → kill(pid, sig) → seccomp filter → notify fd → agentsh handler
                                                              ↓
                                              Target classify → Policy evaluate → Decision
                                                              ↓
                                              allow/deny/redirect → syscall continues or EPERM

Pull Requests

PR #65: Wire signal filter into runtime supervisor

  • Wire the signal filter into the runtime supervisor for signal rule enforcement
  • Mirror unix socket notify pattern: wrapper config → filter installation → FD to parent → handler loop
  • Add SignalFilterEnabled to wrapper config, passed via AGENTSH_SECCOMP_CONFIG
  • Create separate socket pair for signal filter FD (AGENTSH_SIGNAL_SOCK_FD=4)
  • Add signal handler mirroring notify_linux.go pattern
  • Add signal fields to extraProcConfig (signalParentSock, signalEngine, signalRegistry)
  • Register spawned processes in signal registry for classification
  • Add Windows stubs for cross-compilation support

PR #64: Add signal interception for process signal control

  • Add signal interception subsystem using Linux seccomp user-notify
  • Implement signal policy engine with comprehensive target types
  • Support signal groups (@fatal, @job, @reload, @ignore, @ALL)
  • Support decisions: allow, deny, audit, approve, redirect, absorb
  • Add PID registry for session process tracking with UID-based classification
  • Integrate with policy engine via SignalEngine() accessor
  • Platform detection with runtime check for seccomp capability
  • Proper handling of process group signals: kill(0), kill(-pgid), tkill

Commits

Signal Runtime Integration (PR #65)

  • b824720 fix(signal): add Windows stubs for cross-compilation
  • f053443 test(signal): add integration test for signal filter
  • ec3eba9 feat(signal): use separate socket for signal filter fd
  • b8029de feat(signal): wire signal filter into core exec flow
  • 99367fe feat(signal): start signal handler in runCommandWithResources
  • f852030 feat(signal): add signal fields to extraProcConfig
  • 00bafa9 feat(signal): add signal handler for API
  • 05bf556 feat(signal): install signal filter in wrapper
  • 81829af feat(signal): add signal filter config to wrapper
  • a553402 docs: add signal runtime integration plan

Signal Interception Core (PR #64)

  • a79803a docs: add signal interception to README and platform comparison
  • 5865e89 fix(signal): use platform detection for blocking capability
  • a63ba0f fix(signal): handle process group signals and tkill correctly
  • eb85916 fix(signal): correct TargetSystem to match only PID 1 and 2
  • 46463d3 fix(signal): track UID for accurate SameUser classification
  • 42b7a17 fix(signal): remove arch-specific syscall number test
  • a5d3046 fix(policy): add Windows build support for signal rules
  • 0140273 docs: add plan for fixing code review issues
  • 90e8b74 test(signal): add integration tests
  • ae0494a docs: add signal rules documentation
  • fbaea62 fix(signal): add @ALL signal group
  • 3c58f34 feat(policy): add signal rules to policies
  • 01989b1 feat(policy): integrate signal engine into policy engine
  • 1212640 feat(signal): add signal notification handler
  • 75d3d89 feat(signal): add Linux seccomp filter for signal syscalls
  • 32bbaa9 feat(events): add signal event types
  • 4e84556 feat(signal): add policy engine for signal evaluation
  • a5943c4 feat(signal): add PID registry for session tracking
  • 4188e2a feat(policy): add SignalRule to policy model
  • dff7fb1 feat(signal): add target type definitions and matching
  • b7d64db fix(signal): address code review feedback
  • e4050d0 feat(signal): add signal types and group expansion
  • b2e7079 docs: add signal interception implementation plan
  • 7aec733 docs: add signal interception design document

Release Fix

  • 9ebabf3 fix(release): add libfuse-dev to release workflow

Documentation

  • Added Signal Filtering section to README.md
  • Added Section 8.6 Signal Interception to docs/spec.md
  • Added signal protection to SECURITY.md threat model
  • Updated docs/seccomp.md with signal interception details
  • Updated docs/operations/policies.md with signal rules reference
  • Added signal interception to docs/platform-comparison.md

Full Changelog: v0.5.0...v0.6.0

🤖 Generated with Claude Code

Contributors

fatal, job, and 3 other contributors
Assets 15
Loading