{"id":31962137,"url":"https://github.com/mp70/seriald","last_synced_at":"2025-10-14T16:34:09.084Z","repository":{"id":315547022,"uuid":"1052089131","full_name":"MP70/SerialD","owner":"MP70","description":"Serial server for 2025.","archived":false,"fork":false,"pushed_at":"2025-09-08T01:37:59.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T16:42:00.448Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MP70.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"agents.md","dco":null,"cla":null}},"created_at":"2025-09-07T11:36:56.000Z","updated_at":"2025-09-08T01:38:02.000Z","dependencies_parsed_at":"2025-09-19T08:56:31.147Z","dependency_job_id":"3d7e556f-0407-4821-9a2f-915adc80535b","html_url":"https://github.com/MP70/SerialD","commit_stats":null,"previous_names":["mp70/seriald"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MP70/SerialD","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MP70%2FSerialD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MP70%2FSerialD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MP70%2FSerialD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MP70%2FSerialD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MP70","download_url":"https://codeload.github.com/MP70/SerialD/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MP70%2FSerialD/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019577,"owners_count":26086753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T16:34:05.798Z","updated_at":"2025-10-14T16:34:09.075Z","avatar_url":"https://github.com/MP70.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  Serial Agent and CLI \n\n🔐 **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 **\n\n## Features\n\n### Core Security Features\n- **Linux User Authentication** - Uses system users and groups (no custom passwords)\n- **Role-Based Access Control (RBAC)** - Three security levels: admin, operator, user\n- **Port-Level Permissions** - Fine-grained control over serial device access\n- **Comprehensive Audit Logging** - All actions logged to `/var/log/serial-cli/audit.log`\n- **Group-Based Authorization** - Uses standard Linux groups (`dialout`, `serial-admin`, `serial-operator`)\n\n### Technical Features\n- **Modern SerialPort v12.x.x** - Latest Node.js serial port library\n- **TypeScript Implementation** - Type-safe, maintainable codebase\n- **WebSocket Agent Integration** - Secure connection to central management\n- **Hot-plug Support** - Automatic detection of USB serial devices\n- **Interactive CLI** - on local box.\n- **Command-line Automation** - Direct command execution for scripting\n- **Raspberry Pi 4/5 Support** - Optimized for Pi 4/5\n\n## Quick Start\n\n### 1. Build the CLI\n```bash\ncd cli\nnpm install\nnpm run build\n```\n\n### 2. Setup Linux Users and Groups (Linux only)\n```bash\nsudo ./setup-linux.sh\n```\n\nThis creates:\n- **serial-admin** user (password: admin123) - Full access + sudo\n- **serial-operator** user (password: operator123) - Agent + port management  \n- **serial-user** user (password: user123) - Basic port access only\n\n### 3. Run the CLI\n\n#### As Admin (Full Access)\n```bash\nsudo -u serial-admin serial-cli\n```\n\n#### As Operator (Port Management)\n```bash\nsudo -u serial-operator serial-cli\n```\n\n#### As Regular User (Read-only)\n```bash\nsudo -u serial-user serial-cli\n```\n\n## Security Model\n\n### User Roles\n\n| Role | Groups | Permissions |\n|------|--------|-------------|\n| **Admin** | `serial-admin`, `dialout`, `sudo` | Full system access, user management, all ports |\n| **Operator** | `serial-operator`, `dialout` | Agent control, port management, most ports |\n| **User** | `dialout` | Basic port listing, limited access |\n\n### Port Permissions\n\nDefault port access rules (configurable in `/etc/serial-cli/port-permissions.json`):\n\n```json\n{\n  \"/dev/ttyUSB*\": [\"dialout\", \"serial-operator\"],\n  \"/dev/ttyACM*\": [\"dialout\", \"serial-operator\"], \n  \"/dev/ttyS*\": [\"dialout\", \"serial-admin\"]\n}\n```\n\n## CLI Commands\n\n### Core Commands\n```bash\nwhoami                      # Show current user and permissions\nshow ports                  # List accessible serial ports\nshow agent status          # Check agent connection\nopen port /dev/ttyUSB0     # Open serial port\nclose port \u003csessionId\u003e     # Close port session\n```\n\n### Admin Commands (serial-admin only)\n```bash\nuser add \u003cuser\u003e \u003cgroups\u003e           # Create new Linux user\nuser delete \u003cusername\u003e             # Delete Linux user\nuser add-group \u003cuser\u003e \u003cgroup\u003e      # Add user to group\nset port-permissions \u003cport\u003e \u003cgrps\u003e # Configure port access\nshow audit [limit]                 # View audit logs\n```\n\n### Agent Commands\n```bash\nconnect agent              # Connect to serial agent\ndisconnect agent           # Disconnect from agent\nping agent                 # Test agent connectivity\nshow agent config          # View agent configuration\n```\n\n## Configuration Files\n\n### System Configuration\n- `/etc/serial-cli/port-permissions.json` - Port access rules\n- `/etc/serial-cli/environment` - Environment variables\n- `/etc/udev/rules.d/99-serial-cli.rules` - Device permissions\n- `/var/log/serial-cli/audit.log` - Audit trail\n\n### User Configuration\n- `~/.serial-cli/` - User-specific settings (if any)\n\n## Architecture\n\n### Components\n1. **CLI** (`cli/`) - Interactive command-line interface\n2. **Agent** (`agent/`) - Device-side agent for central management\n3. **Central Server** - VPS-based management (separate deployment)\n\n### Security Flow\n```\nLinux User → Group Check → Permission Validation → Action → Audit Log\n```\n\n### Agent Integration\n```\nCLI ←→ WebSocket ←→ Local Agent ←→ Serial Ports\n                    ↓\n                Central VPS\n```\n\n## Development\n\n### Build from Source\n```bash\n# CLI\ncd cli\nnpm install\nnpm run build\n\n# Agent (if needed)\ncd agent  \nnpm install\nnpm run build\n```\n\n### Testing\n```bash\n# Run demo\n./demo-linux-cli.sh\n\n# Test specific user\nsudo -u serial-admin ./cli/dist/cli.js whoami\n```\n\n## Deployment\n\n### Production Setup\n1. Run setup script: `sudo ./setup-linux.sh`\n2. Change default passwords: `sudo passwd serial-admin`\n3. Configure port permissions: Edit `/etc/serial-cli/port-permissions.json`\n4. Install CLI globally: `cd cli \u0026\u0026 npm install -g .`\n5. Start using: `sudo -u serial-admin serial-cli`\n\n### Security Hardening\n- Change all default passwords immediately\n- Review and customize port permissions\n- Enable SELinux/AppArmor if available\n- Monitor audit logs regularly: `tail -f /var/log/serial-cli/audit.log`\n- Restrict sudo access as needed\n\n## Troubleshooting\n\n### Common Issues\n\n#### Permission Denied\n```bash\n# Check user groups\ngroups serial-operator\n\n# Check port permissions  \nls -la /dev/ttyUSB*\n\n# Check configuration\ncat /etc/serial-cli/port-permissions.json\n```\n\n#### Agent Connection Failed\n```bash\n# Check agent status\nshow agent status\n\n# Test connectivity\nping agent\n\n# Check configuration\nshow agent config\n```\n\n#### Audit Logs\n```bash\n# View recent activity\nshow audit 20\n\n# Check log file directly\nsudo tail -f /var/log/serial-cli/audit.log\n```\n\n## Examples\n\n### Interactive Mode\n```bash\n$ sudo -u serial-admin serial-cli\n🔐 Enterprise Serial CLI - Linux Authentication Active\nserial-admin@serial\u003e whoami\nCurrent User:\n  Username: serial-admin\n  Groups: serial-admin, dialout, sudo\n  Admin: Yes\n\nserial-admin@serial\u003e show ports\nAvailable Serial Ports:\n  1. /dev/ttyUSB0\n     Manufacturer: FTDI\n     Access: ✅ Granted\n\nserial-admin@serial\u003e open port /dev/ttyUSB0 9600\n✅ Opened /dev/ttyUSB0 at 9600 baud (session: port-1694123456789)\n```\n\n### Command-line Mode\n```bash\n# Quick status check\nsudo -u serial-operator serial-cli show agent status\n\n# List ports for automation\nsudo -u serial-user serial-cli show ports\n\n# Open port directly\nsudo -u serial-admin serial-cli open port /dev/ttyUSB0 115200\n```\n\n## License\n\nEnterprise Serial CLI - Proprietary\n\n## Support\n\n- Check audit logs: `/var/log/serial-cli/audit.log`\n- Review configuration: `/etc/serial-cli/`\n- Test permissions: `./demo-linux-cli.sh`\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmp70%2Fseriald","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmp70%2Fseriald","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmp70%2Fseriald/lists"}