SentinelGo

Cross‑platform Go agent/service that:

• Collects comprehensive OS‑level metrics (CPU, memory, disk, network)
• Gathers detailed agent information (serial number, battery condition, local users, OSQuery version)
• Sends agent updates to Supabase (configurable intervals)
• Checks for updates once per day from GitHub Releases and self‑updates
• Runs as a service on Windows, Linux (systemd), and macOS (launchd)

🚀 Features

System Metrics Collection

• CPU: Model name, cores, usage percentage
• Memory: Total, used, free, usage percentage
• Disk: Total, used, free space
• Network: Interface statistics and IP addresses

🆕 Agent Information Collection

• Device Serial Number: Cross-platform hardware identification
• Battery Condition: Real-time battery status and charge level
• Local User Accounts: Human user accounts (excludes system accounts)
• OSQuery Version: Detection of installed OSQuery version
• Disk Encryption: Cross-platform disk encryption status detection
• System Information: Hostname, OS, platform, architecture, uptime

Cross-Platform Support

• Linux: /sys/class/dmi/id/, /etc/machine-id, /sys/class/power_supply/, /etc/passwd
• macOS: system_profiler, pmset, dscl commands
• Windows: wmic commands for hardware and user information

Quick Start

1. Download the binary for your OS from GitHub Releases.
2. Follow the OS‑specific installation guide in the doc/ folder:
   • Windows
   • Linux
   • macOS

Build from Source

Quick Build (Development)

# Build for current platform only
make build

# Or build all platforms
make release

Release Build

# Build with specific version
make release VERSION=v1.0.0

# Build using git tag (auto-detected)
make release

# Create GitHub release (requires gh CLI)
./scripts/release.sh --release --version v1.0.0

Environment Setup

1. Copy environment template:

cp .env.example .env

2. Edit .env file with your Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key
API_TOKEN=your-api-token

The Supabase credentials are loaded from environment variables at runtime instead of being embedded in the binary.

Configuration (Optional)

The agent requires Supabase credentials to be set via environment variables. You can optionally override defaults like software sync interval or GitHub repo:

Environment Variables

• Create a .env file in the same directory as the binary or set system environment variables:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key
API_TOKEN=your-api-token

Configuration Files

• Windows: C:\ProgramData\sentinelgo\config.json
• Linux: /etc/sentinelgo/config.json
• macOS: /etc/sentinelgo/config.json

Example:

{
  "update_interval": "5m0s",
  "github_owner": "habib45",
  "github_repo": "SentinelGo",
  "current_version": "v2.0.8",
  "auto_update": false,
  "software_sync_enabled": true
}

Configuration Fields

• update_interval: How often to sync software information (supports "5m0s" format or seconds)
• github_owner: GitHub repository owner for updates
• github_repo: GitHub repository name for updates
• current_version: Current agent version
• auto_update: Enable automatic updates (default: false)
• software_sync_enabled: Enable software synchronization (default: true)

CLI Options

./sentinelgo -install      # Install as a service (requires admin/root)
./sentinelgo -uninstall    # Uninstall the service
./sentinelgo -run          # Run in foreground (console mode)
./sentinelgo -config <path> # Use custom config file

Data Flow

Agent Information Update

The agent updates its information in the agents table:

{
  "serial_number": "44069f5e9a494441b9e1c2c864bd820e",
  "osquery_version": "not installed",
  "battery_condition": "Charging (98%)",
  "local_users": ["bs01463", "bs-support", "sbt", "sentinelgo"],
  "disk_encryption": "yes",
  "last_restart": 384732
}

Local Users Storage: The local_users field is stored as a JSON array in the database, containing only human user account names (system accounts are filtered out).

Database Schema

The agent requires these tables in your Supabase database:

Update Mechanism

• Every 24 hours, the agent queries GitHub Releases for the latest tag.
• If newer, it downloads the matching asset for the current OS/arch.
• It replaces the running binary and restarts.
• On Windows, a batch script handles the replace-after-exit.

Development

Testing

The agent includes comprehensive tests for all agent information collection features:

# Run all tests
go test ./tests/ -v

# Run benchmarks
go test ./tests/ -bench=. -benchmem

# Run specific test
go test ./tests/ -run TestGetLocalUsers -v

# Test agent information collection
go test ./tests/ -run TestSystemInfoCollection -v

Test Coverage

• ✅ Local Users Collection: Detects and validates user accounts
• ✅ Serial Number Collection: Cross-platform hardware identification
• ✅ Battery Condition: Real-time battery status monitoring
• ✅ OSQuery Detection: Version detection and validation
• ✅ System Information: Complete system metrics collection
• ✅ Performance Benchmarks: Memory and timing analysis

Makefile Targets

make build          # Build for current platform
make release        # Build all platforms
make test           # Run tests
make clean          # Clean build artifacts
make deps           # Download dependencies

Test Files

• tests/agent_info_test.go: Unit tests for agent information collection
• tests/benchmark_test.go: Performance benchmarks
• Tests validate cross-platform compatibility and data accuracy

Release Process

1. Tag the release:

git tag v1.0.0
git push origin v1.0.0

2. Automatic Release (GitHub Actions will trigger):

   • Runs tests
   • Builds all platforms
   • Creates GitHub release with assets

3. Manual Release (alternative):

./scripts/release.sh --release --version v1.0.0

Version Management

• Versions are injected at build time via ldflags
• Use semantic versioning (v1.0.0, v1.0.1, etc.)
• Git tags are automatically detected for versioning

Security & Privacy

Data Collection

The agent collects the following information for device management and monitoring:

System Information (Low Sensitivity)

• Hardware Details: CPU model, memory, disk space, network interfaces
• Operating System: OS name, version, architecture, uptime
• Network Information: Private and public IP addresses

Agent Information (Medium Sensitivity)

• Device Serial Number: Hardware identifier for device tracking
• Battery Condition: Battery status and charge level (laptops/devices with battery)
• Local User Accounts: Human user account names (excludes system accounts)
• OSQuery Version: Detection of security tool installation

Security Considerations

• User Privacy: Local user accounts collection excludes system accounts and only captures usernames
• Data Minimization: Only essential information required for device management is collected
• Secure Transmission: All data is transmitted via HTTPS to Supabase
• Access Control: Agent requires proper authentication tokens to update database

Recommendations

• Review collected data to ensure compliance with your organization's privacy policies
• Consider implementing Row Level Security (RLS) in Supabase for data access control
• Use environment variables for sensitive configuration (API keys, tokens)
• Regularly update the agent to benefit from security improvements

System Requirements

• Linux: Requires root access for full system metrics collection
• macOS: Requires administrator privileges for hardware information
• Windows: Requires Administrator rights for system-level data collection

License

MIT