Architecture

System Overview

The SSI Agent operates as a systemd-native monitoring daemon on Linux systems. It consists of three main components:

1. CLI Tool (ssi) — For user interaction and configuration
2. Daemon (ssi-agent-daemon) — Long-running process for backend communication
3. Service Scripts — BASH scripts managed by systemd

Execution Model

Daemon Mode

The SSI Agent daemon (ssi-agent-daemon) is a long-running systemd service that:

• Maintains a WebSocket connection to the backend
• Watches log files for changes using file system events
• Parses log entries and sends status updates
• Handles connection failures with exponential backoff

The daemon is managed by systemd:

1# Service file: /etc/systemd/system/ssi-agent.service
2systemctl status ssi-agent
3systemctl restart ssi-agent
4journalctl -u ssi-agent -f

Timer-Based Execution

Service scripts are not executed by the daemon directly. Instead:

1. Each service script has a corresponding systemd timer
2. The timer triggers a systemd service unit
3. The service unit executes the BASH script
4. Script output is captured to log files
5. The daemon watches log files and reports changes

This design ensures:

• Reliability: systemd handles scheduling, timeouts, and restarts
• Isolation: Each script runs in its own process
• Transparency: Standard systemd tools work (journalctl, systemctl)

Unit File Structure

For a service with ID api_health, the following files are created:

Service Unit (ssi-api-health.service):

1[Unit]
2Description=Checks the health of an API
3After=network.target
4
5[Service]
6Type=oneshot
7ExecStart=/bin/bash -c '/opt/ssi-agent/.installed-service-scripts/api-health.bash'
8TimeoutSec=10
9StandardOutput=append:/var/log/ssi-agent/api-health.log
10StandardError=append:/var/log/ssi-agent/api-health.log

Timer Unit (ssi-api-health.timer):

1[Unit]
2Description=Timer for API health check
3
4[Timer]
5OnCalendar=*:0/01:00
6Persistent=true
7RandomizedDelaySec=30
8
9[Install]
10WantedBy=timers.target

Directory Structure

Communication Flow

Status Reporting

1. Script executes and prints to stdout:

   2024-01-15 10:30:00, OK, API is healthy

2. systemd captures output to log file:

   /var/log/ssi-agent/api-health.log

3. Daemon detects file change and parses the new line

4. Daemon sends status update via WebSocket:

   json

   Copy

   1{
   2  "service_id": "api-health",
   3  "status": "OK",
   4  "message": "API is healthy",
   5  "timestamp": "2024-01-15T10:30:00"
   6}

5. Backend receives and broadcasts to connected clients

Registration Flow

1. ssi register requests a registration code from the backend
2. Backend generates a 6-digit code and UUID pair
3. User enters the code in the mobile app
4. Mobile app confirms registration with backend
5. CLI polls for confirmation and receives agent key
6. Agent key is stored in /etc/ssi-agent/config.json

Resource Constraints

Failure Handling

Fail-Fast (Fatal Errors)

The agent exits immediately on:

• Invalid or missing configuration
• Invalid authentication credentials
• Missing systemd dependency
• Corrupt persistent state

Fail-Soft (Recoverable)

The agent retries with backoff on:

• Transient network failures
• Backend temporarily unavailable
• Individual script failures

Security Model

Agent Permissions

• Runs as dedicated ssi-agent user
• Read access to service scripts
• Write access to log directory
• Read/Write access to config directory

Authentication

• Agent authenticates with a unique agent key
• Key is obtained during registration
• Key is stored securely in config file
• All communication uses TLS (WSS/HTTPS)

Trust Model

• Agent is semi-trusted (limited permissions)
• Agent cannot modify backend configuration
• Agent cannot execute arbitrary remote commands
• Agent can only report status