mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
Sahil BansalandGitHub
94781d6bda
* refactor: remove guard mode execution paths and guard-only packages Guard (non-proxy) mode is removed; all package-manager commands now always run the proxy flow. Removes the guard engine, the common flow, the extractor package, the npm/pypi dependency resolvers and the PackageResolver plumbing that only guard mode consumed. The guard package retains only PackageManagerGuardInteraction, which the proxy flow and confirmation interceptors reuse for user prompts. Proxy behavior is unchanged. * refactor: remove proxy opt-out surfaces, guard references in config, action and docs Removes Config.ProxyMode, ProxyConfig.Enabled, IsProxyModeEnabled, the proxy_mode legacy fallback, PMG_PROXY_ENABLED handling and the --proxy-mode / --include-dev-dependencies flags. Proxy interception can no longer be disabled. Also removes the proxy-mode input from the GitHub Action, the proxy-mode doctor check and setup info row, updates the E2E workflow to stop passing --proxy-mode=false, and sweeps guard-mode wording from docs and the config template. The legacy proxy_install_only flat key and PMG_PROXY_INSTALL_ONLY env var remain supported. audit.FlowTypeGuard is kept so previously recorded audit events still translate for cloud sync. * feat: fail loudly when a removed proxy opt-out is still configured A leftover proxy.enabled: false / proxy_mode: false config key or PMG_PROXY_ENABLED=false / PMG_PROXY_MODE=false env var previously meant guard mode; silently ignoring it would switch those users to proxy interception without notice. PMG now exits with an actionable error naming the exact source. Precedence mirrors the old resolution order: env (ignored under lockdown) > proxy.enabled > legacy proxy_mode. The pmg config subtree is exempt so the config file can still be fixed with pmg config edit/set. The GitHub Action's proxy-mode input is kept as a tombstone that fails the action when set to false and warns otherwise. * refactor: extract flows.RunProxy and address review findings Collapses the identical parse-then-run body duplicated across the 12 package manager commands into flows.RunProxy. Documents the cache-hit / offline analysis trade-off versus the removed guard manifest path, fixes a stale non-proxy label in the E2E workflow and a stale guard reference in the uvx parser comment. * fix(config): mirror old proxy opt-out precedence exactly PMG_PROXY_MODE only ever took effect through the legacy fallback, which was gated on the presence of a proxy: key in the config file (even a null one). Promoting it to the top env tier caused two inversions: a stale PMG_PROXY_MODE=false hard-failed configs that resolved to proxy mode, and PMG_PROXY_MODE=true silently overrode an explicit proxy.enabled: false file opt-out. The check now resolves in the old order: PMG_PROXY_ENABLED > proxy: section (presence gates the legacy tier) > PMG_PROXY_MODE > flat proxy_mode. parseOptOutBool also accepts numeric values (0 = false) to match viper's WeaklyTypedInput/cast.ToBool coercion, so proxy.enabled: 0 and proxy_mode: 0 are detected as opt-outs. * refactor: move package manager interaction out of guard * refactor: trim package manager interaction * fix(config): normalize config keys viper-style in proxy opt-out check Viper resolved config file keys case-insensitively and expanded dotted keys, so spellings like Proxy:, Enabled:, a literal proxy.enabled key or Proxy_Mode selected guard mode before the removal. The opt-out check now lowercases keys recursively and nests dotted keys before matching, so those existing opt-outs fail loudly instead of being silently ignored. * refactor: remove inert transitive controls, dead parser state and guard audit variant transitive / transitive_depth lost their only consumers with the dependency resolvers; remove the config fields, flags, template and doc entries, and the report/audit plumbing that misreported transitive analysis as enabled. Remove write-only parser state (PackageInstallTarget.Extras, ParsedCommand.ManifestFiles, ShouldExtractFromManifest); IsManifestInstall stays as it feeds sandbox gating via IsInstallationCommand. Remove audit.FlowTypeGuard and its cloud mapping; guard events recorded by pre-removal versions in an unsynced WAL translate to UNSPECIFIED. * fix: address review findings on the opt-out wiring and cleanups Move the removed-opt-out rejection from the CLI PersistentPreRun into proxyFlow.Run: the check now fires exactly for package-manager runs, so non-install commands (pmg setup remove, doctor, config, version) stay usable to fix or remove an opted-out installation, and future commands inherit or avoid the check by construction instead of by exemption list. Also: make the e2e malicious-package assertion actually fail the job when an install is not blocked, route pmg go through flows.RunProxy, and drop the dead extras return from pypiParsePackageInfo (extras are still stripped from package names). * fix(config): make the removed opt-out check faithful to the old resolution The gate that silenced the legacy proxy_mode surfaces matched the raw proxy key case-sensitively in the old code, while values resolved viper-style (case-insensitive, dotted keys); applying each semantic where the old code did fixes both divergences: a case-variant Proxy: section no longer hides a flat proxy_mode: false opt-out, and a dotted proxy.enabled: false overridden by proxy_mode: true no longer errors. Replace the generic key-tree normalization with two targeted lookups (the check only ever resolves proxy.enabled and proxy_mode), which also makes colliding spellings resolve deterministically. Coerce legacy-tier values cast.ToBool-style so PMG_PROXY_MODE=off style opt-outs are detected, log the config read error instead of swallowing it, and shorten the error to a one-line statement with the specific remedy in the help text. Add lockdown coverage (env inert both directions) and a repeated-run determinism test. * fix(config): fall back to defaults for unrecognized proxy opt-out values The old loader swallowed viper errors and ran on defaults, so values like proxy.enabled: yes or PMG_PROXY_ENABLED=banana silently discarded the whole config and defaulted to proxy. Treat them the same way now: unrecognized values mean the default (proxy on) instead of a hard error, and the doc comment no longer claims the old loader failed loudly. Only values that actually meant guard mode fail. Also check the removed opt-out before the CA trust check in pmg go, restoring the old error precedence: a config problem must not steer the user into an unnecessary OS trust store change. * fix(e2e): PMG_PROXY_MODE assertion must match the legacy gate semantics The runner's setup step writes the template config, which has a proxy: section — and with one present the legacy PMG_PROXY_MODE was always inert, so expecting a loud failure there asserts pre-fidelity-fix behavior. Assert both sides instead: inert (command succeeds) with the standard config, loud failure against an empty config dir where the legacy fallback actually applied. * refactor(config): collapse parseOptOutBool to ParseBool over the string form YAML hands us typed values (bool, int), so route them through fmt.Sprintf %v and strconv.ParseBool instead of a per-type switch. Identical behavior for every recognized value; numbers other than 0/1 now read as no opinion instead of cast.ToBool's nonzero-true, which no real config relies on.
107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# Proxy Mode
|
|
|
|
PMG protects package installations through proxy based interception:
|
|
|
|
- PMG starts a micro-proxy server on a random localhost port
|
|
- Runs `npm` and other supported package managers configured to use the proxy
|
|
- Intercepts package registry requests and analyzes packages as they are downloaded
|
|
- Blocks malicious packages and allows trusted packages to be installed
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
pmg npm install lodash
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Proxy behavior is configured under the `proxy:` section in `config.yml`:
|
|
|
|
```yaml
|
|
proxy:
|
|
install_only: false
|
|
```
|
|
|
|
| Key | Default | Description |
|
|
|---|---|---|
|
|
| `install_only` | `false` | When `true`, only install commands are proxied. Other commands (e.g., `npm ls`, `pip list`) bypass the proxy and execute directly. |
|
|
| `skip_commands` | `{}` | Per-package-manager commands to bypass the proxy. Only applies when `install_only` is `true`. |
|
|
|
|
### Per-package-manager skip commands
|
|
|
|
The `skip_commands` map lets you define additional commands that should bypass the proxy for specific package managers. This only takes effect when `install_only` is `true`:
|
|
|
|
```yaml
|
|
proxy:
|
|
install_only: true
|
|
skip_commands:
|
|
npm: ["dev", "my-script"]
|
|
pip: ["list", "show"]
|
|
```
|
|
|
|
Commands in `skip_commands` are matched against the first non-flag argument. For example, `npm dev` would match `dev`, but `npm install dev` would not since `install` is the first non-flag argument.
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `PMG_PROXY_INSTALL_ONLY` | Override `proxy.install_only` |
|
|
|
|
The legacy flat config key `proxy_install_only` is still supported when the `proxy:` section does not exist in the config file.
|
|
|
|
### Removed: disabling proxy interception
|
|
|
|
Guard mode (the non-proxy analysis flow) has been removed and proxy interception can no longer be disabled. PMG fails with an error when it detects a leftover opt-out — `proxy.enabled: false` or `proxy_mode: false` in the config file, `PMG_PROXY_ENABLED=false` or `PMG_PROXY_MODE=false` in the environment — instead of silently switching to proxy interception. Remove the setting to proceed. The `--proxy-mode` flag is removed and fails as an unknown flag.
|
|
|
|
Note one trade-off versus the removed guard mode: the proxy analyzes packages as they are downloaded, so installs fully served from a local package manager cache (e.g. npm cache, pnpm store, pip cache, `--offline` installs) do not trigger analysis. Guard mode analyzed manifest-listed packages via registry metadata regardless of downloads. Packages are analyzed when first fetched through the proxy, which is when they enter those caches.
|
|
|
|
## Supported Package Managers
|
|
|
|
| Package Manager | Status |
|
|
| --------------- | ------ |
|
|
| `npm` | ✅ |
|
|
| `npx` | ✅ |
|
|
| `pnpm` | ✅ |
|
|
| `pnpx` | ✅ |
|
|
| `bun` | ✅ |
|
|
| `yarn` | ✅ |
|
|
| `pip` | ✅ |
|
|
| `uv` | ✅ |
|
|
| `uvx` | ✅ |
|
|
| `poetry` | ✅ |
|
|
| `go` | 🧪 experimental |
|
|
|
|
### Go (experimental)
|
|
|
|
`pmg go` guards Go module downloads through the same proxy flow. It is
|
|
experimental and opt-in: it only runs when invoked explicitly as `pmg go ...`
|
|
and is deliberately excluded from `pmg setup` shell aliases and PATH shims.
|
|
|
|
<details>
|
|
<summary>How it differs from npm/PyPI</summary>
|
|
|
|
- The module proxy host comes from the effective `GOPROXY` (including
|
|
`go env -w` values), not a fixed registry. PMG intercepts whatever HTTPS
|
|
proxies are configured and rewrites the child's `GOPROXY` to a fail-closed,
|
|
comma-joined list: `direct` is removed (a module PMG cannot inspect fails
|
|
instead of silently bypassing analysis) and pipe separators collapse to
|
|
comma so a block is terminal.
|
|
- Malware analysis and dependency cooldown run on the `.zip` source download —
|
|
the only GOPROXY endpoint that delivers code. `.info`/`.mod` metadata passes
|
|
through (cooldown reads the publish time from `.info` without modifying it).
|
|
- `sum.golang.org` is never MITM'd and `/sumdb/` requests pass through
|
|
unmodified, so Go's checksum-database verification stays fully intact.
|
|
Toolchain downloads (`golang.org/toolchain`) are allowed on Go's own
|
|
checksum verification.
|
|
- On macOS and Windows, Go only trusts the OS trust store, so
|
|
`pmg setup cert install` is required first; `pmg go` fails fast with
|
|
instructions if the PMG CA is not trusted. Linux works out of the box.
|
|
- Modules matching `GOPRIVATE`/`GONOPROXY` are fetched directly from their
|
|
VCS host and are not analyzed; PMG warns when these are set.
|
|
|
|
</details>
|
|
|
|
## References
|
|
|
|
- [Persistent Proxy Mode](./persistent-proxy.md)
|