pinhaul 0.4.0__tar.gz

pinhaul-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Env & secrets
+.env
+.env.local
+
+# Node
+node_modules/
+
+# Django
+**/static_root/
+**/media/
+db.sqlite3
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+uv.lock.disabled
+
+# OS
+.DS_Store
+
+# real deployment secrets
+deploy/server.env

pinhaul-0.4.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: pinhaul
+Version: 0.4.0
+Summary: Runtime dependency inventory for Pinhaul: one import, your project reports what it actually runs.
+Project-URL: Homepage, https://pinhaul.io
+Author: Reknown
+License: Proprietary
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
+Provides-Extra: scan
+Requires-Dist: bandit>=1.7; extra == 'scan'
+Description-Content-Type: text/markdown
+
+# pinhaul (Python SDK + CLI)
+
+Runtime dependency security for vibe coders: one import (or one `docker run` with the
+[agent](../agent)) and Pinhaul knows exactly what your project *actually* runs, scans it,
+and tells you what matters in plain language.
+
+## Install
+
+```bash
+pip install pinhaul            # or: pip install "pinhaul[dotenv]" for .env loading
+```
+
+## Quickstart
+
+```bash
+# 1. Get an API key
+pinhaul register --email you@example.com
+
+# 2. Add the key to your project
+echo 'PINHAUL_API_KEY=<your key>' >> .env
+
+# 3. One line in your app's entrypoint
+```
+
+```python
+from pinhaul import Pinhaul
+Pinhaul(project_name="my-app", environment="prod", metadata={"team": "core"})
+```
+
+That's it. On startup, Pinhaul captures Python builtins (version, implementation,
+platform, script name, hostname) and the package versions **actually loaded in your
+process** — runtime truth, not a requirements.txt guess — and reports them to your
+Pinhaul cloud in a background thread that can never crash or block your app.
+
+## Snapshot caching (don't re-send what didn't change)
+
+The SDK fingerprints the full payload (python facts + metadata + loaded inventory,
+sorted so import order doesn't matter) and caches it under
+`~/.cache/pinhaul/snapshots/`. An unchanged environment within the TTL sends
+**nothing**; any change to python version, metadata, or a package version ships
+immediately. After the TTL (default 6h) the next start re-sends once as a liveness
+heartbeat — the server deduplicates that without creating rows.
+
+| Env var | Default | Effect |
+|---|---|---|
+| `PINHAUL_REPORT_TTL` | `21600` (6h) | Seconds an unchanged fingerprint is suppressed. `0` = always send |
+| `PINHAUL_NO_CACHE` | unset | Set to disable client caching entirely |
+
+`Pinhaul(..., force=True)` bypasses the cache for one explicit send. Server-side
+dedup (same fingerprint within its window) protects against cache misses, CI, and
+second machines regardless of client settings. Check what happened via
+`ds.last_result`: `sent` / `deduplicated` / `skipped` / `disabled`.
+
+## What it sends (and never sends)
+
+✅ python version/implementation, platform, script *basename*, hostname, loaded package
+names+versions, the metadata you explicitly pass.
+
+❌ environment variables, file paths, source code, secrets, anything else.
+
+Set `PINHAUL_DISABLE=1` to no-op (e.g. in CI). Set `PINHAUL_DEBUG=1` to print
+diagnostics to stderr on failure.
+
+## Local scan engines (feature-gated)
+
+```bash
+pinhaul scan --code                     # bandit SAST over your python code
+pinhaul scan --secrets                  # gitleaks over your git history (full history, redacted)
+pinhaul scan --code --secrets --project my-app
+```
+
+- `--code` needs bandit: `pip install "pinhaul[scan]"`
+- `--secrets` needs the [gitleaks](https://github.com/zricethezav/gitleaks) binary on your PATH
+- Engines are enabled per plan server-side; a disabled engine prints 🔒 instead of running
+- **Privacy:** code snippets are never sent (bandit findings carry test id + file:line only);
+  gitleaks runs with `--redact` and secret values are stripped client-side *and* server-side
+
+## CLI
+
+```bash
+pinhaul doctor [--docker]             # diagnose setup: API, key, cache, socket
+pinhaul status                        # account + project health
+pinhaul report [--project my-app]     # severity summary + dependency intel + AI insight
+pinhaul findings [--severity critical,high] [--source trivy,osv,bandit,gitleaks,depintel]
+pinhaul mute 7643 [7644 ...]          # hide accepted-risk findings from reports/alerts
+pinhaul unmute 7643
+pinhaul sbom --project my-app --out sbom.json   # CycloneDX 1.5 from runtime inventory
+pinhaul analyze [--project my-app]    # queue an AI triage run
+pinhaul init --name my-app            # print the integration snippet
+```
+
+API endpoint defaults to `http://127.0.0.1:8000` for local development; override with
+`PINHAUL_API_URL` or `--api-url`.
+
+## Development
+
+```bash
+cd sdk && python3 -m venv .venv && . .venv/bin/activate
+pip install -e . && python -m unittest discover tests -v
+```

pinhaul-0.4.0/README.md

@@ -0,0 +1,100 @@
+# pinhaul (Python SDK + CLI)
+
+Runtime dependency security for vibe coders: one import (or one `docker run` with the
+[agent](../agent)) and Pinhaul knows exactly what your project *actually* runs, scans it,
+and tells you what matters in plain language.
+
+## Install
+
+```bash
+pip install pinhaul            # or: pip install "pinhaul[dotenv]" for .env loading
+```
+
+## Quickstart
+
+```bash
+# 1. Get an API key
+pinhaul register --email you@example.com
+
+# 2. Add the key to your project
+echo 'PINHAUL_API_KEY=<your key>' >> .env
+
+# 3. One line in your app's entrypoint
+```
+
+```python
+from pinhaul import Pinhaul
+Pinhaul(project_name="my-app", environment="prod", metadata={"team": "core"})
+```
+
+That's it. On startup, Pinhaul captures Python builtins (version, implementation,
+platform, script name, hostname) and the package versions **actually loaded in your
+process** — runtime truth, not a requirements.txt guess — and reports them to your
+Pinhaul cloud in a background thread that can never crash or block your app.
+
+## Snapshot caching (don't re-send what didn't change)
+
+The SDK fingerprints the full payload (python facts + metadata + loaded inventory,
+sorted so import order doesn't matter) and caches it under
+`~/.cache/pinhaul/snapshots/`. An unchanged environment within the TTL sends
+**nothing**; any change to python version, metadata, or a package version ships
+immediately. After the TTL (default 6h) the next start re-sends once as a liveness
+heartbeat — the server deduplicates that without creating rows.
+
+| Env var | Default | Effect |
+|---|---|---|
+| `PINHAUL_REPORT_TTL` | `21600` (6h) | Seconds an unchanged fingerprint is suppressed. `0` = always send |
+| `PINHAUL_NO_CACHE` | unset | Set to disable client caching entirely |
+
+`Pinhaul(..., force=True)` bypasses the cache for one explicit send. Server-side
+dedup (same fingerprint within its window) protects against cache misses, CI, and
+second machines regardless of client settings. Check what happened via
+`ds.last_result`: `sent` / `deduplicated` / `skipped` / `disabled`.
+
+## What it sends (and never sends)
+
+✅ python version/implementation, platform, script *basename*, hostname, loaded package
+names+versions, the metadata you explicitly pass.
+
+❌ environment variables, file paths, source code, secrets, anything else.
+
+Set `PINHAUL_DISABLE=1` to no-op (e.g. in CI). Set `PINHAUL_DEBUG=1` to print
+diagnostics to stderr on failure.
+
+## Local scan engines (feature-gated)
+
+```bash
+pinhaul scan --code                     # bandit SAST over your python code
+pinhaul scan --secrets                  # gitleaks over your git history (full history, redacted)
+pinhaul scan --code --secrets --project my-app
+```
+
+- `--code` needs bandit: `pip install "pinhaul[scan]"`
+- `--secrets` needs the [gitleaks](https://github.com/zricethezav/gitleaks) binary on your PATH
+- Engines are enabled per plan server-side; a disabled engine prints 🔒 instead of running
+- **Privacy:** code snippets are never sent (bandit findings carry test id + file:line only);
+  gitleaks runs with `--redact` and secret values are stripped client-side *and* server-side
+
+## CLI
+
+```bash
+pinhaul doctor [--docker]             # diagnose setup: API, key, cache, socket
+pinhaul status                        # account + project health
+pinhaul report [--project my-app]     # severity summary + dependency intel + AI insight
+pinhaul findings [--severity critical,high] [--source trivy,osv,bandit,gitleaks,depintel]
+pinhaul mute 7643 [7644 ...]          # hide accepted-risk findings from reports/alerts
+pinhaul unmute 7643
+pinhaul sbom --project my-app --out sbom.json   # CycloneDX 1.5 from runtime inventory
+pinhaul analyze [--project my-app]    # queue an AI triage run
+pinhaul init --name my-app            # print the integration snippet
+```
+
+API endpoint defaults to `http://127.0.0.1:8000` for local development; override with
+`PINHAUL_API_URL` or `--api-url`.
+
+## Development
+
+```bash
+cd sdk && python3 -m venv .venv && . .venv/bin/activate
+pip install -e . && python -m unittest discover tests -v
+```

pinhaul-0.4.0/pinhaul/__init__.py

@@ -0,0 +1,15 @@
+"""Pinhaul SDK: runtime dependency inventory with a one-line import.
+
+    from pinhaul import Pinhaul
+    Pinhaul(project_name="my-app")  # reads PINHAUL_API_KEY from env/.env
+
+Sends: python version/implementation, platform, script name, hostname, and the
+package versions actually loaded in this process. Never env vars, never file
+paths, never code. Fails silently (PINHAUL_DEBUG=1 to see errors) and can be
+fully disabled with PINHAUL_DISABLE=1.
+"""
+
+from pinhaul.client import Pinhaul
+
+__version__ = "0.4.0"
+__all__ = ["Pinhaul", "__version__"]

pinhaul-0.4.0/pinhaul/cache.py

@@ -0,0 +1,60 @@
+"""Local snapshot cache: skip shipping when the runtime fingerprint is unchanged.
+
+Cache lives under XDG_CACHE_HOME (default ~/.cache)/pinhaul/snapshots, one small
+JSON per (project, api_url). Every operation fails open: a read-only home, a
+corrupt file, or a missing directory must never break the host application.
+"""
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+
+CACHE_VERSION = 1
+
+
+def _cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "pinhaul" / "snapshots"
+
+
+def _cache_path(project_name: str, api_url: str) -> Path:
+    raw = f"{project_name}|{api_url}".encode()
+    digest = hashlib.sha256(raw).hexdigest()[:24]
+    return _cache_dir() / f"{digest}.json"
+
+
+def load(project_name: str, api_url: str) -> dict | None:
+    """Return {"fingerprint": str, "sent_at": epoch_seconds} or None."""
+    try:
+        path = _cache_path(project_name, api_url)
+        if not path.is_file():
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if data.get("version") != CACHE_VERSION:
+            return None
+        if not isinstance(data.get("fingerprint"), str):
+            return None
+        return data
+    except Exception:
+        return None
+
+
+def save(project_name: str, api_url: str, fingerprint: str) -> None:
+    try:
+        path = _cache_path(project_name, api_url)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({"version": CACHE_VERSION, "fingerprint": fingerprint, "sent_at": time.time()}),
+            encoding="utf-8",
+        )
+    except Exception:
+        pass
+
+
+def clear(project_name: str, api_url: str) -> None:
+    try:
+        _cache_path(project_name, api_url).unlink(missing_ok=True)
+    except Exception:
+        pass