Firewall for npm

The npm firewall checks selected public npm package versions with firewall.lpm.dev before LPM materializes package bytes. Metadata and tarballs still come from the normal npm registry path; the firewall request only asks for a package-version verdict.

The hosted verdict service is an LPM Pro/org feature. Active modes send LPM auth; run lpm login locally, or use LPM_TOKEN / registry-audience OIDC in CI.

Quickstart

lpm login
lpm config firewall --set monitor  # show would-block / warn verdicts
lpm config firewall --set enforce  # block according to the recommended policy profile

off is the default. monitor prints verdicts and lets installs continue. enforce blocks packages whose effective firewall action is block. The legacy string report is still accepted as an alias for monitor, but new config should use monitor.

For guided setup, run the wizard without --set:

lpm config firewall

What gets checked

The firewall runs for eligible public npm package-version rows used by:

• lpm install
• lpm install -g
• lpm fetch
• lpm download
• the source-package download step of lpm add

Private/custom registry packages and lpm.dev packages are not sent to the npm firewall verdict API. Integrity-specific evidence can be attached to a verdict, but the fast product path is the package-version lookup.

Modes

When a human-output materialization command has eligible packages to check, its progress line shows 🔥 LPM Firewall active.

CI usage

Firewall checks run for lpm install, lpm ci, lpm fetch, lpm download, and the source-package download step of lpm add. Because the verdict check calls firewall.lpm.dev, an active firewall check cannot run under --offline.

Static-token CI can enable the firewall for one command with LPM_NPM_FIREWALL:

- run: LPM_NPM_FIREWALL=enforce lpm ci --strict-integrity
  env:
    LPM_TOKEN: ${{ secrets.LPM_TOKEN }}

OIDC-capable CI can avoid storing LPM_TOKEN. When firewall mode is active and no existing bearer or refreshable stored session is available, LPM exchanges a registry-audience OIDC token for a short-lived LPM token before calling the verdict API. If LPM_TOKEN or stored auth is already available, the OIDC exchange is skipped.

permissions:
  id-token: write
  contents: read

jobs:
  install:
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @lpm-registry/cli
      - run: LPM_NPM_FIREWALL=enforce lpm ci --strict-integrity

install:
  id_tokens:
    LPM_OIDC_TOKEN:
      aud: https://lpm.dev
  script:
    - npm install -g @lpm-registry/cli
    - LPM_NPM_FIREWALL=enforce lpm ci --strict-integrity

For offline replay workflows, run the firewall during the online fetch step instead:

- run: LPM_NPM_FIREWALL=enforce lpm fetch
- run: lpm ci --offline --strict-integrity

Policy groups

LPM receives a default verdict from firewall.lpm.dev, then sends your configured policy profile with the request. The registry evaluates the profile server-side and returns the user-effective action for each decision.

Choosing enforce in the interactive wizard opens a single policy review screen. Press Enter to accept the recommended profile, or use the arrow keys to change individual groups before saving.

  current: enforce
◇  How should LPM handle firewall verdicts for npm packages?
│  enforce
│
◆  Review npm firewall enforcement policy
│  Use ↑/↓ to move, ←/→ to change, Enter to save, Esc to cancel.
│
│  › Trusted public malicious advisories
│    OSV / OpenSSF / GHSA
│    ● Block  ○ Warn only  ○ Allow
│
│    LPM AI-confirmed malware
│    Credential/data exfiltration, RCE, remote payload execution, persistence, dependency confusion
│    ● Block  ○ Warn only  ○ Allow
│
│    LPM AI-agent control-surface policy
│    Silent install-lifecycle writes into foreign or broad AI-agent control surfaces
│    ○ Block  ● Warn only  ○ Allow
│
│    Critical vulnerabilities
│    Legitimate package risk without malicious author intent
│    ○ Block  ● Warn only  ○ Allow
│
│    Static-only suspicious signals
│    No AI or trusted advisory confirmation yet
│    ● Warn only  ○ Allow
└

The equivalent config lives in ~/.lpm/config.toml:

[firewall]
mode = "enforce"

[firewall.npm.policies]
trusted_public_malicious_advisories = "block"
lpm_ai_confirmed_malware = "block"
lpm_ai_agent_control_surface = "warn"
critical_vulnerability = "warn"
static_only_suspicious = "warn"

Use lpm config firewall in an interactive terminal to choose:

• Off
• Monitor only
• Enforce, then review the policy profile

The wizard writes the policy table only when the chosen profile differs from the default profile, or when an existing policy table needs to be updated.

AI-agent control-surface policy

LPM flags silent install-lifecycle writes into foreign or broad AI-agent control surfaces because a transitive npm install should not mutate another agent's skills, commands, hooks, MCP config, or startup surface without an explicit user command. The recommended profile warns by default; teams that want stricter containment can set this group to block.

This policy is version-scoped and remediable. A package can move setup into an explicit command such as <tool> setup or <tool> init, then the changed version can be evaluated under a weaker action. See firewall.lpm.dev/policy for the public policy text.

Monitor and JSON output

In monitor mode, LPM never blocks installs. If the registry returns an effective block, human output says it would block and the command continues.

When JSON output includes firewall decisions, each decision can include optional policy and authority metadata:

{
  "action": "block",
  "verdict": "malicious",
  "policy": {
    "group": "lpm_ai_agent_control_surface",
    "key": "ai_agent_control_surface",
    "intent": "dangerous_capability",
    "default_action": "warn"
  },
  "authority": {
    "source": "lpm_ai",
    "source_type": "lpm",
    "external_intel": false
  }
}

Older firewall records can omit policy and authority. Those records fall back to the plain verdict behavior.

See also

• lpm config — interactive and non-interactive setup
• CI/CD setup — token and OIDC examples
• ~/.lpm/config.toml — exact config keys
• lpm install — install-time behavior
• Public firewall policy