remctl 0.1.0__tar.gz

remctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release
+- Core crypto: Ed25519 identity keys, X25519 ECDH handshake, AES-256-GCM transport encryption
+- Wire protocol: pydantic-based message schemas, length-prefixed framing, replay protection
+- LAN discovery: UDP broadcast beacon + peer table
+- Node daemon: async TCP server, command dispatch, audit logging, rate limiting
+- CLI client: all commands (lock, shutdown, restart, sleep, logout, closefocused,
+  exec, screenshot, push, pull, status, cancel)
+- Two-way pairing: both node and controller must explicitly trust each other
+- Permission tiers: observe, standard, full
+- Platform support: Windows (first-class), Linux (second-class), macOS (stub)
+- Service installation: Windows service (pywin32), Linux systemd unit

remctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 remctl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remctl-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: remctl
+Version: 0.1.0
+Summary: Secure LAN-based remote PC control and administration
+Author: remctl contributors
+License: MIT
+License-File: LICENSE
+Keywords: administration,lan,remote-control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: mss>=9.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Requires-Dist: zeroconf>=0.132
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# remctl
+
+**Secure, LAN-based remote PC control and administration.**
+
+`remctl` lets you control machines on your local network from the command line —
+lock, shutdown, execute shell commands with streaming output, transfer files,
+take screenshots, and check system status. All communication is authenticated
+using Ed25519 keys and encrypted with AES-256-GCM.
+
+> ⚠️ **Intended for your own trusted LAN devices only.** `remctl` is not designed
+> for Internet-facing use. Do not expose it via port forwarding or NAT.
+
+## Installation
+
+```bash
+pip install remctl
+```
+
+### From source
+
+```bash
+# TODO: user adds PyPI API token via env var / twine config before publishing
+git clone <repo-url>
+cd remctl
+pip install -e ".[dev]"
+```
+
+## Quick Start: Pairing Walkthrough
+
+`remctl` requires two-way trust: both the node and the controller must explicitly
+authorize each other.
+
+### On the target machine (the node)
+
+```bash
+# Show the node's fingerprint
+remctl node pair --show
+
+# Start the agent (background via service is recommended)
+remctl node start
+```
+
+### On the controlling machine
+
+```bash
+# Discover nodes on the LAN
+remctl ctl discover
+
+# Pair with a node (verify the fingerprint before confirming)
+remctl ctl pair <node-ip>
+
+# Show your own fingerprint for the node to trust you
+remctl ctl pair-show
+```
+
+### Back on the node (trust the controller)
+
+```bash
+# Trust the controller's public key (copy from the controller's output)
+remctl node trust-controller /path/to/controller_identity.pub
+```
+
+### Send commands
+
+```bash
+remctl ctl <target> status
+remctl ctl <target> lock
+remctl ctl <target> exec "whoami"
+remctl ctl <target> screenshot -o screenshot.png
+remctl ctl <target> push ./file.txt /remote/path/file.txt
+remctl ctl <target> pull /remote/log.log ./log.log
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `remctl node start` | Start the node agent in foreground |
+| `remctl node install-service` | Install as OS service |
+| `remctl ctl discover` | Discover nodes on LAN |
+| `remctl ctl pair <target>` | Pair with a node |
+| `remctl ctl <target> lock` | Lock the remote workstation |
+| `remctl ctl <target> shutdown --delay 60` | Shutdown with optional delay |
+| `remctl ctl <target> restart` | Restart |
+| `remctl ctl <target> sleep` | Sleep/Suspend |
+| `remctl ctl <target> logout` | Log out current user |
+| `remctl ctl <target> closefocused` | Close active window |
+| `remctl ctl <target> exec <command>` | Execute shell command (streamed) |
+| `remctl ctl <target> status` | Show system status (CPU/mem/disk/uptime) |
+| `remctl ctl <target> screenshot -o out.png` | Capture screenshot |
+| `remctl ctl <target> push <local> <remote>` | Push file to node |
+| `remctl ctl <target> pull <remote> <local>` | Pull file from node |
+| `remctl ctl <target> cancel` | Cancel pending shutdown/restart |
+
+## Security Model (Summary)
+
+- **Identity:** Ed25519 keypairs generated on first run.
+- **Authentication:** Two-way explicit pairing — both sides must trust each other.
+- **Encryption:** X25519 ECDH key exchange → AES-256-GCM, with forward secrecy.
+- **Replay protection:** Per-message sequence numbers + 30-second timestamp window.
+- **Permission tiers:** `observe` (status/screenshot), `standard` (commands +
+  files), `full` (includes `exec`). Default: `standard`.
+- **Audit log:** All commands logged unredacted at `~/.remctl/audit.log`.
+
+See [docs/SECURITY.md](docs/SECURITY.md) for the full threat model.
+
+## Configuration
+
+All config files live in `~/.remctl/`:
+
+| File | Purpose |
+|------|---------|
+| `identity.key` | Private key (keep secure) |
+| `identity.pub` | Public key |
+| `known_nodes.json` | Paired nodes (ctl side) |
+| `known_controllers.json` | Trusted controllers (node side) |
+| `node_config.json` | Node settings (bind address, port, tiers) |
+| `audit.log` | Command audit log |
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows | First-class |
+| Linux | Second-class (best-effort) |
+| macOS | Not yet implemented |
+
+## Publishing to PyPI
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+> The user must configure `~/.pypirc` or set `TWINE_USERNAME`/`TWINE_PASSWORD`
+> environment variables before running `twine upload`. No credentials are
+> included in this repository.

remctl-0.1.0/README.md

@@ -0,0 +1,137 @@
+# remctl
+
+**Secure, LAN-based remote PC control and administration.**
+
+`remctl` lets you control machines on your local network from the command line —
+lock, shutdown, execute shell commands with streaming output, transfer files,
+take screenshots, and check system status. All communication is authenticated
+using Ed25519 keys and encrypted with AES-256-GCM.
+
+> ⚠️ **Intended for your own trusted LAN devices only.** `remctl` is not designed
+> for Internet-facing use. Do not expose it via port forwarding or NAT.
+
+## Installation
+
+```bash
+pip install remctl
+```
+
+### From source
+
+```bash
+# TODO: user adds PyPI API token via env var / twine config before publishing
+git clone <repo-url>
+cd remctl
+pip install -e ".[dev]"
+```
+
+## Quick Start: Pairing Walkthrough
+
+`remctl` requires two-way trust: both the node and the controller must explicitly
+authorize each other.
+
+### On the target machine (the node)
+
+```bash
+# Show the node's fingerprint
+remctl node pair --show
+
+# Start the agent (background via service is recommended)
+remctl node start
+```
+
+### On the controlling machine
+
+```bash
+# Discover nodes on the LAN
+remctl ctl discover
+
+# Pair with a node (verify the fingerprint before confirming)
+remctl ctl pair <node-ip>
+
+# Show your own fingerprint for the node to trust you
+remctl ctl pair-show
+```
+
+### Back on the node (trust the controller)
+
+```bash
+# Trust the controller's public key (copy from the controller's output)
+remctl node trust-controller /path/to/controller_identity.pub
+```
+
+### Send commands
+
+```bash
+remctl ctl <target> status
+remctl ctl <target> lock
+remctl ctl <target> exec "whoami"
+remctl ctl <target> screenshot -o screenshot.png
+remctl ctl <target> push ./file.txt /remote/path/file.txt
+remctl ctl <target> pull /remote/log.log ./log.log
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `remctl node start` | Start the node agent in foreground |
+| `remctl node install-service` | Install as OS service |
+| `remctl ctl discover` | Discover nodes on LAN |
+| `remctl ctl pair <target>` | Pair with a node |
+| `remctl ctl <target> lock` | Lock the remote workstation |
+| `remctl ctl <target> shutdown --delay 60` | Shutdown with optional delay |
+| `remctl ctl <target> restart` | Restart |
+| `remctl ctl <target> sleep` | Sleep/Suspend |
+| `remctl ctl <target> logout` | Log out current user |
+| `remctl ctl <target> closefocused` | Close active window |
+| `remctl ctl <target> exec <command>` | Execute shell command (streamed) |
+| `remctl ctl <target> status` | Show system status (CPU/mem/disk/uptime) |
+| `remctl ctl <target> screenshot -o out.png` | Capture screenshot |
+| `remctl ctl <target> push <local> <remote>` | Push file to node |
+| `remctl ctl <target> pull <remote> <local>` | Pull file from node |
+| `remctl ctl <target> cancel` | Cancel pending shutdown/restart |
+
+## Security Model (Summary)
+
+- **Identity:** Ed25519 keypairs generated on first run.
+- **Authentication:** Two-way explicit pairing — both sides must trust each other.
+- **Encryption:** X25519 ECDH key exchange → AES-256-GCM, with forward secrecy.
+- **Replay protection:** Per-message sequence numbers + 30-second timestamp window.
+- **Permission tiers:** `observe` (status/screenshot), `standard` (commands +
+  files), `full` (includes `exec`). Default: `standard`.
+- **Audit log:** All commands logged unredacted at `~/.remctl/audit.log`.
+
+See [docs/SECURITY.md](docs/SECURITY.md) for the full threat model.
+
+## Configuration
+
+All config files live in `~/.remctl/`:
+
+| File | Purpose |
+|------|---------|
+| `identity.key` | Private key (keep secure) |
+| `identity.pub` | Public key |
+| `known_nodes.json` | Paired nodes (ctl side) |
+| `known_controllers.json` | Trusted controllers (node side) |
+| `node_config.json` | Node settings (bind address, port, tiers) |
+| `audit.log` | Command audit log |
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Windows | First-class |
+| Linux | Second-class (best-effort) |
+| macOS | Not yet implemented |
+
+## Publishing to PyPI
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+> The user must configure `~/.pypirc` or set `TWINE_USERNAME`/`TWINE_PASSWORD`
+> environment variables before running `twine upload`. No credentials are
+> included in this repository.

remctl-0.1.0/docs/SECURITY.md

@@ -0,0 +1,146 @@
+# Security Model
+
+## Overview
+
+`remctl` implements a defense-in-depth security model for LAN-based remote PC
+administration. Every communication channel is authenticated, encrypted, and
+protected against replay attacks.
+
+## Identity
+
+- Each `remctl` instance (both node and controller) generates an Ed25519 keypair
+  on first run, stored in `~/.remctl/identity.key` (private key) and
+  `~/.remctl/identity.pub` (public key).
+- A node or controller's **identity** is the SHA-256 fingerprint of its Ed25519
+  public key, displayed as a colon-separated hex string (SSH-fingerprint style).
+- Private keys are stored with restrictive permissions (`chmod 600` on Linux,
+  equivalent ACL restriction on Windows).
+
+## Pairing (Trust-On-First-Use)
+
+- **Two-way trust is required.** Both the node and the controller must explicitly
+  trust each other. There is no auto-trust mechanism.
+- When a controller pairs with a node (`remctl ctl pair <target>`):
+  1. The controller opens a direct TCP connection to the node.
+  2. The node sends its public key over this direct connection (never over
+     broadcast).
+  3. The controller computes the fingerprint and displays it for visual
+     confirmation (mimicking SSH's `known_hosts` behavior).
+  4. Only after the user types `yes` is the node's public key saved.
+- For the node to trust the controller, the user must run
+  `remctl node trust-controller <pubkey-file>` on the node, adding the
+  controller's public key to the allowlist.
+
+## Wire Protocol Security
+
+### Session Key Exchange (Forward Secrecy)
+
+1. Each connection performs an X25519 ECDH handshake.
+2. Both sides generate ephemeral X25519 keypairs per connection.
+3. Each handshake message is signed with the long-term Ed25519 identity key.
+4. The shared secret is derived via HKDF-SHA256, incorporating:
+   - The X25519 ECDH shared secret
+   - The peer's long-term public key
+5. This provides **forward secrecy**: compromising the long-term keys does not
+   compromise past session keys.
+
+### Transport Encryption
+
+- All post-handshake traffic is encrypted with **AES-256-GCM** (authenticated
+  encryption).
+- Frame format: `[4-byte big-endian length][12-byte nonce][ciphertext]`
+- Each frame uses a random nonce (never reused).
+
+### Replay Protection
+
+- Every command message includes a **monotonically increasing sequence number**
+  and a **timestamp**.
+- The receiver rejects:
+  - Messages with a timestamp more than **30 seconds** from the current time.
+  - Messages with a sequence number that has already been processed.
+- Sequence numbers are tracked per-connection.
+
+### Network Binding
+
+- By default, the node daemon binds to `0.0.0.0` (all interfaces). This is
+  suitable for trusted LAN environments.
+- Users can restrict binding to a specific interface via the `--bind` option
+  or `node_config.json`.
+- **Port forwarding or WAN exposure is explicitly out of scope.** `remctl` is
+  not designed or tested for Internet-facing use, and the documentation does
+  not include instructions for exposing it beyond the LAN.
+
+## Authorization
+
+### Controller Allowlist
+
+- The node maintains an allowlist of trusted controller public keys in
+  `~/.remctl/known_controllers.json`.
+- Any connection whose identity is not in this list is rejected and logged.
+
+### Permission Tiers
+
+Each trusted controller is assigned a permission tier (configured in
+`~/.remctl/node_config.json`):
+
+| Tier       | Permissions                                       |
+|------------|---------------------------------------------------|
+| `observe`  | `status`, `screenshot` only                       |
+| `standard` | All simple commands + file push/pull, no `exec`   |
+| `full`     | Everything, including arbitrary shell `exec`      |
+
+- The default tier for newly-paired controllers is **`standard`**, not `full`.
+- Upgrading to `full` requires explicit configuration by the node operator.
+
+## Rate Limiting / Lockout
+
+- Failed handshake/auth attempts are tracked per source IP address.
+- After **5 failures within 60 seconds**, the source IP is temporarily banned
+  for **5 minutes**.
+- Rate limiting is in-memory only (not persistent across restarts).
+
+## Audit Logging
+
+- Every received command is recorded in `~/.remctl/audit.log` as a JSON line.
+- Each log entry includes: timestamp, source fingerprint, command name,
+  arguments (unredacted), outcome (accepted/rejected/error), and exit code
+  where applicable.
+- Log rotation is size-based (default: 10MB per file, keep 5 backups) using
+  `RotatingFileHandler`.
+
+## Threat Model
+
+### What `remctl` protects against:
+
+| Threat | Mitigation |
+|--------|-----------|
+| Unauthenticated LAN actor sending commands | Ed25519 identity verification; controller allowlist |
+| Passive eavesdropping on the wire | AES-256-GCM encryption of all traffic |
+| Active man-in-the-middle | X25519 ECDH signed with long-term identity keys |
+| Replay of captured commands | Per-message sequence numbers + timestamp window |
+| Brute-force connection attempts | Per-IP rate limiting with temporary ban |
+| Unauthorized `exec` on a partially trusted controller | Permission tiers (default `standard`) |
+| Controller key compromise (past sessions) | Forward secrecy via ephemeral X25519 keys |
+
+### What `remctl` does NOT protect against:
+
+| Non-goal | Reason |
+|----------|--------|
+| A fully compromised endpoint | Any machine where the node daemon runs with root/admin access can be controlled; if an attacker has root/Administrator, all bets are off |
+| Physical access to the machine | Physical access enables bypassing all software security measures |
+| A compromised controller machine | If a trusted controller machine is compromised, the attacker inherits that controller's permissions |
+| WAN/Internet threats | `remctl` is explicitly designed for LAN use only |
+| DoS attacks | While rate limiting mitigates casual DoS, a determined LAN attacker can still flood the network |
+| Malicious `exec` payloads | `exec` runs arbitrary shell commands; the node operator should only grant `full` tier to highly trusted controllers |
+
+## Security Recommendations for Users
+
+1. **Keep your identity keys safe.** The `~/.remctl/identity.key` file grants
+   full access to all nodes that trust it. Back it up securely, or generate a
+   new keypair if compromised.
+2. **Use the `observe` tier** for controllers that only need to check status.
+3. **Grant `full` tier sparingly** — only to controllers that genuinely need
+   shell access.
+4. **Review the audit log** periodically at `~/.remctl/audit.log`.
+5. **Bind to a specific interface** if your machine has multiple network
+   interfaces and you only want `remctl` accessible on one of them.

remctl-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remctl"
+version = "0.1.0"
+description = "Secure LAN-based remote PC control and administration"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "remctl contributors"},
+]
+keywords = ["remote-control", "lan", "administration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+]
+
+dependencies = [
+    "typer>=0.12",
+    "pydantic>=2",
+    "cryptography>=42",
+    "zeroconf>=0.132",
+    "psutil>=5.9",
+    "mss>=9.0",
+    "rich>=13",
+    "pywin32>=306; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]
+
+[project.scripts]
+remctl = "remctl.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/remctl"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_generics = false
+disallow_subclassing_any = false
+exclude = ["tests/"]

remctl-0.1.0/src/remctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

remctl-0.1.0/src/remctl/__main__.py

@@ -0,0 +1,4 @@
+from remctl.cli import app
+
+if __name__ == "__main__":
+    app()

remctl-0.1.0/src/remctl/audit.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import logging
+from logging.handlers import RotatingFileHandler
+
+from remctl.crypto import KEY_DIR
+
+AUDIT_LOG = KEY_DIR / "audit.log"
+
+_logger: logging.Logger | None = None
+
+
+def get_logger(max_bytes: int = 10 * 1024 * 1024, backup_count: int = 5) -> logging.Logger:
+    global _logger
+    if _logger is not None:
+        return _logger
+    KEY_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    _logger = logging.getLogger("remctl.audit")
+    _logger.setLevel(logging.INFO)
+    handler = RotatingFileHandler(
+        str(AUDIT_LOG),
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _logger.addHandler(handler)
+    _logger.propagate = False
+    return _logger
+
+
+def log_command(
+    source_fingerprint: str,
+    command: str,
+    args: dict,
+    outcome: str,
+    detail: str | None = None,
+) -> None:
+    logger = get_logger()
+    record = {
+        "timestamp": __import__("time").time(),
+        "source": source_fingerprint,
+        "command": command,
+        "args": args,
+        "outcome": outcome,
+    }
+    if detail:
+        record["detail"] = detail
+    logger.info(json.dumps(record, default=str))