Protaction is a terminal-first CLI that helps developers, CI jobs, platform teams, and AI coding agents run package manager workflows with stronger supply-chain guardrails.
It can preview package manager operations before they execute, scan local projects for suspicious execution paths, and install explicit shims so familiar commands such as npm install, pnpm add, or yarn install can be routed through Protaction.
Repository: marcoabate-ck/protaction
- Node.js
>=22.13.0 - npm, pnpm, or Yarn for the package manager workflows you want Protaction to guard
Install from npm:
npm install -g protactionInstall from Homebrew:
brew install marcoabate-ck/protaction/protactionInstall from GitHub Releases with checksum verification:
curl -fsSL https://raw.githubusercontent.com/marcoabate-ck/protaction/main/install.sh | shThe shell installer downloads the release bundle, verifies its SHA-256 checksum, installs protaction into ~/.protaction/bin, and prints PATH instructions. It does not mutate shell profiles.
Check the installation:
protaction --helpCreate a conservative project config:
protaction init --yesChoose the generated top-level operating mode:
protaction init --yes --mode strict
protaction init --mode monitorPreview a package manager command without executing it:
protaction preview npm install
protaction preview pnpm add react
protaction preview yarn add reactScan the current project without executing project code:
protaction detectDiagnose package managers, shims, config, PATH, and active policy:
protaction doctor
protaction history --limit 10Use preview before running install, add, or update commands:
protaction preview npm install
protaction preview pnpm add lodash
protaction preview yarn upgradePreview output includes a deterministic risk score, risk label, reason ids, dependency categories, lifecycle script changes, and policy decisions. Protaction does not execute the wrapped package manager command during preview.
Preview accuracy is configurable:
basic: local and offline; uses manifests and parsed lockfiles only.intermediate: also queries trusted registry metadata for lifecycle scripts in packages normalized from the current lockfile and command-explicit packages.advanced: also downloads trusted package tarballs, verifies integrity when present, and readspackage/package.jsonwithout executing code.
Authenticated registry and tarball access is restricted to preview.trustedRegistries.
Even trusted registries are blocked by default when they use insecure URLs or resolve to private/internal networks. Use preview.allowedRegistryHosts or preview.allowPrivateRegistryNetworks only for explicit private registry opt-in.
Use detect to inspect project files, package scripts, and tooling config without importing or executing project code:
protaction detect
protaction detect --jsonFindings include stable rule ids, severity, confidence, evidence, and recommendations.
Shims are explicit and reversible. They let Protaction guard familiar package manager commands by placing controlled wrappers earlier in your PATH.
protaction shim --npm
protaction shim --pnpm
protaction shim --yarn
protaction shim status --allRemove shims when you no longer need them:
protaction shim remove --npm
protaction shim remove --allUse doctor when you need to understand which package manager binaries are active and whether Protaction is guarding the expected paths:
protaction doctor
protaction doctor --jsonDoctor reports package manager discovery, real binary paths, shim status, PATH ordering, config sources, active policy, Corepack, nvm, mise, asdf, and Volta. It reports environment state without mutating your shell, PATH, shims, or project files.
Create a default config with:
protaction init --yesUse --mode monitor|warn|strict to choose the generated top-level mode. If omitted, init writes mode: warn. This does not change generated agent policy modes such as agents.default.mode, which remain conservative by default.
Example:
schemaVersion: 1
mode: warn
packageManagers:
npm:
enabled: true
preview: auto
pnpm:
enabled: true
preview: auto
yarn:
enabled: false
preview: auto
preview:
mode: interactive
accuracy: basic
trustedRegistries:
- https://registry.npmjs.org
allowPrivateRegistryNetworks: false
allowedRegistryHosts: []
failClosed: true
detect:
enabled: true
blockSeverity: high
include:
- .
exclude:
- node_modules
- dist
- build
- .git
agents:
default:
enabled: true
mode: strict
requireHumanReviewForNewDependencies: true
requireHumanReviewForNewDirectDependencies: true
requireHumanReviewForLifecycleScripts: true
allowDependencyAdditions: policy-only
audit:
enabled: true
retentionDays: 90
detail: summarySupported project config files:
protaction.config.jsonprotaction.config.yamlprotaction.config.ymlprotaction.config.jsprotaction.config.ts
JSON and YAML are data-only. JS config is executable code and is loaded only when explicitly allowed by the relevant command. TypeScript config files are discovered but are not imported directly by the current runtime; use JSON, YAML, or JS until an explicit TypeScript loader is added.
CI must be deterministic and non-interactive. Use JSON output and treat non-zero exit codes as policy failures:
protaction preview --ci --json --actor codex npm install
protaction detect --json
protaction doctor --jsonIn CI, warn thresholds fail instead of prompting. Unknown AI-agent identities fall back to the default agent policy.
Protaction guarantees these baseline boundaries:
previewdoes not execute the wrapped package manager command.detectdoes not execute project code or import JS/TS project config.doctorreports environment state without mutating PATH, shell profiles, shims, package manager config, or project files.initdoes not install shims, mutate shell profiles, install dependencies, or execute project code.- Shims are explicit, reversible, and resolve the real package manager while skipping Protaction shim paths.
- CI never prompts.
basic preview is static and offline. Higher accuracy levels may use registry requests or tarball downloads for packages reconstructed from supported lockfiles and package specs. Auth tokens from NPM_TOKEN or NODE_AUTH_TOKEN are redacted from output and cache keys.
Private registries must be listed in preview.trustedRegistries before Protaction contacts them or sends bearer tokens.
Protaction keeps local summary-only analysis history at ~/.config/protaction/history.ndjson by default. History includes scores, reason ids, counts, decisions, accuracy, and degradation status; it does not persist script command bodies, full environments, tokens, or credential-bearing URLs.
Yarn Berry lockfile parsing is reported as unsupported when it cannot be reconstructed safely.
Detection is deterministic and intentionally conservative. False positives are expected; findings include rule ids, evidence, severity, confidence, and recommendations to make review manageable.
This project uses Node.js, TypeScript, Vitest, and pnpm.
The repository pins pnpm through packageManager and .nvmrc. The workspace also sets:
minimumReleaseAge: 1440, delaying newly published packages by 24 hours, including transitives.allowBuilds: { esbuild: true }, so dependency lifecycle/build scripts are not broadly pre-approved.esbuildis narrowly allowed because Protaction uses it to build the release bundle.
Set up a checkout:
pnpm install
pnpm run build
pnpm link --globalRun local checks:
pnpm test
pnpm run build
pnpm run lint
pnpm run typecheck
pnpm run pack:dry-runReleases are tag-driven. A tag such as v0.1.0 runs .github/workflows/release.yml, which tests, builds, lints, typechecks, builds the release bundle, renders the Homebrew formula, publishes to npm with provenance through trusted publishing/OIDC, and uploads release assets to GitHub Releases.
The release jobs use the protected release environment.