browser-private-port-probe

browser-private-port-probe is a browser-focused TypeScript library for probing ports on localhost and private-network hosts. It does not use raw TCP sockets. Instead, it combines WebSocket, fetch, and resource-loading strategies and returns full evidence for each port so the caller can see what the browser observed.

Why Is This Interesting?

Without using extensions like Port Authority websites can scan your entire network, from your own browser. It's not as complete as a full port scan, but it can indicate that certain services are running on your network, which could be very unique to you and be used a way to fingerprint you, or worse. Attackers can get a general idea of how your network is laid out, prior to ever accessing it.

It could reveal information like that you're on a different private subnet, which could reveal information about a users location. A user VPNed into a corporate network gives them the same external ip, but if you fingerprinted them based on open ports and what private subnet they are on it would be easier to determine if they are at home or in the office.

That is to say, situations where a (public) IP address is supposed to kept hidden, location can be determined in some cases. If it were to be used on something like the Tor network, authorities would be able to determine if 2 different users are in fact the same person, in some circumstances. Networks with unique equipment on them or a unique static arrangement of devices or services could act as a fingerprint, depending on the degree of uniqueness.

The scans also take place on the users network(s), bypassing firewall configurations that trust that device to access resources that others cannot. For example if this were to be run on an application server and the databases are on a subnet that only can be accessed by that application server, then you've effectively transversed 2 subnets as part of your information gathering.

What It Does

• Probes localhost, loopback, and RFC1918 private-network targets.
• Combines multiple browser-safe strategies per port.
• Returns evidence, latency, hints, and a merged confidence classification.
• Supports single-host, multi-host, IPv4 range, and small CIDR scans.
• Includes a Vite demo that exposes the full runtime configuration.

What It Does Not Do

• It does not perform raw TCP scanning.
• It does not target public internet hosts in the first release.
• It does not promise security-scanner-grade accuracy.
• It does not perform service fingerprinting or authenticated probing.

Install

npm install browser-private-port-probe

Usage

import { Scanner } from "browser-private-port-probe";

const scanner = new Scanner({
  target: {
    hosts: ["localhost", "192.168.1.10"],
  },
  ports: {
    values: [80, 443, 3000, 5173, 8080],
  },
  strategies: {
    sampleCount: 3,
    stopOnHighConfidence: true,
  },
  execution: {
    networkConcurrency: 128,
    workerCount: "all",
  },
});

scanner.addEventListener("progress", (event) => {
  console.log("progress", event);
});

const summary = await scanner.scan();
console.log(summary.results);

Result Shape

Each result contains:

• host
• port
• status
• confidence
• latencyMs
• hints
• evidence[]

Evidence items include the strategy name, attempt number, duration, URL, error text, and lightweight protocol hints.

Demo

npm install
npm run dev:demo

That starts a local web server for the demo at http://127.0.0.1:4173.

To serve the built demo locally instead:

npm run build:demo
npm run serve:demo

Build And Test

npm run lint
npm run test
npm run build
npm run build:demo

Important Browser Limits

This package is still bound by browser security and networking behavior.

• Mixed-content rules can block HTTP or ws:// probes from secure pages.
• Cross-origin policies can hide response details.
• Browser-specific private-network restrictions can affect local scans.
• A failed browser probe does not always mean the port is truly closed.

That is why the library returns full evidence instead of reducing every port to a single opaque boolean.