DOCSEARCHbyAlgolia
Submit Docs

Bytesafe Dependency Firewall

website·Indexed 34 days ago

https://docs.bytesafe.dev/

A preventive control system for managing third-party dependencies. It allows organizations to block vulnerable, deprecated, or malicious packages, prevent dependency confusion, and restrict install-time code execution. The platform integrates with repository managers like JFrog Artifactory, Sonatype Nexus, GitLab, GitHub Packages, and Azure Artifacts, and supports ecosystems including Composer, Cargo, and OCI containers.

Tokens
64.7K
Snippets
194
Records
446
Agent score
66%

What's inside Bytesafe

  1. Overview of the ByteSafe Audit Log

    The audit log records control-plane actions, including configuration and policy changes, token and team management, permission denials, and OIDC exchanges. It is used to determine 'who changed the firewall', whereas the firewall log tracks 'what happened to a package request'. Each namespace has its own audit log, and events cannot be edited or deleted via the API.

  2. Overview of Firewall Selector Functions

    A selector function is a computed condition in a firewall rule that matches what is known about a package (e.g., vulnerabilities, malware, or license status) rather than its identity (name, version). A selector can contain at most one function, which is combined with plain fields using a logical AND operation.
    {
  "function": {
    "name": "vulnerabilities",
    "options": { "maxCvssScore": 9.0, "maxEpssScore": 0.5 }
  }
}

  3. Overview of migrating from previous-generation Bytesafe to Dependency Firewall

    The previous generation of Bytesafe combined a firewall with a hosted package registry. The new Dependency Firewall is a standalone security control that checks every request against rules in real-time.

    Key architectural changes:

    • Policy: Moves from policies and plugins to a unified Rule model.
    • Private Packages: Move from Bytesafe hosted registries to a repository manager (e.g., Artifactory, Nexus, GitLab, GitHub Packages, Azure Artifacts, or AWS CodeArtifact).
    • End of Life: The previous generation of Bytesafe reaches end of life on December 31, 2026.

  4. Overview of Bytesafe Dependency Firewall

    The Bytesafe Dependency Firewall acts as a policy checkpoint between package managers and public registries. Instead of installing packages directly from sources like npmjs.org or PyPI, tools install through a firewall endpoint. The firewall fetches packages from configured upstreams, evaluates defined rules, and either serves or blocks the package at install time, preventing malicious or vulnerable code from reaching developer machines or CI runners.

  5. Overview of Firewall Execution Phases

    The firewall operates in three distinct execution phases based on the request made by the package manager to the registry. Every rule runs in exactly one of these phases. The choice of phase determines whether a rule can 'steer' the package manager to a different version or if it must fail the request entirely.

    Package Manager NeedRequest MadePhaseRule Capability
    Find existing versionsVersion listversionsRemove specific versions from the response list
    Get a specific filePackage filedownloadServe the file or fail the request
    Publish a fileUploaduploadAccept or reject the publish request

  6. Overview of Firewall Observability Records

    The firewall maintains four distinct types of records to provide visibility into traffic, configuration, and usage. These records overlap but answer different questions:

    • Firewall log: Answers 'What happened to this package request, and which rule decided?'. It records one entry per logged rule decision and upstream failures.
    • Audit log: Answers 'Who changed configuration, policy, tokens, or teams?'. It records one event per control-plane action.
    • Metrics: Answers 'How much traffic/blocking occurred over time?'. It provides time-bucketed counters.
    • Observations: Answers 'Which packages and versions are actually in use?'. It records one row per package version seen in real traffic.

  7. Overview of planned OCI Container Firewall capabilities

    Bytesafe is developing a container firewall for OCI registries (planned for Q4 2026). The system will act as a registry proxy positioned in front of image sources to evaluate pulls against defined rules before images reach build agents or nodes. Supported registries will include Docker Hub, GitHub Container Registry, AWS ECR, Google Artifact Registry, and private OCI registries.

    Key planned capabilities include:

    • Vulnerability Blocking: Blocking images with known CVEs in base layers or bundled packages based on CVSS and EPSS thresholds.
    • Content Scanning: Scanning image contents for malware and secrets.
    • Rule-based Control: Applying block or log effects based on image name, tag pattern, registry source, and image age, including time-limited exceptions.
    • Auditability: Logging and auditing of every pull, block, and exception.

  8. Understand the ByteSafe audit log event structure

    The audit log records control-plane actions within a namespace, tracking activities related to firewalls, tokens, teams, webhooks, and Trusted Builders. Each event is represented as a JSON object containing metadata about the actor, the request, and the outcome of the action.
    {
  "id": "01J...",
  "createdAt": "2026-07-03T10:22:41Z",
  "namespace": "ns-01KYA296JWEE36NDNRTJ4KM82Q",
  "action": "firewall.rule.upsert",
  "resourceType": "firewall",
  "resourceId": "3e7f5cb806f26e3beae2",
  "actorUserId": "user-7d2f...",
  "actorTokenIdentifier": "5f8a...",
  "requestId": "8f4c2e...",
  "interactionId": "build-4711",
  "remoteAddr": "203.0.113.7",
  "userAgent": "bsfw/1.4.0",
  "requestMethod": "PUT",
  "requestPath": "/v1/ns-01KYA296JWEE36NDNRTJ4KM82Q/config/3e7f5cb806f26e3beae2/rules/delay-14d",
  "outcome": "success",
  "statusCode": 200,
  "eventData": { "rule": "delay-14d" }
}

  9. Understand the firewall rule evaluation process

    Firewall rules are evaluated based on 'cost' (cheapest first), not by their configuration order. Rules of equal cost maintain their configuration order.

    Evaluation flow:

    1. Match Rule: The system checks if the rule's selector matches the request and if any active, non-expired exceptions apply. If an exception matches, the rule is skipped.
    2. Apply Effect:
      • If log: true, a log entry is written, and evaluation continues to the next rule.
      • If block: true, the request is blocked immediately, and evaluation ends.
    3. Completion: If no rules block the request, it is allowed.

    Because blocking ends evaluation, the rule recorded in the log is the cheapest rule that matched, not necessarily the first one configured.

  10. Choose between Bytesafe Dependency Firewall SaaS and Self-Hosted deployment

    The Bytesafe Dependency Firewall can be deployed in two ways. Both models use the same rules, ecosystems, CLI, and API, but differ in where the proxy runs and who operates it.

    SaaS (Default):

    • Operated by Bytesafe.
    • Package traffic flows through Bytesafe infrastructure.
    • Upstream credentials are encrypted at rest.
    • Recommended for the fastest setup and zero operational overhead.

    Self-Hosted (Your own infrastructure):

    • Operated by the customer in their own datacenter or cloud account.
    • Package traffic and upstream credentials never leave the customer's perimeter.
    • Supports internal registries that are unreachable from the internet.
    • Required for organizations with strict data residency or network topology policies.

  11. Understand inherited firewall rule fields

    When querying inherited firewall rules via /rules/inherited, the API provides metadata about the source of the rule and whether it has been overridden.

    Source Metadata:

    • sourceFirewall: ID of the firewall where the entry is defined.
    • sourceFirewallName: Display name of the source firewall.
    • sourceFirewallVersion: Version of the source firewall's configuration.

    Override Status (present if a nearer firewall declares the same ID):

    • overridden: Boolean indicating if this upstream rule is not in effect.
    • overriddenBy: ID of the nearer firewall whose upstream rule is currently in effect.

    Permission Metadata (present on /rules and /rules/inherited):

    • canAddException: Boolean indicating if the current token has permission to add an exception to this rule.
    • exceptionDeniedReason: Provided when canAddException is false. Possible values include:
      • missing_child_permission: Caller lacks fw:update:exception on the current firewall.
      • missing_owner_permission: Caller lacks permission on the source firewall that owns the rule.
      • ambiguous_rule_id: The rule ID is not unique across the firewall and its parents.

  12. Understand firewall event data fields

    Firewall events provide details about the decision made for a package request. Key fields include:

    • firewall and firewallVersion: The firewall that made the decision and the configuration version used.
    • executionPhase: Indicates if the phase was download or upload.
    • blocked: Boolean indicating if the request was blocked.
    • ecosystem, packageName, version: The package details associated with the decision.
    • upstream: The upstream that served (or would have served) the package.
    • rule: The rule that matched the request.
    • user: Opaque user ID of the requester.
    • request: Request ID (corresponds to the blocked-install error message seen by clients).
    • message: Rule description or specific findings (e.g., malware detection details).
    • sourceFirewall and sourceFirewallVersion: Present if the rule was inherited from another firewall.
    • exception, exceptionSourceFirewall, exceptionSourceFirewallVersion: Present on firewall.exception-allowed events to identify the exception that permitted the request.
    • published: The publish date of the version upstream.
    • output: Rule-specific details such as vulnerability IDs, scores, or malware scanner confidence/signals.
    • interaction: Interaction ID from the token suffix.
    • userAgent and remoteAddress: Client metadata.