Firewall for npm guide

Review public npm verdicts, enforce a policy, and configure authenticated CI checks.

LPM Firewall checks selected public npm versions. In enforce mode, LPM CLI waits for each verdict before it materializes the package bytes. In monitor mode, downloads continue while the check runs, and the verdicts are reported before the command finishes. The hosted verdict service requires eligible LPM.dev Registry Pro or organization access.

lpm login
lpm config firewall --set monitor
lpm install

Monitor mode reports warnings and packages that enforcement would block. After reviewing those results, enable enforcement:

lpm config firewall --set enforce
lpm install

Metadata and package downloads still use the normal registry routes. Firewall verdicts use a separate authenticated request through LPM.dev Registry.

Choose a mode

Mode	Verdict and availability behavior
`off`	No hosted verdict request. This is the default.
`monitor`	Report warnings and would-block decisions. Downloads do not wait for verdicts. Authentication, entitlement, and network failures produce warnings.
`enforce`	Stop for effective block decisions or unavailable checks. Warning decisions allow the command to continue.

Monitor mode does not suppress other installation errors or security policies. A failed dependency resolution can still stop the command.

Use lpm config without --set for interactive policy selection:

lpm config firewall

Save policy configuration

Firewall configuration belongs in the global configuration, rather than lpm.json:

~/.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"
lpm_ai_suspicious = "warn"

For one command:

LPM_NPM_FIREWALL=enforce lpm ci --strict-integrity

An approved machine posture can require a stronger mode. A weaker environment or global setting does not automatically override that requirement.

Policy groups

Group	Default action	Evidence
`trusted_public_malicious_advisories`	`block`	Public malicious-package advisories.
`lpm_ai_confirmed_malware`	`block`	Malware behavior confirmed by LPM Firewall analysis.
`lpm_ai_agent_control_surface`	`warn`	Unexpected changes to agent skills, hooks, commands, or configuration during installation.
`critical_vulnerability`	`warn`	Critical vulnerability advisories.
`lpm_ai_suspicious`	`warn`	Suspicious signals without confirmed malware classification.

Policy groups accept allow, warn, or block. The interactive editor normally offers warn or allow for suspicious signals.

LPM Firewall evaluates the supplied profile and returns the effective action. An unknown verdict does not prove that a package is safe.

Understand the scope

Eligible public npm versions are checked during these workflows:

lpm install, including lpm ci
lpm global install
lpm fetch
lpm download
The source download in lpm add

Private registry packages, custom registry packages, and @lpm.dev/* packages do not enter the public npm verdict request.

The verdict check does not route npm downloads through a hosted tarball proxy. It also does not replace vulnerability audits or lifecycle-script controls.

Read a decision

! LPM Firewall warned for 1 package:
  › example-package@1.0.0 - warn: Package source requires review.
    report: https://firewall.lpm.dev/npm/example-package/v/1.0.0

A decision includes the package, version, action, and reason. Available reports link to the evidence for that version.

For a monitor-mode block decision, the output says that the package would be blocked and the command continues.

JSON output can include policy and authority metadata. Older records can omit those fields.

Use CI credentials

For a CI token stored in the platform's secret store:

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

The token must belong to an eligible account or organization. Install permission alone does not establish Firewall entitlement.

Supported CI identities can also exchange an OIDC assertion for a read token. See CI/CD setup for trust configuration and token audiences.

Combine online checks with offline installation

First, populate the store and perform the hosted check online:

LPM_NPM_FIREWALL=enforce lpm fetch

An enforced Firewall check cannot run offline. Monitor mode skips the hosted check with a warning.

A later offline installation does not receive fresh verdicts. Disabling enforcement for that step requires an explicit policy decision and any required signed approval.

--offline limits package-network work. It is not a network sandbox for root lifecycle scripts.

Recover from a blocked command

Cause	Action
Effective block decision	Read the report and select a reviewed version or dependency replacement.
Missing credentials	Use lpm login or correct the CI identity configuration.
Missing entitlement	Check the account or organization coverage.
Service or network failure in enforce mode	Restore connectivity and repeat the command.
Unexpected policy action	Review the global profile and managed security policy.

Changing a group to allow changes enforcement. It does not remove the underlying evidence.

Firewall for npm