View logs

A rule match with logging enabled produces a log entry: who requested which package, through which firewall, which rule fired, and whether the request was blocked. Logs are the place to answer "why did this install fail" and "what would this rule have blocked". They are not a record of every request; see What is logged when below.

In the dashboard

Open Logs on a firewall. Each entry shows the timestamp, the block decision, the execution phase (versions, download, or upload), the package and version, the matched rule, and the user. Users appear by name where the dashboard can resolve them; service tokens and removed users show the raw ID. From a log entry you can create an exception directly, prefilled with the rule and package.

Select a row to see the complete entry. The detail includes fields not shown as table columns, such as request, interaction, upstream, and, when applicable, the source firewall or exception.

The newest entries load first. Load more at the bottom of the table fetches the next batch of older entries, so you can page back as far as the retained history goes. New entries arriving while you page do not shift or duplicate the ones already on screen.

From the terminal

The bsfw CLI reads the same log the dashboard shows. Its table is a compact view built for scanning, so it leaves out some fields; add -o json or -o ndjson to get complete entries, including the request, exception, source firewall, and upstream IDs.

One thing to know before the first run: without --all-users, you only see your own requests. A CI token has no user behind it, so it sees nothing at all unless you pass --all-users.

export BYTESAFE_ENDPOINT=https://eu-sov-1.bytesafecloud.eu
export BYTESAFE_NAMESPACE="<namespace-id>"
export BYTESAFE_TOKEN=<your token>

bsfw logs --firewall <firewall-id>

Filter entries

bsfw logs --all-users --blocked --since 24h
bsfw logs --firewall <firewall-id> --phase download --search lodash

--blocked narrows the list to requests the firewall stopped, which is where a reported install failure is usually found. --search matches on user, ecosystem, package, version, and message, so the package name from the error message is a good search term.

--since takes a duration counted back from now (30m, 24h, 168h) or a point in time (2026-08-01, or an RFC 3339 timestamp). There is no day unit, so a week is 168h. See dates and durations.

Stream live

bsfw logs --firewall <firewall-id> --follow

--follow keeps the connection open and prints entries as they happen. Useful while testing a new rule: run the install in one terminal and watch the decision in the other. A stream starts from the newest entries and goes forward, so --since and --limit have no effect on it; the other filters do.

Filter by user

bsfw logs --user user-7d2f...
bsfw logs --all-users

--user and --all-users are mutually exclusive, and --user takes the raw user ID, not a name or email. Omit both to see your own entries.

Read complete entries

bsfw logs --firewall <firewall-id> --search lodash -o json
bsfw logs --all-users --follow -o ndjson

-o json returns the whole response as one document, which suits a saved report. -o ndjson writes one complete entry per line, which is what to use with --follow or when piping into jq or a log collector.

Correlate CI runs

Log entries record the interaction ID when the token carries one (<token>::<id>, see Access Tokens). Set it to the pipeline run ID in CI and every package request from that run shares the ID.

What is logged when

• A rule with log: true writes an entry on every match, blocked or not. A log-only rule (block: false, log: true) is the standard way to trial a policy before enforcing it.
• An exception with log: true writes an entry when it lets a request through. The complete entry identifies the exception.
• A rule with log: false writes nothing, even when it blocks the request. If an install fails with no entry to show for it, this is the first thing to check.
• Requests that match no rule are not logged at all. An empty log means no rule had anything to say, not that no packages were installed.

To see traffic that no policy rule covers, add a rule matching all packages with { "block": false, "log": true }. That is also the quickest way to confirm a client really is going through the firewall.

See what was actually downloaded

The firewall log answers "which rule decided this", not "what did we download". A successful install that broke no rule leaves nothing behind, by design: the log exists so a developer can find out why something was blocked.

Two ways to get the download record instead:

• Observations are the ready-made answer. Each row is a package version the firewall has served, with when and how often, built from real traffic rather than from what manifests declare. Nothing to configure.

  bsfw observations --period 30d --firewall <firewall-id>

• A match-all log-only rule turns the firewall log itself into a full request trail, at the cost of an entry per request. Use it when you want the log's fields, such as the identity and interaction ID on each request, rather than an inventory.

Neither is the audit log, which records control-plane actions: who changed configuration, policy, tokens, and teams.

Related

• How-to: Investigate a blocked install
• Reference: CLI