Firewall config

The firewall config is the complete description of one firewall: identity, upstreams, policy, and access grants. It is what bsfw config export writes and bsfw config import applies, and what the dashboard edits piece by piece.

Shape

{
  "id": "3e7f5cb806f26e3beae2",
  "version": 12,
  "ecosystem": "npm",
  "name": "npm production",
  "description": "Firewall for all production npm installs",
  "upstreams": [
    {
      "id": "npmjs",
      "endpoint": "https://registry.npmjs.org",
      "credentials": {},
      "internal": false,
      "cached": false
    }
  ],
  "publishTarget": "npmjs",
  "rules": [
    {
      "id": "delay-new-versions",
      "executionPhase": "versions",
      "selector": { "maxAgeHours": 168 },
      "ruleEffect": { "block": true, "log": true },
      "description": "Block versions younger than 7 days"
    }
  ],
  "exceptions": [],
  "permissions": {
    "everybody": ["fw:access", "fw:clone", "fw:read"],
    "platform": ["fw:access", "fw:read", "fw:update:rule", "fw:update:exception"]
  },
  "updatedAt": "2026-07-02T09:30:00Z"
}

Fields

With parentId set, the stored config keeps holding only the firewall's own entries; inherited rules, exceptions, and upstreams are resolved from the parent chain at serving time. Exports and the granular rule/exception endpoints operate on the firewall's own entries only.

Firewall ID

The ID is a path segment in every client-facing URL, so it is constrained to characters that need no escaping:

• Letters, digits, and dashes only
• Must start and end with a letter or digit, so no leading dash (which reads as a flag on a command line) and no trailing dash
• At most 128 characters

The server rejects anything else with 400. The rule applies to every config write, not just creation, so an existing firewall with a non-conforming ID cannot carry it forward through an import. The dashboard generates conforming IDs on its own.

Import semantics

bsfw config import PUTs the whole object:

• Importing a config with a new id creates the firewall (requires fw:create).
• Importing an existing id replaces its configuration.
• Plaintext values in credentials are rejected. On an existing firewall, an exported placeholder keeps the stored value for the same upstream. When a new firewall ID or upstream has no stored value, the placeholder resolves to empty; set its credentials separately through the dashboard or bsfw config credentials.
• The ecosystem must be one of the supported values. Rules and exceptions whose selector function or version range does not support that ecosystem are rejected.
• The permissions map is optional on create. Without one, the server applies the defaults for a new firewall. The create request body also accepts an owner field (a team ID, not stored on the config): the named team receives the full default permission set instead of the everybody team.
• A permissions map that would leave no team with fw:update:config, or would drop the caller's own ability to update the configuration, is rejected; see Permissions.

See CLI.

Related

• Reference: Upstreams, Rules and selectors, Exceptions, Permissions, CLI
• How-to: Configure upstreams