Serial Agent and CLI

🔐 **A secure, enterprise-grade serial server management system with Linux user authentication, comprehensive audit logging, and robust access control. Agent mTLS websocket to a central management server to allow a 'single pane of glass' for all serial servers/sessions **

Features

Core Security Features

• Linux User Authentication - Uses system users and groups (no custom passwords)
• Role-Based Access Control (RBAC) - Three security levels: admin, operator, user
• Port-Level Permissions - Fine-grained control over serial device access
• Comprehensive Audit Logging - All actions logged to /var/log/serial-cli/audit.log
• Group-Based Authorization - Uses standard Linux groups (dialout, serial-admin, serial-operator)

Technical Features

• Modern SerialPort v12.x.x - Latest Node.js serial port library
• TypeScript Implementation - Type-safe, maintainable codebase
• WebSocket Agent Integration - Secure connection to central management
• Hot-plug Support - Automatic detection of USB serial devices
• Interactive CLI - on local box.
• Command-line Automation - Direct command execution for scripting
• Raspberry Pi 4/5 Support - Optimized for Pi 4/5

Quick Start

1. Build the CLI

cd cli
npm install
npm run build

2. Setup Linux Users and Groups (Linux only)

sudo ./setup-linux.sh

This creates:

• serial-admin user (password: admin123) - Full access + sudo
• serial-operator user (password: operator123) - Agent + port management
• serial-user user (password: user123) - Basic port access only

3. Run the CLI

As Admin (Full Access)

sudo -u serial-admin serial-cli

As Operator (Port Management)

sudo -u serial-operator serial-cli

As Regular User (Read-only)

sudo -u serial-user serial-cli

Security Model

User Roles

Role	Groups	Permissions
Admin	serial-admin, dialout, sudo	Full system access, user management, all ports
Operator	serial-operator, dialout	Agent control, port management, most ports
User	dialout	Basic port listing, limited access

Port Permissions

Default port access rules (configurable in /etc/serial-cli/port-permissions.json):

{
  "/dev/ttyUSB*": ["dialout", "serial-operator"],
  "/dev/ttyACM*": ["dialout", "serial-operator"], 
  "/dev/ttyS*": ["dialout", "serial-admin"]
}

CLI Commands

Core Commands

whoami                      # Show current user and permissions
show ports                  # List accessible serial ports
show agent status          # Check agent connection
open port /dev/ttyUSB0     # Open serial port
close port <sessionId>     # Close port session

Admin Commands (serial-admin only)

user add <user> <groups>           # Create new Linux user
user delete <username>             # Delete Linux user
user add-group <user> <group>      # Add user to group
set port-permissions <port> <grps> # Configure port access
show audit [limit]                 # View audit logs

Agent Commands

connect agent              # Connect to serial agent
disconnect agent           # Disconnect from agent
ping agent                 # Test agent connectivity
show agent config          # View agent configuration

Configuration Files

System Configuration

• /etc/serial-cli/port-permissions.json - Port access rules
• /etc/serial-cli/environment - Environment variables
• /etc/udev/rules.d/99-serial-cli.rules - Device permissions
• /var/log/serial-cli/audit.log - Audit trail

User Configuration

• ~/.serial-cli/ - User-specific settings (if any)

Architecture

Components

1. CLI (cli/) - Interactive command-line interface
2. Agent (agent/) - Device-side agent for central management
3. Central Server - VPS-based management (separate deployment)

Security Flow

Linux User → Group Check → Permission Validation → Action → Audit Log

Agent Integration

CLI ←→ WebSocket ←→ Local Agent ←→ Serial Ports
                    ↓
                Central VPS

Development

Build from Source

# CLI
cd cli
npm install
npm run build

# Agent (if needed)
cd agent  
npm install
npm run build

Testing

# Run demo
./demo-linux-cli.sh

# Test specific user
sudo -u serial-admin ./cli/dist/cli.js whoami

Deployment

Production Setup

1. Run setup script: sudo ./setup-linux.sh
2. Change default passwords: sudo passwd serial-admin
3. Configure port permissions: Edit /etc/serial-cli/port-permissions.json
4. Install CLI globally: cd cli && npm install -g .
5. Start using: sudo -u serial-admin serial-cli

Security Hardening

• Change all default passwords immediately
• Review and customize port permissions
• Enable SELinux/AppArmor if available
• Monitor audit logs regularly: tail -f /var/log/serial-cli/audit.log
• Restrict sudo access as needed

Troubleshooting

Common Issues

Permission Denied

# Check user groups
groups serial-operator

# Check port permissions  
ls -la /dev/ttyUSB*

# Check configuration
cat /etc/serial-cli/port-permissions.json

Agent Connection Failed

# Check agent status
show agent status

# Test connectivity
ping agent

# Check configuration
show agent config

Audit Logs

# View recent activity
show audit 20

# Check log file directly
sudo tail -f /var/log/serial-cli/audit.log

Examples

Interactive Mode

$ sudo -u serial-admin serial-cli
🔐 Enterprise Serial CLI - Linux Authentication Active
serial-admin@serial> whoami
Current User:
  Username: serial-admin
  Groups: serial-admin, dialout, sudo
  Admin: Yes

serial-admin@serial> show ports
Available Serial Ports:
  1. /dev/ttyUSB0
     Manufacturer: FTDI
     Access: ✅ Granted

serial-admin@serial> open port /dev/ttyUSB0 9600
✅ Opened /dev/ttyUSB0 at 9600 baud (session: port-1694123456789)

Command-line Mode

# Quick status check
sudo -u serial-operator serial-cli show agent status

# List ports for automation
sudo -u serial-user serial-cli show ports

# Open port directly
sudo -u serial-admin serial-cli open port /dev/ttyUSB0 115200

License

Enterprise Serial CLI - Proprietary

Support

• Check audit logs: /var/log/serial-cli/audit.log
• Review configuration: /etc/serial-cli/
• Test permissions: ./demo-linux-cli.sh

---