logtap 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

logtap/core/validation.py

@@ -3,8 +3,140 @@ Input validation functions for logtap.
 
 These functions validate user input to prevent security issues
 like path traversal attacks and DoS via overly large inputs.
+
+Path Traversal Prevention Model
+===============================
+1. Input validation: reject NUL bytes, control chars, path separators, ".."
+2. Join filename to base directory
+3. Resolve to canonical absolute path (follows symlinks)
+4. Containment check: commonpath([base, resolved]) == base
+5. File type check: must be regular file (not dir, device, etc.)
+
+This prevents:
+- Directory traversal (../)
+- Absolute path injection (/etc/passwd)
+- Symlink escape attacks
+- Null byte injection
+- Path prefix collisions (/var/log vs /var/logs)
 """
 
+import os
+import stat
+from typing import Optional, Tuple
+
+
+def resolve_safe_path(base_dir: str, filename: str, require_exists: bool = False) -> Optional[str]:
+    """
+    Safely resolve a filename within a base directory.
+
+    Security guarantees:
+    - Resolved path is always within base_dir (symlink-safe)
+    - No path traversal via "..", separators, or absolute paths
+    - No NUL bytes or control characters
+    - Containment verified via os.path.commonpath
+
+    Args:
+        base_dir: The base directory that files must be within.
+        filename: The user-provided filename (single component, no path separators).
+        require_exists: If True, also verify the file exists and is a regular file.
+
+    Returns:
+        The resolved filepath if safe, None if validation fails.
+    """
+    # Reject empty filenames
+    if not filename:
+        return None
+
+    # Reject NUL bytes (can truncate paths in some contexts)
+    if "\x00" in filename:
+        return None
+
+    # Reject control characters (0x00-0x1F, 0x7F)
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in filename):
+        return None
+
+    # Reject special directory entries
+    # Note: ".." substring check removed - it over-blocks valid names like "my..log"
+    # Traversal requires separators which we reject below; containment check is authoritative
+    if filename in {".", ".."}:
+        return None
+
+    # Reject path separators - filename must be a single component
+    if "/" in filename or "\\" in filename:
+        return None
+
+    # Reject absolute paths (Unix and Windows)
+    if filename.startswith("/") or filename.startswith("\\"):
+        return None
+    # Windows drive letters (C:, D:, etc.)
+    if len(filename) >= 2 and filename[1] == ":":
+        return None
+
+    # Resolve base directory to canonical absolute form
+    base_resolved = os.path.realpath(base_dir)
+
+    # Join and resolve to canonical absolute path (follows symlinks)
+    filepath = os.path.join(base_resolved, filename)
+    filepath_resolved = os.path.realpath(filepath)
+
+    # Containment check using commonpath
+    # This is the authoritative check - handles prefix collisions correctly
+    # e.g., base=/var/log, candidate=/var/logs/evil will fail
+    try:
+        common = os.path.commonpath([base_resolved, filepath_resolved])
+        if common != base_resolved:
+            return None
+    except ValueError:
+        # Paths on different drives (Windows) or other path issues
+        return None
+
+    # Optional: verify file exists and is a regular file
+    if require_exists:
+        try:
+            file_stat = os.stat(filepath_resolved)
+            if not stat.S_ISREG(file_stat.st_mode):
+                return None
+        except OSError:
+            return None
+
+    return filepath_resolved
+
+
+def resolve_safe_path_checked(base_dir: str, filename: str) -> Tuple[Optional[str], str]:
+    """
+    Resolve a safe path and return detailed error reason if validation fails.
+
+    Returns:
+        Tuple of (resolved_path, error_reason). If path is valid, error_reason is empty.
+    """
+    if not filename:
+        return None, "empty filename"
+    if "\x00" in filename:
+        return None, "filename contains NUL byte"
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in filename):
+        return None, "filename contains control character"
+    if filename in {".", ".."}:
+        return None, "filename is special directory entry"
+    if "/" in filename or "\\" in filename:
+        return None, "filename contains path separator"
+    if filename.startswith("/") or filename.startswith("\\"):
+        return None, "filename is absolute path"
+    if len(filename) >= 2 and filename[1] == ":":
+        return None, "filename contains Windows drive letter"
+
+    base_resolved = os.path.realpath(base_dir)
+    filepath = os.path.join(base_resolved, filename)
+    filepath_resolved = os.path.realpath(filepath)
+
+    try:
+        common = os.path.commonpath([base_resolved, filepath_resolved])
+        if common != base_resolved:
+            return None, "resolved path escapes base directory"
+    except ValueError as e:
+        return None, f"path resolution error: {e}"
+
+    return filepath_resolved, ""
+
 
 def is_filename_valid(filename: str) -> bool:
     """

logtap-0.4.1.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: logtap
+Version: 0.4.1
+Summary: A CLI-first log access tool for Unix systems. Remote log file access without SSH.
+Project-URL: Homepage, https://github.com/cainky/logtap
+Project-URL: Repository, https://github.com/cainky/logtap
+Author-email: cainky <kylecain.me@gmail.com>
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: cli,devops,logs,monitoring,sysadmin
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.2.1
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: google-re2>=1.1
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# logtap
+
+[![PyPI version](https://badge.fury.io/py/logtap.svg)](https://badge.fury.io/py/logtap)
+[![Tests](https://github.com/cainky/logtap/actions/workflows/tests.yml/badge.svg)](https://github.com/cainky/logtap/actions/workflows/tests.yml)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**`tail -f` for GPU clouds. Survives disconnects, aggregates multi-node.**
+
+> Stop losing your training logs when SSH drops. Watch from anywhere, reconnect seamlessly.
+
+## The Problem
+
+You're training a model on RunPod, Vast.ai, or Lambda. You SSH in, start training, and:
+
+- Your terminal disconnects after an hour
+- You lose visibility into what's happening
+- You resort to tmux hacks just to keep logs alive
+- Multi-node training means logs scattered across machines
+
+## The Solution
+
+```bash
+# On your GPU instance
+pip install logtap
+logtap collect &
+python train.py 2>&1 | logtap ingest run1
+
+# From your laptop (or phone)
+logtap tail run1 --follow
+
+# Connection drops... reconnects automatically
+# "reconnected (missed 0 lines)"
+```
+
+## Quickstart: RunPod / Vast.ai
+
+On the GPU instance:
+
+```bash
+pip install logtap
+export LOGTAP_API_KEY=secret
+logtap collect --port 8000
+```
+
+Start training and stream logs:
+
+```bash
+python train.py 2>&1 | logtap ingest run1 --tag node=$(hostname)
+```
+
+From your laptop:
+
+```bash
+export LOGTAP_SERVER=http://<gpu-ip>:8000
+export LOGTAP_API_KEY=secret
+logtap tail run1 --follow
+```
+
+Disconnect, close your terminal, or switch networks.
+Re-run `logtap tail` anytime to resume where you left off.
+
+Works the same on RunPod, Vast.ai, Lambda, and any ephemeral GPU cloud.
+
+## Features
+
+- **Survives Disconnects** - Resume from where you left off with cursor-based streaming
+- **Pipe-Friendly** - Works with any training script via stdin
+- **Multi-Node Ready** - Tag runs with `node=gpu1` and filter/aggregate
+- **Zero Infra** - No database, no complex setup, just pip install
+- **Lightweight** - <50MB memory, append-only file storage
+
+## Why not tmux / mosh?
+
+tmux and mosh help keep SSH sessions alive.
+logtap solves a different problem.
+
+- SSH can still drop (web terminals, proxies, idle timeouts)
+- tmux doesn't aggregate logs across machines
+- tmux can't be viewed from another device without SSH
+- tmux sessions die when ephemeral instances stop
+
+logtap streams logs over HTTP:
+- survives disconnects
+- resumes without gaps
+- aggregates multi-node training via tags
+- works from anywhere (no SSH required)
+
+You can still use tmux. You just don't have to rely on it.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install logtap
+```
+
+### 2. Start Collector (on GPU instance)
+
+```bash
+logtap collect --api-key secret
+```
+
+### 3. Pipe Your Training Logs
+
+```bash
+python train.py 2>&1 | logtap ingest run1 --api-key secret
+```
+
+### 4. Tail From Anywhere
+
+```bash
+export LOGTAP_SERVER=http://your-gpu-ip:8000
+export LOGTAP_API_KEY=secret
+
+logtap tail run1 --follow
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `logtap collect` | Start collector server (accepts ingested runs) |
+| `logtap ingest <run>` | Pipe stdin to collector |
+| `logtap tail <run>` | Tail a run with `--follow` for streaming |
+| `logtap runs` | List active runs |
+| `logtap doctor` | Check server connectivity and diagnose issues |
+
+### Ingest Options
+
+```bash
+# Auto-generate run name
+python train.py | logtap ingest
+
+# Add tags for multi-node
+python train.py | logtap ingest run1 --tag node=gpu1 --tag rank=0
+
+# Quiet mode (no status messages)
+python train.py | logtap ingest run1 --quiet
+```
+
+### Tail Options
+
+```bash
+# Follow mode (like tail -f)
+logtap tail run1 --follow
+
+# Resume from specific cursor (survives disconnects!)
+logtap tail run1 --follow --since 5000
+
+# Filter by tag
+logtap tail run1 --tag node=gpu1
+
+# Output formats
+logtap tail run1 --output jsonl | jq '.line'
+```
+
+### Collector Options
+
+```bash
+logtap collect \
+  --port 8000 \
+  --api-key secret \
+  --data-dir ~/.logtap/runs \
+  --max-disk-mb 5000 \
+  --retention-hours 72
+```
+
+## Multi-Node Training
+
+Tag each node and aggregate:
+
+```bash
+# Node 1
+python train.py | logtap ingest run1 --tag node=gpu1
+
+# Node 2
+python train.py | logtap ingest run1 --tag node=gpu2
+
+# Watch all nodes
+logtap tail run1 --follow
+
+# Watch specific node
+logtap tail run1 --follow --tag node=gpu1
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOGTAP_SERVER` | `http://localhost:8000` | Collector URL |
+| `LOGTAP_API_KEY` | - | API key for auth |
+
+Set these to avoid typing `--server` and `--api-key` every time.
+
+## How It Works
+
+1. **Collector** writes logs to append-only files with cursor tracking
+2. **Ingest** streams stdin over HTTP chunked POST
+3. **Tail** uses SSE (Server-Sent Events) with resume support
+4. **Reconnect** passes `?since=<cursor>` to continue without gaps
+
+No database. No message queue. Just files and HTTP.
+
+## API Endpoints
+
+For scripting or custom integrations:
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /runs/{id}/ingest` | Stream lines (chunked POST) |
+| `GET /runs/{id}/stream` | SSE stream with `?since=&follow=` |
+| `GET /runs/{id}/query` | Query with `?from=&to=&search=` |
+| `GET /runs` | List runs |
+| `GET /health` | Health check with capabilities |
+
+## Legacy: Static File Mode
+
+logtap also works as a simple remote log viewer (the original use case):
+
+```bash
+# On server with log files
+logtap serve --log-dir /var/log
+
+# From client
+logtap tail syslog --server http://myserver:8000 --follow
+logtap query auth.log --regex "Failed password"
+```
+
+## Security
+
+- **API Key Auth** - Optional but recommended for production
+- **Path Traversal Protection** - Comprehensive defense with symlink-safe containment checks (see [SECURITY.md](SECURITY.md))
+- **ReDoS Protection** - Uses google-re2 for guaranteed linear-time regex matching
+- **Read-Only by Default** - Collector only writes to its data directory
+- **Input Validation** - Rejects control characters, NUL bytes, and malicious path patterns
+
+## Development
+
+```bash
+git clone https://github.com/cainky/logtap.git
+cd logtap
+
+# Install with uv
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Run collector in dev mode
+uv run logtap collect --reload
+```
+
+## License
+
+GPL v3 - see [LICENSE](LICENSE)
+
+## Author
+
+Kyle Cain - [@cainky](https://github.com/cainky)

{logtap-0.4.0.dist-info → logtap-0.4.1.dist-info}/RECORD

@@ -6,24 +6,25 @@ logtap/api/dependencies.py,sha256=1cx1qrp0O6v1fHXA2JdEhC8P4caG2oUSCfMk2-8zmGs,16
 logtap/api/routes/__init__.py,sha256=XYvFyTP4zKywRZH0v97k0EZCYgxdL2PSUaNet20znPE,29
 logtap/api/routes/files.py,sha256=bqZYrX6jrF5-7GzBpUIXXoPVdxUwm6o0LTcJBLtaJUE,991
 logtap/api/routes/health.py,sha256=s117Hr1E8OcBGPOWq2WwHLZSq35hS7wmLPk6BYq3dq4,1112
-logtap/api/routes/logs.py,sha256=XpRAd4fZmVyylz6bHCHm4y0Y2GofSquH6j5WJP3Jyao,8467
-logtap/api/routes/parsed.py,sha256=XVvkKBE_hQvfJyrDBBPR_PpVxvof-y4B77xKe9Rr0Qk,3367
-logtap/api/routes/runs.py,sha256=Fxb6joJ5FPXPCKTfgD41i0H4UQ4U4fmFxk08SFUxt_s,11355
+logtap/api/routes/logs.py,sha256=J_Sp9-Mx2g-tVdpVJMzMz1ytymtCCMJvDJ74uLeiKw0,8294
+logtap/api/routes/parsed.py,sha256=dXIKy0JMxlvoHAbCCk4zhagHUPaWclaUBPcHXG2ew1I,3442
+logtap/api/routes/runs.py,sha256=njyPZ90eXeAvnDWVq-q3x0slDCjUJ8FotOnl1muCKgI,10571
 logtap/cli/__init__.py,sha256=U4zaUJ1rm0qHXqeArpzC45S5N-5SBdd8K6foe513msk,31
-logtap/cli/main.py,sha256=jfzN-S6dn3bg6yuQ3ovJtaLYb7LnCDg_cl7vqRWTBxw,1230
+logtap/cli/main.py,sha256=7XSeZrvCfiCcMA_sJLIIaT21ORAsYKiD_gKCSLxGmbc,1267
 logtap/cli/commands/__init__.py,sha256=U4zaUJ1rm0qHXqeArpzC45S5N-5SBdd8K6foe513msk,31
 logtap/cli/commands/collect.py,sha256=8x6LyMrzI79wYtfLZcbQdgpy5nxPZuQOEillE9IfwwE,3002
+logtap/cli/commands/doctor.py,sha256=fVL6ZhD52zQBqGQRwi0J_m3MaN-0SbwhxM8UZC4nG-Y,4218
 logtap/cli/commands/files.py,sha256=WFr8kA0SdgQHz3ZyONTaljxHMcD-nQlndp3UIOwZATc,2455
 logtap/cli/commands/ingest.py,sha256=JaItHHYV3fBmPkseYpubyHryNbuEuxyjRBk-EiiEwyU,4054
 logtap/cli/commands/query.py,sha256=uD9nH5E-7EqJryLf3hHkDbJSQo4kWFGmzzHgTfAKFwk,3418
 logtap/cli/commands/runs.py,sha256=Dweswku19Dj2KOFhT0kaega9KSKmUrvya3eLn0-5lXo,3632
 logtap/cli/commands/serve.py,sha256=9OvfII21q6cel3zZfSsAsiERKwKFt0ZFTXmUd2Psthg,1910
-logtap/cli/commands/tail.py,sha256=w7P3_1o0OtVtos3kV8w4goShWXzzUDo4ekSye3VSpGo,10015
+logtap/cli/commands/tail.py,sha256=mOYGwXaXeM_PHI27BAm61CR25YAh9dpLOlq8oy0ciLM,10427
 logtap/core/__init__.py,sha256=tsoL0XuDrPd5xHEu975WqFHoA7EQgloxrum7CjsWHuk,450
 logtap/core/reader.py,sha256=BuBrEAbS2naCBTtuBNc0Un6thbekzabaHTBzYE1SwKg,5277
-logtap/core/runs.py,sha256=t4JnQvZTi-YB2II8maBIcaJD77gp_CjKVcTGYwHhuU8,13488
+logtap/core/runs.py,sha256=lYOWAWp6RrcaMLkWxqhD0MC5alQe7rv07GtEazL5WWE,14956
 logtap/core/search.py,sha256=rtq8WP96RYUvRkX_R5x_mdD_dw1syDuNkHx3uP_diOg,4574
-logtap/core/validation.py,sha256=Nk86jHqEfI4H96fk-1rjbC5sBwfzls43hyOhnRV6rxI,1359
+logtap/core/validation.py,sha256=kRKRuhSaORslgatIQ2nW3ufDOn0mp_mB38CguhizRBY,6071
 logtap/core/parsers/__init__.py,sha256=5f3hFxf_DgNScRDchRT8ocFVgi7Md4xuMN-ShvlssBo,575
 logtap/core/parsers/apache.py,sha256=JjuQ4v-b7HJvTCcjbOMgv5_dSdiNVPX_EUyplc3f5Qw,5332
 logtap/core/parsers/auto.py,sha256=OLLuX7XIxS0Upnv9FQ-_B0sGAyZmfNxjnMDGdZtUIO4,3565
@@ -34,8 +35,8 @@ logtap/core/parsers/syslog.py,sha256=gBNQ39QXsigOpfnq3cEdmvFa8NLp_wmiSMDlTt0SIbs
 logtap/models/__init__.py,sha256=tce3Q0QjPhnlAYG8IcwxPedyh1ibBlKIF3CjXe5wwgo,280
 logtap/models/config.py,sha256=8x6OR_y2ZB8SSoQWQGwDB7DXH30UyMNXUcRWOctjUn8,927
 logtap/models/responses.py,sha256=xKdKdS85soxMYGNad3WfF0pOG0Pb5Z7XwVrwK-TCnHs,4084
-logtap-0.4.0.dist-info/METADATA,sha256=_Y9ZSz2BwIF2SOOHYPQZ8YrLIxmpB31tOaabDty1BDY,7466
-logtap-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-logtap-0.4.0.dist-info/entry_points.txt,sha256=tuAit8kt97yjtACQKvN35wWozp4KhSju_gfDhSS1IrM,47
-logtap-0.4.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-logtap-0.4.0.dist-info/RECORD,,
+logtap-0.4.1.dist-info/METADATA,sha256=Mz7i6uIVOv9mHtQ2oMgKSOVH5oVtpjO7s3N9u7ZSUP8,8203
+logtap-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+logtap-0.4.1.dist-info/entry_points.txt,sha256=tuAit8kt97yjtACQKvN35wWozp4KhSju_gfDhSS1IrM,47
+logtap-0.4.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+logtap-0.4.1.dist-info/RECORD,,