mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
b19473945b
* feat: add experimental Go module support via pmg go Adds Go modules as a proxy-guarded ecosystem, opt-in only: the command runs solely when invoked explicitly as `pmg go ...` and is deliberately excluded from setup aliases and PATH shims so existing users are unaffected. - packagemanager: goPackageManager with fail-safe command classification (vet/fix excluded from non-download since they can fetch on a cold cache) and pinned-version extraction where only canonical semver counts as explicit. - GOPROXY normalization (fail-closed): effective GOPROXY read via `go env` (honors go env -w), rebuilt comma-joined with `direct` dropped so a 403 block is terminal and nothing silently falls back to unanalyzed VCS fetches. GOPRIVATE/GONOPROXY surface a warning; GOINSECURE is cleared. Contributed to the proxy flow through a new ProxyRoutingProvider hook (extra child env + dynamic MITM hosts). - Go interceptor with dynamic host matching from the user's effective GOPROXY via InterceptorContext.GoProxyHosts. Malware analysis runs on .zip only (the sole endpoint that delivers code); .info/.mod/@latest/ list pass through; /sumdb/ traffic and sum.golang.org are never touched so checksum-db verification stays intact; golang.org/toolchain is allowed on Go's own checksum verification. - Dependency cooldown: publish time captured from .info responses (body unmodified), in-window .zip blocked with 403; fails open for cooldown only when the publish time was never observed. - Cert gate: on macOS/Windows `pmg go` fails fast with actionable guidance unless the persisted PMG CA is OS-trusted (Go ignores SSL_CERT_FILE there); Linux works via the injected bundle. - proxye2e: GOPROXY-protocol mock registry, Go driver and 10 hermetic cases (allow/block/confirm, case-escaped paths, cooldown block and fail-open, toolchain, sumdb passthrough). Verified end-to-end on Linux: `pmg go get github.com/google/uuid@v1.6.0` MITMs proxy.golang.org, analyzes the decoded module at the .zip fetch, and go.sum verification succeeds through the tunneled checksum db. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014xuhBeTVpfU4SdqVaarvuK * fix(go): address review findings on experimental Go support - Drop fmt/clean from NonDownloadCommands: both load packages via go list and can download modules on a cold cache, which would bypass the proxy under install_only. - Support GOPROXY entries with a base path (e.g. corp Athens/JFrog at https://corp/goproxy): the interceptor now receives host -> base URL and strips the path prefix before parsing module URLs, so verdicts and cooldown key on the real module path. - Default unschemed GOPROXY entries to https, matching go's own behavior, so corp mirrors configured as bare hosts are intercepted instead of silently unanalyzed. - Memoize the final verdict per module zip: go re-requests a failed zip during go get's load phase, which double-recorded stats (the report showed the same blocked module twice) and would have re-prompted on Confirm verdicts. - Fetch .info out-of-band on a cooldown cache miss: go serves .info from its local module cache on any machine that used go before PMG, which silently disabled cooldown. Failure of the side-fetch still fails open for cooldown only. - Move the noop package resolver into packagemanager. Verified live: cold-cache cooldown block now records once; warm-cache rerun is blocked via the side-fetch instead of failing open. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014xuhBeTVpfU4SdqVaarvuK * docs: collapse Go proxy-mode details by default Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014xuhBeTVpfU4SdqVaarvuK --------- Co-authored-by: Claude <noreply@anthropic.com>
107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
# Proxy Mode
|
|
|
|
PMG supports proxy based interception as an alternative to the current optimistic dependency resolution. When enabled:
|
|
|
|
- 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:
|
|
enabled: true
|
|
```
|
|
|
|
| Key | Default | Description |
|
|
|---|---|---|
|
|
| `enabled` | `true` | Enable proxy-based interception. When `false`, PMG falls back to guard-based analysis. |
|
|
| `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.
|
|
|
|
### CLI flags
|
|
|
|
Use `--proxy-mode` to override `proxy.enabled` at runtime.
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `PMG_PROXY_ENABLED` | Override `proxy.enabled` |
|
|
| `PMG_PROXY_INSTALL_ONLY` | Override `proxy.install_only` |
|
|
|
|
Legacy variables `PMG_PROXY_MODE` and `PMG_PROXY_INSTALL_ONLY` (for the old flat config keys) are still supported when the `proxy:` section does not exist in the config file.
|
|
|
|
## 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)
|