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.
147 lines
6.1 KiB
Markdown
147 lines
6.1 KiB
Markdown
# Configuration
|
|
|
|
PMG supports local configuration through a configuration file. To create the default configuration file, run:
|
|
|
|
```bash
|
|
pmg setup install
|
|
```
|
|
|
|
To see the configuration file path and activated configuration, run:
|
|
|
|
```bash
|
|
pmg setup info
|
|
```
|
|
|
|
To edit configuration file:
|
|
|
|
```bash
|
|
pmg config edit
|
|
```
|
|
|
|
To get a config value (output is JSON):
|
|
|
|
```bash
|
|
pmg config get paranoid
|
|
pmg config get cloud.enabled
|
|
```
|
|
|
|
To set a config value:
|
|
|
|
```bash
|
|
pmg config set paranoid true
|
|
pmg config set dependency_cooldown.days 10
|
|
pmg config set cloud.enabled true
|
|
```
|
|
See [config template](../config/config.template.yml) for the configuration schema.
|
|
|
|
## Environment Variables
|
|
|
|
Any configuration key can be overridden using environment variables, without modifying the config
|
|
file. This is useful for CI/CD pipelines or temporary overrides.
|
|
|
|
**Format:** `PMG_<KEY>` where the key is the config key uppercased, with nested keys joined by `_`.
|
|
|
|
| Config key | Environment variable |
|
|
|---|---|
|
|
| `paranoid` | `PMG_PARANOID` |
|
|
| `proxy.install_only` | `PMG_PROXY_INSTALL_ONLY` |
|
|
| `verbosity` | `PMG_VERBOSITY` |
|
|
| `skip_event_logging` | `PMG_SKIP_EVENT_LOGGING` |
|
|
| `sandbox.enabled` | `PMG_SANDBOX_ENABLED` |
|
|
| `dependency_cooldown.enabled` | `PMG_DEPENDENCY_COOLDOWN_ENABLED` |
|
|
| `cloud.enabled` | `PMG_CLOUD_ENABLED` |
|
|
|
|
The legacy flat key `proxy_install_only` is still supported when the `proxy:` section does not exist in the config file.
|
|
|
|
Proxy interception can no longer be disabled: PMG fails with an error when the config or environment still contains `proxy.enabled: false`, `proxy_mode: false`, `PMG_PROXY_ENABLED=false` or `PMG_PROXY_MODE=false`. See [proxy mode](proxy-mode.md).
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
# Enable paranoid mode without editing the config file
|
|
PMG_PARANOID=true pmg npm install express
|
|
|
|
# Restrict proxy to install commands only
|
|
PMG_PROXY_INSTALL_ONLY=true pmg npm install express
|
|
```
|
|
|
|
**Precedence (highest to lowest):**
|
|
|
|
1. CLI flags
|
|
2. Environment variables (`PMG_*`)
|
|
3. Config file (`config.yml`)
|
|
4. Built-in defaults
|
|
|
|
Under a [globally managed config](#globally-managed-configuration) with `global_lockdown` enabled, PMG disables `PMG_*` and managed-flag overrides.
|
|
|
|
|
|
**Limitation**
|
|
|
|
- `config set` can only update keys that are present and uncommented in the config file.
|
|
If a key is commented out (e.g. `# endpoint_id: "my-machine"`) or missing entirely, `set` will
|
|
return a "key not found" error. To fix this, uncomment or add the key manually via `pmg config edit`,
|
|
or run `pmg setup install` to merge missing template keys into your config.
|
|
|
|
## Globally Managed Configuration
|
|
|
|
For centrally managed or fleet deployments, PMG can read an OS-level **global config file**. When this file exists, it is authoritative: PMG uses it and ignores the per-user `config.yml` (the two are never merged). An administrator ships a machine-wide baseline this way, and can lock it (see [Lockdown](#lockdown)) to forbid user overrides.
|
|
|
|
**Paths** (used when the file is present):
|
|
|
|
| OS | Global config path |
|
|
|---|---|
|
|
| macOS | `/Library/Application Support/safedep/pmg/config.yml` |
|
|
| Linux | `/etc/safedep/pmg/config.yml` |
|
|
| Windows | `%PROGRAMDATA%\safedep\pmg\config.yml` |
|
|
|
|
Check whether a global config is active with `pmg setup info`:
|
|
|
|
```bash
|
|
pmg setup info
|
|
# Config Source: global <- global config, overrides allowed
|
|
# Config Source: global (locked) <- global config with lockdown enabled
|
|
# Config Source: user <- per-user config in effect
|
|
```
|
|
|
|
### Behaviour
|
|
|
|
Whenever a global config file is present:
|
|
|
|
- **It is authoritative.** PMG ignores the per-user `config.yml`. The file may be **partial**. Keys it does not set fall back to PMG's built-in defaults, not to a user's values.
|
|
- **`config set` and `config edit` fail.** They return an error stating the config is globally managed. To change it, deploy an updated file at the OS path, which is root-owned and not writable by users.
|
|
- **`pmg setup install` skips the per-user config.** It still creates shell aliases and shims per user.
|
|
|
|
By default a user can still override the global config's values at runtime through `PMG_*` environment variables and CLI flags. Enable lockdown to forbid that.
|
|
|
|
## System Install (Linux)
|
|
|
|
See [system-install.md](./system-install.md) for `pmg setup install --system`: artifacts, Docker `ENV PATH`, what works vs what differs (aliases, config edit, logs, cloud, CA, sandbox), and permissions.
|
|
|
|
### Lockdown
|
|
|
|
Add `global_lockdown: true` to the global config to enforce it:
|
|
|
|
```yaml
|
|
# Only meaningful in the global config file.
|
|
global_lockdown: true
|
|
```
|
|
|
|
When lockdown is on:
|
|
|
|
- **CLI flags that would change a managed value fail fast.** For example, `pmg --sandbox=false ...` or `pmg --paranoid ...` errors out instead of overriding policy. Governed flags: `--paranoid`, `--skip-event-log`, `--sandbox`, `--sandbox-enforce`, `--sandbox-profile`, `--sandbox-allow`, `--skip-dependency-cooldown`. Operational flags such as `--dry-run` keep working.
|
|
- **`PMG_*` variables cannot change the config**, including `PMG_INSECURE_INSTALLATION` (which otherwise bypasses malicious-package blocking).
|
|
|
|
PMG reads `global_lockdown` straight from the global file, so a user cannot flip it through env or CLI. If the global file exists but cannot be read or parsed, PMG fails closed and treats it as locked. `PMG_CONFIG_DIR` and `PMG_CACHE_DIR` still relocate per-user state directories (logs, cache) in any mode, but leave the managed config alone.
|
|
|
|
### Precedence
|
|
|
|
| Mode | Effective order (highest to lowest) |
|
|
|---|---|
|
|
| No global config | CLI flags > `PMG_*` env > per-user `config.yml` > built-in defaults |
|
|
| Global config, no lockdown | CLI flags > `PMG_*` env > global config > built-in defaults |
|
|
| Global config, `global_lockdown: true` | global config > built-in defaults (env and managed-flag overrides refused) |
|
|
|
|
### Deploying via MDM (macOS)
|
|
|
|
Scripts to install or update PMG and deploy a global config across a macOS fleet (Jamf, Mosyle, Kandji, Intune) live in [`scripts/mdm`](../scripts/mdm). Bundle a `config.yml` next to the scripts. The installer places it at the global path, and the uninstaller removes it. See the [`scripts/mdm` README](../scripts/mdm/README.md) for details.
|