# nanokvm-mqtt

Exposes NanoKVM API via MQTT with support for home assistant autodiscovery/config.

## Implementation

This project is built with TypeScript and enforces runtime type safety where possible by using [zod](https://zod.dev).

## Disclaimer

Please read the License and understand that this program comes with **no warranties or guarantees**.

**Critical Security Warning:** Exposing a KVM (Keyboard, Video, Mouse) device over a network creates significant security risks, as it provides direct access to connected systems. Carefully review our security advisories below before deployment.

## Usage

1. Clone the repository
2. Create one or multiple client configs like ```xxx.client.json```
3. **Option A (recommended)** Use docker-compose like in the provided example ```docker-compose.example.yml```
3. **Option B** Install bun and run via ```bun run build && bun run start```
4. Your NanoKVM(s) should now show up in home assistant via autodiscovery

## Security Notices

### NanoKVM

**Critical vulnerability:** The NanoKVM firmware currently uses a hardcoded secret key for authentication.
Thats only one of the many security flaws.
By default, this project includes the known hardcoded secret for compatibility.

We strongly recommend blocking every connection going in and out of the NanoKVM by default,
and only allow as narrow access as possible to the web server (port 80) with return traffic.
Its also recommended to only enable SSH when you need it.

### Additional Security Recommendations

- **TLS/SSL:** Use encrypted MQTT connections (mqtts://) with valid certificates
- **MQTT Authentication:** Enable username/password authentication on your MQTT broker
- **Access Control:** Implement MQTT ACLs (Access Control Lists) to restrict topic access
- **Firewall Rules:** Block external access; only allow connections from trusted IPs
- **Regular Updates:** Monitor for NanoKVM firmware and dependency updates

### Usage with Home Assistant

**Think carefully before integrating this with Home Assistant**, especially if:

- Your Home Assistant instance is publicly accessible
- You use cloud-based integrations or remote access features
- Multiple users have access to your Home Assistant dashboard

**Recommended mitigations:**

- Keep Home Assistant on a private network only
- Use VPN access instead of port forwarding
- Monitor access logs regularly
- Consider if you truly need KVM control through Home Assistant

### Known Risks

Potential attack vectors include:

- Unauthorized access to connected computers/servers
- Keystroke injection and command execution
- Screen capture and information disclosure
- BIOS/firmware manipulation on connected systems
- Lateral movement within your network