https://github.com/mp70/seriald
Serial server for 2025.
https://github.com/mp70/seriald
Last synced: 9 months ago
JSON representation
Serial server for 2025.
- Host: GitHub
- URL: https://github.com/mp70/seriald
- Owner: MP70
- Created: 2025-09-07T11:36:56.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-08T01:37:59.000Z (10 months ago)
- Last Synced: 2025-10-03T16:42:00.448Z (9 months ago)
- Language: JavaScript
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: agents.md
Awesome Lists containing this project
README
# 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
```bash
cd cli
npm install
npm run build
```
### 2. Setup Linux Users and Groups (Linux only)
```bash
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)
```bash
sudo -u serial-admin serial-cli
```
#### As Operator (Port Management)
```bash
sudo -u serial-operator serial-cli
```
#### As Regular User (Read-only)
```bash
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`):
```json
{
"/dev/ttyUSB*": ["dialout", "serial-operator"],
"/dev/ttyACM*": ["dialout", "serial-operator"],
"/dev/ttyS*": ["dialout", "serial-admin"]
}
```
## CLI Commands
### Core Commands
```bash
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 # Close port session
```
### Admin Commands (serial-admin only)
```bash
user add # Create new Linux user
user delete # Delete Linux user
user add-group # Add user to group
set port-permissions # Configure port access
show audit [limit] # View audit logs
```
### Agent Commands
```bash
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
```bash
# CLI
cd cli
npm install
npm run build
# Agent (if needed)
cd agent
npm install
npm run build
```
### Testing
```bash
# 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
```bash
# 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
```bash
# Check agent status
show agent status
# Test connectivity
ping agent
# Check configuration
show agent config
```
#### Audit Logs
```bash
# View recent activity
show audit 20
# Check log file directly
sudo tail -f /var/log/serial-cli/audit.log
```
## Examples
### Interactive Mode
```bash
$ 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
```bash
# 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`
---