Skip to main content

StackBob On-Prem Bridge architecture and security

Concept · On-Prem Bridge

Written by Agent Bob

StackBob On-Prem Bridge connects StackBob.ai to managed apps that run inside your private network and cannot be reached from the internet, such as on-premises and internally hosted web applications. The bridge runs as a container in your network and maintains a single outbound, encrypted connection to StackBob.ai. StackBob NCAP™ uses this connection to reach only the apps you configure. The bridge requires no inbound firewall rules, no VPN, and no changes to your network perimeter.

This article describes the architecture of the bridge, its network requirements, and its security controls. It is intended for the security, network, and architecture teams that review the bridge before deployment. For installation steps, see Deploy a StackBob On-Prem Bridge.

✅ Apps that are reachable over HTTPS from the internet do not require a bridge. They connect through a Direct Internet Connection (Direct Sync).
See Quickstart: Connect your first managed app.


Key facts

Item

Detail

Inbound firewall rules

None. The bridge requires no port forwarding, public IP addresses, or DMZ changes.

Outbound firewall rules

TCP 443 from the bridge host to bridge.stackbob.ai

Network access

The bridge is not a VPN. StackBob.ai does not join your network and receives no routes into it. The bridge opens individual TCP connections to the apps you configure.

Use of SSH

SSH is used only to encrypt and multiplex traffic inside the tunnel. There is no SSH server, shell access, command execution, file access, or open port 22.

App traffic

For HTTPS apps, TLS is established directly between the StackBob NCAP™ browser and the app. The bridge and the gateway cannot decrypt this traffic.

Image integrity

Each image is signed by the CI pipeline that built it and is published with an SBOM and build provenance. Signatures can be verified with cosign.

Deactivation

Stopping the container directly closes the tunnel immediately. Alternatively you can revoke the bridge node via StackBob.ai platform (the tunnel will be closed within 30 seconds).

Footprint on your host

A single static binary in a minimal container image. It runs as a non-root user, with no shell and no published ports.

Supported hosts

The default Linux image runs on Linux (x86-64 or ARM64), macOS, and Windows 10 or 11. For Windows Server and Kubernetes Windows nodes, a Windows container image is available on request.


Components

The architecture consists of three components:

  • StackBob On-Prem Bridge. A container that runs on a host in your network. It establishes an outbound connection to the StackBob.ai gateway and keeps it open. Each running instance is a bridge node. A bridge can also include a backup node on a second host for failover.

  • StackBob.ai gateway. The StackBob.ai cloud service that authenticates bridge nodes and routes traffic from the NCAP™ Integration to the correct tunnel.

  • StackBob NCAP™ Integration. The deterministic integration that StackBob.ai creates for the managed app. It runs in an isolated headless browser in StackBob.ai’s cloud. It signs in to the app with the service account you provide and performs the configured operations.

ℹ️ The container image is published as stackbob-bridge in the Amazon ECR Public Gallery, and the gateway address is bridge.stackbob.ai.


How a connection is established

  1. On startup, the bridge opens an outbound WebSocket connection to wss://bridge.stackbob.ai on port 443. To your network, this is a standard outbound TLS connection.

  2. The bridge verifies the gateway’s identity in two ways. First, it validates the gateway’s public TLS certificate. Then it performs an SSH handshake inside TLS and compares the gateway’s key with a fingerprint compiled into the bridge. If the key does not match, the bridge terminates the connection. A misissued certificate or a TLS-inspecting proxy therefore cannot impersonate StackBob.ai.

  3. After both checks succeed, the bridge presents its enrollment token. The gateway validates the token against a stored hash and binds the tunnel to that bridge node within your organization.

  4. The tunnel remains idle until it is needed. Both sides exchange keepalives every 25 seconds, so a lost tunnel is detected within approximately 35 seconds. The bridge then reconnects automatically.

  5. Before an operation runs against a managed app, the NCAP™ Integration requests a reachability probe through the gateway. The bridge attempts a TCP connection to the app host, optionally with a TLS handshake, and returns the result. Connectivity failures are reported as specific errors, such as host unreachable or TLS failed, instead of browser timeouts.

  6. The NCAP™ Integration’s browser sends an HTTP CONNECT request through the gateway. The gateway then instructs the bridge to open a TCP connection to the app’s host and port. The bridge resolves the hostname using your internal DNS, establishes the connection, and relays traffic in both directions. The browser then completes its own TLS handshake with the app through the tunnel.

  7. When the operation completes, the TCP connection is closed. The tunnel remains available for subsequent operations.

Your internal DNS resolves the hostnames, so internal app names do not need to be published in public DNS.

Protocol layers

TCP 443 ← the only connection your firewall sees

└─ TLS 1.2 / 1.3 ← public certificate, verified by the bridge

└─ WebSocket ← compatible with web proxies and load balancers

└─ SSH transport ← second encryption layer, gateway key pinned

└─ channels ← one per relayed TCP connection

└─ app TLS ← NCAP™ Integration to app, end to end
​

Between your network and StackBob.ai, HTTPS app traffic is encrypted in three layers. The innermost layer is the app’s own TLS session with the NCAP™ Integration’s browser. The bridge and the gateway relay that session without decrypting it.

The SSH transport protocol provides encryption, integrity protection, and multiplexing of connections over a single tunnel. No SSH server runs in your network. SSH also allows the bridge to pin the gateway’s key without relying on public certificate authorities.


Supported hosts

The bridge is distributed as a Docker container image. You can run it on a Linux server or virtual machine with Docker, on a Kubernetes cluster, or on macOS or Windows 10 and 11 with Docker Desktop.

ℹ️ If your environment cannot run Docker containers, for example a Windows Server host, contact StackBob.ai support. We will work with you to provide a suitable deployment option.

Network requirements

All rules apply to the bridge host.

Direction

Destination

Port

Purpose

Outbound

bridge.stackbob.ai

TCP 443

Tunnel connection

Internal

Managed app hosts

App port, such as 443

Connections to managed apps

Internal

Internal DNS

53

Hostname resolution

Outbound, installation and upgrades only

public.ecr.aws

TCP 443

Image download. Not required if you mirror the image to an internal registry.

Inbound

—

—

None

The bridge does not listen on any port. If your firewall policy requires IP-based rules, StackBob.ai can provide the gateway’s static IP address.

Proxies and TLS inspection

If outbound traffic must pass through a corporate proxy, set HTTPS_PROXY on the bridge. The proxy must permit WebSocket traffic over CONNECT to bridge.stackbob.ai:443. The bridge reaches managed apps directly, so they do not need to be added to NO_PROXY.

StackBob.ai recommends excluding bridge.stackbob.ai from TLS inspection. If inspection is required, add your inspection CA to the container with SSL_CERT_FILE. The inspection device then sees only the SSH-encrypted stream and cannot read the

enrollment token or app traffic.

⚠️ The tunnel fails if the proxy rejects the WebSocket upgrade or delays keepalive responses by more than 10 seconds. The second case appears as repeated reconnects on an otherwise healthy link.


Security controls

Bridge and container

The bridge consists of fewer than 1,000 lines of Go, and its source code is available for review on request. It features are limited only to the following:

  • Maintain the outbound tunnel.

  • Open TCP connections at the gateway’s request.

  • Test app reachability.

  • Report its version and hostname for support.

It cannot accept inbound connections, run commands, access files on the host, store data, be reconfigured remotely, or update itself.

The default image is built on distroless/static and contains no shell or package manager. The bridge runs as a non-root user and publishes no ports. Its only third-party dependencies are golang.org/x/crypto/ssh and coder/websocket.

Image signing

Each image is signed by StackBob.ai’s CI pipeline using keyless Sigstore cosign. Each image also carries a signed SPDX SBOM and an SLSA provenance record. Signing requires an OIDC token that only StackBob.ai’s CI jobs can obtain, so stolen registry credentials are not sufficient to publish a validly signed image. Docker does not verify signatures automatically. The verification command is described in the Deploy a StackBob On-Prem Bridge article.

Authentication and credentials

  • Each bridge node has its own 256-bit enrollment token, which is displayed once. StackBob.ai stores only a SHA-256 hash of the token, so the token cannot be retrieved later.

  • The bridge sends the token only inside the SSH layer, after it verifies the gateway’s key. The token is never visible to proxies or inspection devices.

  • Generating a new installation command invalidates the node’s previous token. Revoking a node in StackBob.ai closes its tunnel within approximately 30 seconds.

  • Production and non-production environments use separate gateway keys and registries. Published images cannot disable certificate verification or key pinning.

  • The bridge never handles app credentials. Service account credentials are encrypted in StackBob Vault and are used only inside the NCAP™ Integration’s TLS session with the app.

⚠️ For apps served over plain http://, the tunnel encrypts traffic between your network and StackBob.ai. However, the gateway relays that traffic unencrypted within StackBob.ai’s private network. To maintain end-to-end encryption, serve the app over HTTPS.

Tenant isolation

Every relayed connection names a bridge node and an organization. Connections are pooled per tunnel and are never rerouted through another node or organization. The gateway’s internal proxy is reachable only from StackBob.ai’s private network. Its public endpoint enforces handshake deadlines and per-IP rate limits, and it accepts TLS 1.2 or 1.3 only.

Logging

  • The gateway logs each relayed connection: the organization, bridge node, target host:port, bytes transferred, and duration. It does not log content.

  • The bridge logs to stdout and stderr as text, or as JSON with STACKBOB_LOG_FORMAT=json, for SIEM ingestion. If its token is invalid or revoked, it exits with code 3.

  • StackBob.ai displays each bridge node’s status, last heartbeat, and last error.


Deployment recommendations

  • Run the bridge on a dedicated, patched Linux server or virtual machine that is covered by your EDR tools.

  • Segment the host so that it can reach only DNS and the managed apps that StackBob.ai needs to integrate with. This is the most effective control over what the bridge can reach.

  • Restrict Docker access on the host, because the token is passed as an environment variable. Alternatively, provide the token as a file with STACKBOB_TOKEN_FILE.

  • Verify the image signature. If you mirror the image, use cosign copy, which preserves the signatures.

  • For high availability, add a backup bridge node on a second host (see the Deploy a StackBob On-Prem Bridge).


Add-ons and Limitations

Item

Status

Destination allowlist enforced by the bridge

Available on request

Apps with certificates issued by an internal CA

Available on request

Windows Integrated Authentication (Kerberos, NTLM)

Not currently available


Next steps

Did this answer your question?