Protaction

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

Warning

⚠️ This library is still under active development and is not ready for use yet, especially in production environments. Once this notice is removed, the library can be considered ready for usage.

Requirements

• Node.js >=22.13.0
• npm, pnpm, or Yarn for the package manager workflows you want Protaction to guard

Install

Install from npm:

npm install -g protaction

Install from Homebrew:

brew install marcoabate-ck/protaction/protaction

Install from GitHub Releases with checksum verification:

curl -fsSL https://raw.githubusercontent.com/marcoabate-ck/protaction/main/install.sh | sh

The 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 --help

Quickstart

Create a conservative project config:

protaction init --yes

Choose the generated top-level operating mode:

protaction init --yes --mode strict
protaction init --mode monitor

Preview a package manager command without executing it:

protaction preview npm install
protaction preview pnpm add react
protaction preview yarn add react

Scan the current project without executing project code:

protaction detect

Diagnose package managers, shims, config, PATH, and active policy:

protaction doctor
protaction history --limit 10

Common Workflows

Preview Dependency Changes

Use preview before running install, add, or update commands:

protaction preview npm install
protaction preview pnpm add lodash
protaction preview yarn upgrade

Preview 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 reads package/package.json without 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.

Scan A Codebase

Use detect to inspect project files, package scripts, and tooling config without importing or executing project code:

protaction detect
protaction detect --json

Findings include stable rule ids, severity, confidence, evidence, and recommendations.

Install Package Manager Shims

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 --all

Remove shims when you no longer need them:

protaction shim remove --npm
protaction shim remove --all

Diagnose An Environment

Use doctor when you need to understand which package manager binaries are active and whether Protaction is guarding the expected paths:

protaction doctor
protaction doctor --json

Doctor 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.

Configuration

Create a default config with:

protaction init --yes

Use --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: summary

Supported project config files:

• protaction.config.json
• protaction.config.yaml
• protaction.config.yml
• protaction.config.js
• protaction.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 And Automation

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 --json

In CI, warn thresholds fail instead of prompting. Unknown AI-agent identities fall back to the default agent policy.

Security Boundaries

Protaction guarantees these baseline boundaries:

• preview does not execute the wrapped package manager command.
• detect does not execute project code or import JS/TS project config.
• doctor reports environment state without mutating PATH, shell profiles, shims, package manager config, or project files.
• init does 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.

Limitations

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.

Contributing

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. esbuild is narrowly allowed because Protaction uses it to build the release bundle.

Set up a checkout:

pnpm install
pnpm run build
pnpm link --global

Run local checks:

pnpm test
pnpm run build
pnpm run lint
pnpm run typecheck
pnpm run pack:dry-run

Releases 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.

Documentation

• Product Brief
• Architecture
• Command Design
• CLI Output
• Detection Design
• Shim Design
• Configuration
• Policy And Risk Scoring
• Security Model