# PipDock — Security *Version 0.1 · 2026-07-17* ## 1. Threat model (scoped) PipDock's job is to run package managers against local environments. The realistic risks are: (a) PipDock being tricked into running something other than the intended engine command, (b) users being nudged into damaging their system Python, (c) compromised update delivery of PipDock itself, and (d) PipDock's own dependency supply chain. Malicious *packages* the user chooses to install are out of scope — pip/uv execute setup code by design; PipDock's mitigations are the preview step, snapshots, and the (P1) audit tab, not sandboxing. ## 2. Command execution hygiene - All engine/tool invocations use argv arrays via `tokio::process::Command`; **no shell is ever involved**, so quoting/injection classes are structurally absent. - Package names are validated against the PEP 508 name grammar (`^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$` after normalization) and version specs against PEP 440 before entering argv; anything else is rejected client-side with PD-PKG-002. - **The version half has been true only since 1.4.0.** Names always went through `PkgName`; versions were plain strings, so a dock-bay entry of `2.0 ; python_version<'0'` reached argv as one token pip read as a requirement whose marker is false — a silent no-op install. `pep440` is now the one place that says what a version and a specifier set may look like, and every way text arrives passes through it: install specs from either head, imported requirements, the IPC types that carry them, and the installed versions the guard set restates. - **Requirements and constraints reach an engine as files** (`-r `, `-c `) since 1.4.0: restating the installed set one argv entry per package (SP-1) passed Windows' 32,767-character command line at about 1,300 packages. The files hold exactly the tokens argv held — rendered `PinnedSpec`s and validated `Spec`s — and, like `probe.py` and the pins handed to pip-audit, each is an `exec::TempFile`: a fresh random name created with `create_new`, so an existing file is never written through, and deleted on drop. - Interpreter paths come only from discovery (registry/launcher/uv/venv scan) or from a person — *Add interpreter…*, `pipdock env add`, `env use`, `--env`. **A path from a person goes through `envs::validate_interpreter` before anything runs it** (since 1.6.0; this line claimed it for two milestones while the only check was existence): it must be an existing file named `python.exe`, `python3.exe`, `python3.12.exe` or the free-threaded `python3.14t.exe`, so the probe — which executes the file — cannot be pointed at another program, and **where it leads** is checked too, so a `python.exe` that links to another program is refused; it must not be inside PipDock's own tools or audit venv, compared canonically so `..` or a link cannot walk past. It is **run and stored as given, made absolute, with its links left alone**: a venv made with `--symlinks` has a `python.exe` that links to its base interpreter, and only running the link finds the venv — the first 1.6.0 build stored the canonical path, so `--env .venv` acted on the base Python. A Microsoft Store app-execution alias, which Windows will not resolve (os error 1920), is judged by its own path. Each refusal is PD-ENV-001. The picker that suggests a path is not the check; `env_add_manual` is, an added entry is checked again on every listing (`envs::probe_listed`, in both heads), and the CLI checks the stored `env use` default when it uses it. **What this is not is an enforcement point against the webview**: `env_probe` checks only a path the webview *says* is manual, and every command taking a `PyEnv` runs `env.interpreter` as the webview hands it back from `env_scan` — the trust backlog X36 records, which predates 1.6.0. An independent review of 1.6.0 found this bullet saying otherwise, the second time it has said more than the code. - `probe.py` is stdlib-only, written to a temp file with a random name, executed with `-I` (isolated mode: ignores `PYTHONPATH`, user site) so a poisoned env cannot inject code into the probe — and with `-X utf8`, because `-I` implies `-E`, which also discards invariant 7's `PYTHONUTF8`/`PYTHONIOENCODING`: until 1.4.0 a venv under a folder named in Vietnamese crashed the probe. - **Owner decision 2026-07-27 (spike SP-6): `-I` stays, and the cost is disclosed rather than hidden.** Isolated mode also disables user site-packages, so on a *non-venv* system Python the probe sees fewer distributions than `pip list` does — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reports `hidden_user_site`: the user-site path when it exists, is off `sys.path`, and is non-empty; `null` otherwise. Only when it is non-null does the Installed screen show a note naming the path (`env.partialListing`), so the disclosure is accurate rather than a permanent disclaimer. Dropping to `-E` was rejected: a package in user site is part of the untrusted surface the isolation exists to exclude. - Child processes run with inherited user privileges only; PipDock never elevates in v1 (PD-PRM-001 blocks instead — elevation broker is P2 with its own review). - The Code Health **project folder** is a user file-pick that becomes the working directory of three subprocesses and, with `--fix`, the target of a write. It is canonicalized and existence-checked, and a folder resolving inside `%LOCALAPPDATA%\PipDock\data\tools` is refused — rewriting the tools venv would break Health itself. - `git` is the one PATH-resolved program PipDock runs with a **user-controlled** working directory (the dirty-tree check). Windows' legacy `CreateProcess` search order would make a `git.exe` planted in a cloned repository win; **verified by planting one** — Rust's `Command` does its own resolution and does not search the current directory. Re-check if the process layer changes. A repository can also name a program for `git status` to run — `core.fsmonitor` in its own `.git/config`, which a project folder downloaded rather than cloned brings with it — so asking "is it safe to write here" would have run it. The check has been `git -c core.fsmonitor=false --no-optional-locks status …` since 1.4.0; a command-line `-c` wins over every config file. ## 3. PEP 668 policy (protecting the system Python) Environments carrying an `EXTERNALLY-MANAGED` marker are **blocked by default** with an explanation and a "create a venv instead" pointer. The override lives in Settings, off by default, with explicit warning copy; when enabled, every mutating screen for that env shows a persistent warning chip, and the flag corresponding to `--break-system-packages` is passed only then. PipDock never adds that flag silently — this is a hard rule. **As built in 1.4.0, the first version in which the override did anything.** Until then the checkbox saved and nothing read it, no chip existed anywhere, and the gate trusted whatever copy of the environment the caller had cached — with no gate at all on rollback. - **Decided on a fresh probe.** Update/install, uninstall and rollback open with one preamble (`flow::preamble`): probe the environment, then decide on what the probe says. Without the override a managed environment is PD-ENV-002 before any engine command runs. A venv is never externally managed, so the override never applies to one. - **A named value, not a bool.** `SystemPackages::OverrideAllowed` exists only in a flow that probed, found the marker and was told the setting is on — for the reason `SnapshotProof` is a named waiver: invariant 5 says the flag is never passed *implicitly*, and this makes "implicitly" greppable. It reaches both engines' installs and removals, and uv's dry run, which refuses a managed environment without it; pip's `--dry-run --report` never gets it. - **Per engine** (`engine::system_packages_for`). uv takes the flag throughout its supported range. pip implemented PEP 668 in 23.0 and added the flag in 23.0.1, so pip ≥ 23.0.1 gets it; a pip below 23.0 has nothing to override and is passed nothing; and pip 23.0 itself, which enforces the marker with no way past it, is refused with PD-ENV-002, its message naming 23.0.1. - ***Upgrade pip* is outside the override.** It refuses a managed environment whatever the setting says, and never passes the flag. - **Turning it on asks first.** The checkbox opens a confirm with Cancel rendered first and focused, so `Enter` cancels (`PdSettings`); turning it off saves at once. The chip (`PdOverrideChip`) shows on Installed/Updates, Search's dock bay, the plan panel and an environment's detail — and only where the override applies: the setting is on *and* the environment carries the marker. A chip on a venv would claim the flag was being sent. - **The CLI has no switch of its own.** It reads the setting from the store both heads share — the override stays a decision made in the GUI, behind the confirm — and says on stderr, on every run it applies to, that `--break-system-packages` will be passed. ## 4. Network surface | Destination | Purpose | Notes | |---|---|---| | `pypi.org` | PEP 691 name index; per-package JSON metadata; since 1.4.0, per-release JSON for `Requires-Python` (invariant 10 — uv's plans and exact pins; `crate::release`, at most eight in flight, each answer cached forever in the store) | HTTPS with certificate verification; redirects restricted to `pypi.org`/`files.pythonhosted.org` | | — everything else | none | engines make their own PyPI connections per their configs (user `pip.ini`/`uv.toml` respected, incl. private indexes — PipDock does not rewrite index URLs) | `pypi.org` is the **only** host PipDock itself connects to. It does not update itself (§5), so it has no reason to reach `github.com` — the legal gate and the bug-report deep link hand a URL to the user's browser rather than fetching anything. The webview cannot reach either: `connect-src` in `tauri.conf.json` allows only `'self'` and the IPC origin, so all network access goes through Rust. **Four hosts may be handed to the browser, and the allowlist is the record of why.** `capabilities/external-links.json` scopes `opener:allow-open-url` to `https://github.com/*`; to `https://docs.astral.sh/*` since Phase 3 · P4 — every ruff finding carries its own rule page and CODE-HEALTH-SPEC §6 as amended requires using ruff's `url` rather than constructing one; to `https://poli0981.dev/*` since Phase 4, for the one page the About tab links to that lists every other way to reach the author; and to `https://osv.dev/*` since P1-1, where every advisory links to its entry and the alternative was a promise that rejects in silence. None is a connection PipDock makes; all four are URLs it asks the OS to open. This paragraph said "three" from P1-1 until 1.4.0 while listing four — drift no sentence catches and a test does: `the_opener_reaches_four_hosts_and_no_more` (`src-tauri/src/lib.rs`) now fails on a fifth, or on one fewer. The widening is recorded here rather than only in `capabilities/` because an allowlist entry is a change to this document's subject matter, not a config detail — and because the failure mode of *not* widening it is silent: the promise rejects, nothing opens, and nothing anywhere says so. **What the scope actually defends is narrower than it looks.** Most call sites pass module constants no injected string can reach. Three pass data: `PdErrorRow` hands over a URL built in Rust; `PdAuditReport` an OSV URL that `audit::advisory_url` builds from an advisory id it has checked against a whitelist (ASCII letters, digits and `-`), so the tool chooses the id and never the destination; and `PdHealthReport` hands over `finding.url` — which comes out of **ruff's own JSON** over the user's source tree, and is the only URL in the application taken verbatim from a third-party tool's output. `https://docs.astral.sh/*` is precisely what stops that being anything else. That is also why the contact addresses in About are copied to the clipboard rather than opened: a `mailto:` entry would widen the allowlist by a whole URL *scheme*, and re-open a target class for that one call site, to save a paste. **The webview's reach is narrowed, and its grants are pinned.** Beyond `connect-src`, the Content-Security-Policy is `default-src 'self'` with `object-src`, `base-uri` and `form-action` all `'none'` (since 1.4.0), and a release build's `style-src` is `'self'` alone — React sets styles through CSSOM, which CSP does not govern. The development policy, `devCsp`, adds `'unsafe-inline'` because Vite injects CSS as `