Quickstart
Create a firewall, install a package through it, add a delay rule, create an exception, and read the logs. About ten minutes.
This tutorial takes you from nothing to a working npm firewall with one active rule and one exception. Along the way you will touch every core concept: firewalls, upstreams, tokens, rules, exceptions, and logs.
The same pattern applies to every ecosystem: create a firewall, point the package manager at its endpoint, authenticate with a token, then add rules and exceptions. This quickstart uses npm because it is common and keeps the tutorial concrete.
You need access to a namespace in the Bytesafe dashboard and a machine with npm installed.
The examples use <namespace-id> and <firewall-id> placeholders. Replace them with the IDs shown on the firewall's Setup tab, not with namespace or firewall names.
Coming from the previous-generation Bytesafe? Migrate from previous-generation Bytesafe maps your registries, policies, and plugins to the new product.
Create a firewall
In the dashboard, select your namespace, choose npm as the ecosystem, and name the firewall.
The name is only a label. The firewall also gets a generated ID, shown in the firewall list and on the Setup tab. That ID, not the name, is what goes in the endpoint path and in every --firewall flag. The namespace works the same way: the path and BYTESAFE_NAMESPACE use the namespace ID, not its display name.
The new firewall comes with a default upstream pointing at registry.npmjs.org. That is all it needs to start proxying packages.
Create an access token
Package managers authenticate to the firewall with an access token. Access Tokens is not in the main sidebar: open the user menu in the lower-left corner of the dashboard (your name and avatar) and select Access Tokens, then create a personal access token (PAT). Copy the token value: it is shown once.
For CI systems, use a Service Access Token (SAT) instead. See Access Tokens for when to use which.
Configure npm
Point npm at your firewall in the project's .npmrc:
registry=https://eu-sov-1.bytesafecloud.eu/v1/<namespace-id>/npm/<firewall-id>/
//eu-sov-1.bytesafecloud.eu/v1/<namespace-id>/npm/<firewall-id>/:_authToken=${BYTESAFE_TOKEN}The firewall's Setup tab in the dashboard shows an npm snippet with your endpoint, namespace ID, and firewall ID already filled in.
Export the token:
export BYTESAFE_TOKEN=<your token>Keeping the token in an environment variable keeps it out of version control.
Install a package
npm install lodashThe install works as before. The difference: the request went through your firewall, was checked against your rules (none yet), fetched from the upstream, and logged.
Add a delay rule
A delay rule keeps versions younger than a set age out of your builds. The point is to let a release sit in public for a while, so that a malicious version has a chance to be reported and removed before it reaches you.
In the dashboard, open your firewall, go to Rules, and add a rule:
- Execution phase: filter versions (called
versionsin config, API, and CLI) - Selector, max age: 7 days
- Effect: block and log
The same rule as JSON, if you manage config as code:
{
"executionPhase": "versions",
"selector": { "maxAgeHours": 168 },
"ruleEffect": { "block": true, "log": true },
"description": "Block versions younger than 7 days"
}maxAgeHours is a whole number of hours, so 168 is 7 days.
You do not have to use the dashboard for this. Firewalls, rules, and exceptions can also be created from the terminal; see the CLI reference.
See the rule work
Pick any package whose newest version was published in the last few days, and ask for that exact version. Substitute the real name and version for the placeholders below:
npm install some-package@9.9.9Because that version is younger than 7 days, the firewall filters it out of the version list npm sees, and the exact pin fails with No matching version found. Requests that are not pinned keep working:
- A version range, like the
^1.2.3entries inpackage.json, resolves to the newest version older than 7 days and installs fine. npm install some-packagewithout a version does the same: the firewall removes thelatesttag when it points at a filtered version, and npm falls back to the newest allowed version.- A named tag like
@canaryfails as not found when it points at a filtered version.
Add an exception
Suppose you need a fresh release right now, for example a security patch. Instead of weakening the rule, add an exception scoped to that one package version.
In the dashboard, open Exceptions on the firewall and add one:
- Rule: your delay rule
- Package name:
some-package - Version: the exact version you need
- Reason: pick one, for example evaluating component
- Expires: set a date, for example two weeks out
Run the install again. The version resolves, and the exception is recorded in the logs.
Expiring exceptions are the point: the waiver disappears on its own instead of becoming permanent policy nobody remembers.
Read the logs
Every rule match is logged. In the dashboard, open Logs on the firewall to see requests, matched rules, and block decisions.
From the terminal, with the bsfw CLI:
export BYTESAFE_ENDPOINT=https://eu-sov-1.bytesafecloud.eu
export BYTESAFE_NAMESPACE="<namespace-id>"
bsfw logs --firewall <firewall-id> --tail--tail streams new entries live. Trigger an install in another terminal and watch the entries arrive.
Where to go next
- Set up npm properly for your team and CI, including yarn, pnpm, and Bun.
- Block vulnerable packages with CVSS and EPSS thresholds.
- Rule evaluation explains how phases, selectors, and exceptions fit together.
What is a dependency firewall?
How the Bytesafe Dependency Firewall works, what it protects against, and where it fits next to SCA tools and repository managers.
Access Tokens
Personal Access Tokens (PAT), Service Access Tokens (SAT), and Trusted Builders with OpenID Connect (OIDC). Which one to use where, and how to create them.