PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the first button its advice ever had) and TESTING's golden count. SECURITY §2 claimed for two milestones that interpreter paths were canonicalized before use while the only check was existence; it now describes the validator that makes it true. PRD also records P0-9's first-run uv detection, P1-7 and P2 as not planned in maintenance mode. legal/PRIVACY-POLICY.md 1.3 names the interpreter paths a person adds, kept until removed, in both languages. With the repository URL it already changed, the first-run gate shows once in 1.6.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
27 KiB
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 of2.0 ; python_version<'0'reached argv as one token pip read as a requirement whose marker is false — a silent no-op install.pep440is 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.
- The version half has been true only since 1.4.0. Names always went through
- Requirements and constraints reach an engine as files (
-r <file>,-c <file>) 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 — renderedPinnedSpecs and validatedSpecs — and, likeprobe.pyand the pins handed to pip-audit, each is anexec::TempFile: a fresh random name created withcreate_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 throughenvs::validate_interpreterbefore 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 namedpython.exe,python3.exeorpython3.12.exe, so the probe — which executes the file — cannot be pointed at another program; it must not be inside PipDock's own tools or audit venv, compared canonically so..cannot walk past; and it is stored canonical, without the verbatim prefix. Each refusal is PD-ENV-001. The picker that suggests a path is not the check:env_add_manualand amanualenv_probevalidate whatever the webview names. probe.pyis stdlib-only, written to a temp file with a random name, executed with-I(isolated mode: ignoresPYTHONPATH, user site) so a poisoned env cannot inject code into the probe — and with-X utf8, because-Iimplies-E, which also discards invariant 7'sPYTHONUTF8/PYTHONIOENCODING: until 1.4.0 a venv under a folder named in Vietnamese crashed the probe.- Owner decision 2026-07-27 (spike SP-6):
-Istays, 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 thanpip listdoes — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reportshidden_user_site: the user-site path when it exists, is offsys.path, and is non-empty;nullotherwise. 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-Ewas rejected: a package in user site is part of the untrusted surface the isolation exists to exclude.
- Owner decision 2026-07-27 (spike SP-6):
- 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 like an interpreter path, and a folder resolving inside%LOCALAPPDATA%\PipDock\data\toolsis refused — rewriting the tools venv would break Health itself. gitis the one PATH-resolved program PipDock runs with a user-controlled working directory (the dirty-tree check). Windows' legacyCreateProcesssearch order would make agit.exeplanted in a cloned repository win; verified by planting one — Rust'sCommanddoes its own resolution and does not search the current directory. Re-check if the process layer changes. A repository can also name a program forgit statusto run —core.fsmonitorin 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 beengit -c core.fsmonitor=false --no-optional-locks status …since 1.4.0; a command-line-cwins 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::OverrideAllowedexists only in a flow that probed, found the marker and was told the setting is on — for the reasonSnapshotProofis 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 --reportnever 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
Entercancels (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-packageswill 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 <style> elements. Both live in tauri.conf.json, and vite.config.ts injects devCsp into vite dev and nothing else; it used to be a meta tag in ui/index.html, which put the weaker policy into every release build beside the stronger one — harmless, since the stricter of two policies wins, and still in the product. The capability set is exact in the same way: capabilities/*.json grants the main window the two event permissions the progress streams need, core:window:allow-close, the open and save dialogs (each returns a path and grants no file access), clipboard write and the scoped opener, and src-tauri/src/lib.rs pins that union with a test. core:default stood there until 1.4.0 — some sixty core commands nothing called, and not core:window:allow-close, so Decline on the legal gate did nothing in the installed app while its component test, which mocks close(), passed. Widening a grant is now a test change, on purpose; the CSP has no test of its own.
No telemetry, no crash reporting endpoints, no analytics. TLS failures surface as PD-NET-002 and the app never offers to disable verification — for PipDock's own requests, since 1.4.0, by reading the error's source chain: reqwest's top-level message never mentions the certificate, so PD-NET-002's guidance never showed.
5. Update integrity (PipDock itself)
PipDock does not update itself. New versions come from the GitHub Releases page and are installed like any other download.
That is a deliberate removal, not an omission. A self-updater is a permanent remote-code-execution path into a tool that already runs subprocesses against the user's interpreters, and it has to be defended for the life of the product: a signing key that must never leak, an endpoint that must never be spoofable, and verification logic that must never be bypassable. For a tool people open occasionally to tidy an environment, that is a large standing liability bought for a small convenience.
What replaces it: SHA-256 checksums published per release (SHA256SUMS.txt) for manual verification, which the README tells users to check because SmartScreen warns on first run — the binaries are not EV-code-signed. Installer artifacts are NSIS + MSI from the Tauri bundler. Since 1.4.0 the checksum file has LF line endings, written byte for byte: the CRLF one Set-Content produced made sha256sum -c on any other platform read the CR as part of each file name and report every file missing.
From 1.4.0, the installers carry a build-provenance attestation. The release workflow attests the .exe and the .msi (actions/attest-build-provenance), and gh attestation verify <file> --repo poli0981org/pipdock proves an installer was built by this repository's release workflow at the tagged commit (for 1.4.0 and 1.5.0, built before the repository moved to the poli0981org organization on 2026-11-21, the attestations stayed with the account that made them: --owner poli0981 --signer-repo poli0981/pipdock) — which a checksum published beside the file cannot, since whoever could replace one could replace both. The attestation is signed through Sigstore with a short-lived certificate bound to the workflow run, so it adds no key to keep.
The token that can write a release never runs the build. Building executes third-party code — every crate's build script, every npm package's install script — so the build job holds a read-only token and keeps no credentials in its checkout; a separate job downloads what it produced, attests it and drafts the release, and is the only one granted contents, id-token and attestations write (RELEASE-CI §3).
Consequences worth knowing: there is no signing keypair to generate or rotate, no TAURI_SIGNING_PRIVATE_KEY secret, no latest.json, and tauri-plugin-updater is not a dependency.
6. Auditing user environments (P1 Security tab)
pip-audit runs from a venv of its own in freeze-file mode: Engine::freeze the target env → its pins (name==version) in a temp file → pip-audit -r <pins> --no-deps -f json → findings joined to installed rows. Flags validated in SP-4 and pinned by a committed capture (tests/fixtures/audit/). Pins, not the raw freeze, since 1.4.0: an editable install (-e …) or a direct reference (name @ file:///…) is a line pip-audit cannot look up on an index, and a single one failed the whole audit. Neither is on PyPI, so neither has a PyPI advisory to miss.
Its own venv, not Code Health's, and that is a correction rather than a detail. This section said "the tools venv" from the day it was written; the code has refused that since P2, because pip-audit's closure contains msgpack, which publishes no universal wheel and would hard-fail the whole sync under --only-binary=:all: on a new CPython — taking Code Health down with a feature it does not use. health::AUDIT_TOOLS and health::audit_dir keep the blast radius inside the Security tab.
No severity, because pip-audit has none. This section promised "(CVE/GHSA id, severity, fixed-in)" against a field that does not exist under either vulnerability service; a finding carries id, fix_versions, aliases and description and nothing else. Findings are ordered by package, then by whether anything fixes them, then by id. A severity derived from the id's year or the prose would be a number PipDock invented, shown beside real ones.
The network surface does not change. pip-audit's default service is PyPI, and it is left there deliberately: §4's table still has one row. Findings link to the OSV entry, which is a visit the user's browser makes after a click, and the URL is built from a validated id rather than taken from the tool's output. "Update to fixed version" hands off to the normal Update flow — audit never auto-applies anything.
7. Supply chain of PipDock itself
- CI:
cargo audit(RustSec) +npm audit --audit-level=highgate every PR, and since 1.4.0 run again every day againstmain(security-scan.yml). A PR gate fires only when something changes, so an advisory published against a dependency already merged waited for the next PR to trip over it — which is howmainwent red on 2026-09-23 with no PR open to say so — and, because the failure notifier matched no workflow at all, with nobody told. Dependabot keeps the Rust, npm, Actions and Code Health pins and the Rust toolchain current (see RELEASE-CI.md §2).- The
cargo auditgate is on vulnerabilities and is never relaxed..cargo/audit.tomlignores a fixed list of informational advisories — unmaintained/unsound — on transitive crates PipDock cannot influence, chiefly Tauri's archived GTK3 bindings and, since 2026-10-20, zbus 5'szvariant/zbus_names/zvariant_derive(folded into zbus 6, which no Tauri plugin requires yet) — both stacks a Windows-only build never compiles — and, since 2026-11-21, chrono, whichCargo.locklists only because serde_with's weakchrono_0_4?features make Cargo record it, and which no target compiles at all. They are listed individually with justification so a new advisory still fails CI. Adding macOS/Linux builds (P2-1) is the point at which that block must be re-examined rather than extended. - That "still fails CI" has been true only since 1.4.0. Informational advisories — unmaintained, unsound, yanked — are cargo-audit warnings, and
rustsec/audit-check@v2, which ran the gate until then, let warnings through; on a pull request it failed only on critical, which is how September's advisories passed every PR. The gate is now a prebuiltcargo-audit(installed bytaiki-e/install-action, pinned by commit) run with--deny warnings. npm auditinstalls withnpm ci --ignore-scripts: it reads the lockfile and builds nothing, so no package's install script has a reason to run.
- The
cargo denychecks licences, sources and bans on every PR (deny.toml, since 1.4.0). Its licence allowlist — each entry GPL-3.0-compatible — turns THIRD-PARTY-NOTICES' "all bundled licenses are GPL-3.0-compatible" from a sentence into a test for every crate the Windows target resolves, transitive ones included; widening the list is a licensing decision, not a CI fix. Only crates.io may supply a crate — no git dependency, no other registry — and wildcard version requirements are refused. Advisories staycargo audit's, so there is one ignore list rather than two to keep in step. The npm half has the same check since 2026-11-21:scripts/check-licenses.mjs(npm licencesinci-node.yml) evaluates the SPDX expression of every packagepackage-lock.jsondoes not markdevagainst the same allowlist, entry for entry, and fails on a package that declares none. Both are required checks (RELEASE-CI §2). Qodana's licence audit would have been a third, but it needs a plan the project does not have, and a check this small should not depend on one.Cargo.lockandpackage-lock.jsoncommitted; builds are--locked.- The environments PipDock builds for itself install a pinned tree. Since 1.4.0
tools/tools-constraints.txtpins every package beneath the four tools, for the Code Health and the Security-tab venvs alike, so a broken or compromised release ofrequests,richormsgpackno longer reaches every user on their next sync (CODE-HEALTH-SPEC §2). The pins are versions, not hashes;--require-hashesis in ROADMAP's Audit backlog. - Workflows pin every action by commit, with the version in a comment for Dependabot — GitHub's own
actions/*andgithub/codeql-actionincluded since 2026-11-21, when the last tags went. No workflow calls another repository's. Until the move to the poli0981org organization four were callers into the owner's personal ops repo at@main, and its notifier checked out that repository'smainand ran its script with PipDock's Discord webhooks in the environment; those workflows are local now and the script is vendored (RELEASE-CI §1). A write permission sits on the job that needs it, not on the workflow (RELEASE-CI §1). A secret sits on the step that needs it:sonar.ymlbuilds and tests — every crate's build script, every npm package's — before it scans, soSONAR_TOKENis in the scanner step's environment alone, and the version spliced into the scanner's argv is checked against a version's shape first. - SonarQube Cloud analyses every PR and
mainfrom CI (sonar.yml, since 2026-10-25) rather than by automatic analysis, which never saw the Rust code and could import no coverage. Its quality gate is not a required check (RELEASE-CI §2); a red gate onmainfails the workflow and reaches Discord. - CodeQL runs from
codeql.yml(a caller into the ops repo until 2026-11-21) overjavascript-typescript,rustandactions. This bullet saidjavascript-typescriptonly, because "CodeQL has no Rust analyzer" — which stopped being true in 2025, and the ops repo's reusable handed any language straight tocodeql-action.actionsanalyses the workflows themselves: write permissions at workflow level and unpinned third-party actions, the class of mistake SonarCloud had been finding by hand. Only the JavaScript/TypeScript analysis is a required check, so Rust's blocking static analysis is still clippy-D warningspluscargo auditinci-rust.yml. - Qodana (
qodana.yml, since 2026-11-21) runs JetBrains' inspections as two Qodana Cloud projects, one per half of the repository, each with its own token: RustRover's in a Linux container (qodana-rust.yaml— it cannot see#[cfg(windows)]code, which clippy, CodeQL and SonarQube Cloud cover on Windows) and WebStorm's natively (qodana-js.yaml). A run fails on a problem outside its committed baseline, and only those reach Code scanning. It is not a required check: one of its linters is an early-access build behind an external service, and Dependabot's PRs get no token. - Third-party licenses tracked in
legal/THIRD-PARTY-NOTICES.md, which names the direct dependencies the manifests declare and is reconciled against them by hand at each release. It is not generated: an earlier revision of both documents claimedcargo about/license-checkerproduced it into alicenses/directory, and no such config, directory or release step has ever existed. The complete resolved graph isCargo.lockandpackage-lock.json, both committed. Generating the inventory is tracked as a Post-1.0 item; until it lands, the claim here matches what is done — andcargo denychecks the Rust licences without writing the inventory.
8. Data & privacy engineering
All state PipDock writes is local under %LOCALAPPDATA%\PipDock\data\.
The nesting is deliberate and was learned by installing. Tauri's NSIS per-user installer writes the program to $LOCALAPPDATA\{productName} — so a flat data root put pipdock-app.exe and uninstall.exe beside index.db, snapshots\ and tools\, and the "delete the folder to reset" advice below would have uninstalled the application. Deleting data\ is the complete reset; deleting the parent removes the program too, which is what the uninstaller is for. Verified: uninstalling removes its own binaries, the Start-menu shortcut and the registry entry, and leaves data\ untouched.
One exception, and it is the only one. ruff check --fix (CODE-HEALTH-SPEC §5, Phase 3 · P5) rewrites files in a project folder the user chose. It is PipDock's sole write outside site-packages and %LOCALAPPDATA%, it happens only behind an explicit confirm carrying a FixConsent the executing call demands, and it is refused entirely — before the first byte — if any target cannot be written. No snapshot is taken, because no snapshot in this application describes a source tree; the safety net is the user's own version control, which the confirm names and git status is consulted about twice. §1's threat model does not otherwise contemplate PipDock writing to user source, so this is the paragraph that says it does.
Logs contain package names and paths. There was no log until 1.4.0, while the Privacy Policy described one; now each head writes one file per UTC day under data\logs\ (pipdock.<date>.log for the GUI, pipdock-cli.<date>.log for the CLI), recording every command PipDock ran with its argv, exit code and duration, kept LOG_RETENTION_DAYS (14) by a sweep that touches only files named the way it names them — and the CLI's --log-file adds a copy wherever the user says. Nothing sends them anywhere; the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting data\ is a complete reset — and deleting the parent uninstalls the program, which is why the distinction is spelled out wherever the advice appears: legal/PRIVACY-POLICY.md §2 and the About tab. The Privacy Policy carried the pre-move wording for two weeks after the move; that is the failure this paragraph exists to prevent recurring.
9. Vulnerability reporting
Report privately through GitHub Security Advisories on poli0981org/pipdock, or by email to code@poli0981.dev; target acknowledgment ≤ 7 days. Coordinated disclosure preferred; in-range CVEs in shipped dependencies trigger a patch release via the standard pipeline.
.github/SECURITY.md is the short pointer GitHub's Security policy tab renders, and it points here. This file is the policy; that one exists so the tab is not empty.