agent-smith-go

Agent Smith

Rewst's lean, open-source command executor that fits right into your Rewst workflows. See community corner for more details.

Installation

Agent Smith runs as a system service on Windows, Linux, and macOS. Installation involves configuring the agent with your organization credentials and starting the service.

Prerequisites

• A Rewst organization ID
• Configuration URL and secret from your Rewst platform
• Administrative/root privileges for service installation

Basic Installation

1. Download the appropriate binary for your platform from the releases page
2. Configure the agent with your organization credentials:

Windows:

rewst_agent_config.win.exe --org-id YOUR_ORG_ID --config-url CONFIG_URL --config-secret CONFIG_SECRET

Linux/macOS:

./rewst_agent_config.linux.bin --org-id YOUR_ORG_ID --config-url CONFIG_URL --config-secret CONFIG_SECRET
# or
./rewst_agent_config.mac-os.bin --org-id YOUR_ORG_ID --config-url CONFIG_URL --config-secret CONFIG_SECRET

Configuration Options

• --logging-level: Set logging verbosity (info, warn, error, debug)
• --syslog: Write logs to system log instead of file (Linux/macOS)
• --disable-agent-postback: Disable agent postback
• --no-auto-updates: Disable auto updates
• --mqtt-qos: MQTT subscription QoS level (0 = at-most-once, 1 = at-least-once, 2 = exactly-once). Defaults to 1 when omitted.

Example with optional parameters:

./rewst_agent_config --org-id YOUR_ORG_ID --config-url CONFIG_URL --config-secret CONFIG_SECRET --logging-level info --syslog --disable-agent-postback --no-auto-updates --mqtt-qos 1

Update

Once installed, the agent can be updated and configured using the config executable. The optional parameters are also available.

./rewst_agent_config --org-id YOUR_ORG_ID --update --logging-level info --syslog --disable-agent-postback --no-auto-updates --mqtt-qos 1

Service Mode

Once configured, the agent can run in service mode using the generated configuration:

./rewst_agent_config --org-id YOUR_ORG_ID --config-file /path/to/config.json --log-file /path/to/agent.log

Diagnostic Mode

The diagnostic mode provides an interactive menu to validate an installed agent without needing to inspect log files or know platform-specific service commands. It is useful for troubleshooting connectivity issues, verifying permissions, and confirming the agent is healthy.

Usage

Run without an org ID to scan all installed agents:

Windows:

rewst_agent_config.win.exe --diagnostic

Linux:

sudo ./rewst_agent_config.linux.bin --diagnostic

macOS:

sudo ./rewst_agent_config.mac-os.bin --diagnostic

To target a specific organization directly:

./rewst_agent_config --org-id YOUR_ORG_ID --diagnostic

Interactive menu

Once launched, the menu guides you through the following checks:

[1] Scan installed agents and check status
[2] Test command execution
[3] Test MQTT/WebSocket connectivity
[4] Test temp directory write access
[5] View live log data
[6] Run all checks
[0] Exit

Option	What it checks
1	Lists all installed agents with running/stopped status and config details (device ID, IoT Hub, engine host, log level)
2	Runs a test command using the platform shell (PowerShell on Windows, Bash on Linux/macOS) and confirms execution succeeds
3	Attempts TLS connections to the agent's IoT Hub on port 8883 (MQTT) and port 443 (WebSocket). Prints troubleshooting tips if both fail
4	Creates a test file in the scripts temp directory and reads it back to confirm write access
5	Opens the agent log file and tails it in real time. Press Ctrl+C to stop
6	Runs checks 1–4 in sequence

Example output

  ╔══════════════════════════════════════════════════╗
  ║         Agent Smith Diagnostic Mode              ║
  ║         Version: v1.1.0                          ║
  ║         Platform: windows/amd64                  ║
  ╚══════════════════════════════════════════════════╝

  ── Installed Agents ──

    [PASS] a1b2c3d4-... - RUNNING (RewstRemoteAgent_a1b2c3d4-...)
      Device ID:    device-xyz
      IoT Hub:      abc123.azure-devices.net
      Engine Host:  engine.rewst.io
      Log Level:    info
      Syslog:       false
      Auto-Updates: true
      MQTT QoS:     1

  ── MQTT/WebSocket Connectivity ──

    Host: abc123.azure-devices.net
    Testing MQTT (TLS port 8883)... OK
    [PASS] MQTT TLS connection to abc123.azure-devices.net:8883
    Testing WebSocket (port 443)... OK
    [PASS] WebSocket connection to abc123.azure-devices.net:443

Uninstallation

To remove Agent Smith from your system:

# Replace with your organization ID
./rewst_agent_config --org-id YOUR_ORG_ID --uninstall

This will stop the service, remove configuration files, and clean up system service registrations.

Features

• Cross-platform: Runs on Windows, Linux, and macOS
• Secure: Uses Azure IoT Hub MQTT for encrypted communication
• Extensible: Plugin system for custom notifications and integrations
• Reliable: Automatic reconnection and error handling
• Lightweight: Minimal resource footprint

How It Works

1. Agent connects to your Rewst organization via Azure IoT Hub MQTT
2. Receives command execution requests from Rewst workflows
3. Executes commands using PowerShell (Windows) or Bash (Unix/Linux/macOS)
4. Returns results back to the Rewst platform
5. Supports system information collection and custom plugins

Build

Required tools and packages:

• commitizen: To use a standardized description of commits.

  pipx ensurepath
  pipx install commitizen
  pipx upgrade commitizen
  

• go-winres: To embed icons and file versions to windows executables.

  go install github.com/tc-hib/go-winres@latest
  

Run the following command using powershell or pwsh to build the binary:

./scripts/build.ps1

Testing and Coverage

Agent Smith maintains high code quality through comprehensive testing with an 80% coverage threshold.

Running Tests

Run all tests:

go test ./...

Run tests with verbose output:

go test ./... -v

Run tests for a specific package:

go test ./cmd/agent_smith -v
go test ./internal/service -v
go test ./plugins -v

Run a specific test:

go test ./cmd/agent_smith -v -run TestLoadConfig

Coverage Reports

Generate coverage report:

./scripts/coverage.ps1

This script:

• Runs tests across all packages
• Generates coverage profiles
• Enforces 80% minimum coverage threshold

Note: When running tests locally on Linux, some tests write to /tmp/rewst_remote_agent/scripts. If that directory was created by root (e.g., via sudo), your user won't have write access. Fix it by running:

sudo chmod -R o+w /tmp/rewst_remote_agent

Test Categories

Unit Tests: Test individual functions and components in isolation

• Message parsing and validation
• Configuration loading
• SAS token generation
• Path resolution

Integration Tests: Test component interactions

• MQTT message flow (with test broker)
• Service lifecycle (start/stop/restart)
• Plugin loading and notifications
• Command execution and postback

Platform-Specific Tests: Test OS-specific functionality

• Windows service management
• Linux systemd integration
• macOS launchd integration
• System information collection

Writing Tests

When contributing new code, ensure:

1. Test coverage: Aim for >80% coverage for new code
2. Table-driven tests: Use for multiple test cases

   tests := []struct {
       name     string
       input    string
       expected string
   }{
       {"case1", "input1", "expected1"},
       {"case2", "input2", "expected2"},
   }
   

3. Clean up resources: Use t.TempDir() and defer statements
4. Avoid flaky tests: Use proper synchronization and timeouts
5. Mock external dependencies: Don't rely on network or filesystem in unit tests

CI/CD

Tests run automatically on:

• Every pull request
• Every push to main branch
• Pre-release validation

GitHub Actions Workflows:

• .github/workflows/test.yml - Runs test suite
• .github/workflows/coverage.yml - Validates coverage threshold

Pull requests must:

• ✅ Pass all tests
• ✅ Maintain ≥80% coverage
• ✅ Pass all linters
• ✅ Pass CodeQL security scanning

Code Quality and Linting

Agent Smith uses golangci-lint for strict security and code formatting enforcement.

Running Locally

Install golangci-lint:

See this guide to learn how to install golangci-lint on your local machine.

Run linter:

golangci-lint run

Auto-fix formatting:

golangci-lint run --fix

CI/CD

Linting runs automatically on:

• Every pull request
• Every push to main branch

Contributing

Contributions are always welcome. Please submit a PR!

Please use commitizen to format the commit messages. After staging your changes, you can commit the changes with this command.

cz commit

License

Agent Smith is licensed under GNU GENERAL PUBLIC LICENSE. See license file for details.