Skip to content

v0.3.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 02 Jan 05:50
· 1145 commits to main since this release
v0.3.0
7579e7b

Highlights

  • Windows Mini Filter Driver: Complete kernel-mode driver for filesystem and registry interception with policy enforcement, process tracking, and configurable fail modes.
  • macOS ESF + Network Extension: Enterprise-grade support using Apple's Endpoint Security Framework and Network Extension APIs (requires Apple entitlements).
  • macOS FUSE-T Support: Standard macOS support using FUSE-T for file policy enforcement without requiring Apple entitlements.
  • Multi-Mount Profiles: Mount multiple filesystem paths per session with independent policies for each mount.
  • Policy Generation: New agentsh policy generate command to create restrictive policies from observed session behavior.
  • User-Local Configuration: Non-root users can now run agentsh with their own configuration, policies, and data storage.
  • Security Hardening: Commands now default-deny, full-path command matching, dangerous env vars blocked by default.

What's New

Windows Mini Filter Driver (#47)

Complete kernel-mode mini filter driver for native Windows support:

# Install the driver (requires Administrator)
sc create agentsh type=filesys binPath="C:\path\to\agentsh.sys"
sc start agentsh

# Run the agentsh server
agentsh server
Phase Feature
Phase 1 Driver skeleton with filter port communication
Phase 2 Session registration and process tree tracking
Phase 3 Filesystem interception (create, write, delete, rename) with policy cache
Phase 4 Registry interception with high-risk path detection (MITRE ATT&CK mappings)
Phase 5 Configurable fail modes, metrics collection, runtime configuration

New Files:

  • drivers/windows/agentsh-minifilter/ - Complete C driver source
  • internal/platform/windows/driver_client.go - Go driver client
  • docs/windows-driver-deployment.md - Production deployment guide
  • .github/workflows/driver-windows.yml - CI workflow for driver builds

macOS ESF + Network Extension (#46)

Enterprise-grade macOS support using Apple's native security frameworks:

ESF/NE Events → System Extension (Swift) → XPC Service → Unix Socket → Go Policy Server
Component Description
ESF Client Subscribes to AUTH/NOTIFY events for file operations
NEFilterDataProvider Network traffic filtering
NEDNSProxyProvider DNS-based policy enforcement
XPC Service Bridge between Swift and Go policy server

Requirements: Apple Developer Program membership, ESF + Network Extension entitlements from Apple, Xcode 15+

macOS FUSE-T Support (#45)

Standard macOS support without Apple entitlements:

# Install FUSE-T
brew install fuse-t

# Build with CGO enabled (default on macOS)
CGO_ENABLED=1 go build -o agentsh ./cmd/agentsh

# Run the server
agentsh server

Graceful fallback to FSEvents observation mode when CGO unavailable.

Multi-Mount Profiles (#43)

Mount multiple filesystem paths with independent policies:

mount_profiles:
  claude-agent:
    base_policy: "default"
    mounts:
      - path: "/home/user/workspace"
        policy: "workspace-rw"
      - path: "/home/user/.config"
        policy: "config-readonly"
# Create session with profile
curl -X POST /api/v1/sessions -d '{"profile": "claude-agent"}'

# List available profiles
curl /api/v1/profiles

Policy Generation (#42)

Generate restrictive policies from observed session behavior:

# Profile a session, then generate policy
agentsh policy generate latest --output policy.yml

# Generate from specific session
agentsh policy generate <session-id> --output policy.yml

Features:

  • Smart path grouping (collapses to globs when files in same directory exceed threshold)
  • Domain grouping (collapses subdomains to wildcards like *.github.com)
  • Risky command detection
  • Blocked operations included as commented-out rules for review

User-Local Configuration (#44)

Non-root users can now run agentsh with their own configuration:

Source Priority Location
AGENTSH_CONFIG env 1 (highest) Custom path
User-local 2 ~/.config/agentsh/config.yml
System-wide 3 /etc/agentsh/config.yml

Cross-platform support: XDG on Linux, Library on macOS, APPDATA on Windows.

Security Improvements

Change Description
Commands default-deny Commands must be explicitly allowed in policy
Full-path command matching Prevents bypass via PATH manipulation
Dangerous env vars blocked LD_PRELOAD, DYLD_INSERT_LIBRARIES, etc. blocked by default
eBPF race fix Fixed race condition with ptrace-stopped process start

CLI Improvements

New environment variable support:

# Set session context via environment
export AGENTSH_SESSION_ID="my-session"
export AGENTSH_SESSION_ROOT="/workspace"

# Execute command in session context
agentsh exec -- npm install

Breaking Changes

  • Commands now default-deny: Update your policies to explicitly allow required commands
  • Dangerous env vars blocked by default: If your workflow requires LD_PRELOAD or similar, add explicit allow rules

Platform Support Matrix

Platform Implementation Security Score
Linux Native FUSE3 + iptables 100%
Windows Native Mini Filter + WinDivert 65%
Windows WSL2 FUSE3 (Linux) 100%
macOS ESF+NE Endpoint Security + Network Extension 90%
macOS FUSE-T FUSE-T + pf 70%
macOS + Lima FUSE3 in VM 85%

Downloads

Platform Architecture Format
Linux amd64, arm64 tar.gz, deb, rpm, pkg.tar.zst
macOS amd64, arm64 tar.gz
Windows amd64, arm64 zip

Note: Windows driver (.sys) is built separately via the driver-windows CI workflow and requires test-signing for development or EV signing for production.

Changelog

Features

  • feat(windows): Windows Mini Filter Driver - Phases 1-5 Complete (#47)
  • feat(darwin): add macOS ESF + Network Extension support (#46)
  • feat(darwin): implement FUSE-T filesystem mounting (#45)
  • feat: user-local configuration support (#44)
  • feat: add multi-mount support for sessions with per-mount policies (#43)
  • feat: add policy generate command (#42)
  • feat(cli): support AGENTSH_SESSION_ID and AGENTSH_SESSION_ROOT env vars
  • feat(cli): add --root flag to exec for auto-creating sessions
  • feat(config): support environment variable expansion in config files

Security

  • security(policy): change commands to default-deny, update default policy
  • security(policy): support full-path command matching to prevent bypass
  • security(exec): fix eBPF race condition with ptrace-stopped process start
  • security(policy): block dangerous env vars by default

Fixes

  • fix(policy): handle invalid glob patterns in command rules gracefully
  • fix(cli): handle duplicate session ID in args when env var is set
  • fix(session): allow hyphens in session IDs
  • fix(cli): treat all args as command when AGENTSH_SESSION_ID is set

Documentation

  • docs: add Windows driver deployment guide
  • docs: add SECURITY.md with threat model documentation
  • docs: add platform-specific limitations for macOS and Windows
  • docs: add AI assistant integration examples (Claude, Cursor, AGENTS.md)
Assets 15
Loading