Add a Network > Ports page: agent-reported ports plus manual openings

Summarizes every server's agent-reported listening ports in one
cross-server table (grouped by protocol+port, addresses merged,
loopback-only flagged) - previously this only existed per-server on
each server's own detail page.

Adds a second table for ports this app has no way to see on its own:
manually-recorded openings on a router, edge firewall, or cloud
security group, each with a label, external port/protocol, an optional
link to a tracked server (with its own internal port when NAT changes
it) or a freeform destination, a free-text source, and a comment.
Viewer-readable; adding/editing/deleting needs operator or admin.

The agent-port grouping logic (dedupe by protocol+port, detect
loopback-only sockets) was shared with the existing per-server Ports
card via a new agentPorts.ts service instead of duplicating it.

Verified with a real HTTP-level test: a genuine Express app with the
actual routers, a scratch SQLite DB, and forged admin/viewer sessions,
covering grouping correctness, the server-name join, input validation,
and role enforcement - the real dev DB was confirmed untouched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5 committed 2026-09-29 23:48:35 +02:00
1 parent 4e48377348
commit 236b1da0dc
14 files changed
+2486 -39

No files matched your search

+180
View File
@@ -0,0 +1,180 @@
import { Router } from "express";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { db } from "../db/client.js";
import { servers, portForwards } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { type AgentPort, groupAgentPorts, parseJson, splitPortKey } from "../services/agentPorts.js";
import { asyncHandler } from "../utils/asyncHandler.js";
export const portsRouter = Router();
portsRouter.use(requireAuth);
// ─── Ports reported by agents, across every server ──────────────────────────
export interface AgentPortRow {
serverId: number;
serverName: string;
serverHostname: string | null;
protocol: "tcp" | "udp";
port: number;
addresses: string[];
process: string | null;
localOnly: boolean;
lastSeenAt: string | null;
}
portsRouter.get("/agent", asyncHandler(async (_req, res) => {
const rows = await db
.select({ id: servers.id, name: servers.name, hostname: servers.hostname, listeningPorts: servers.listeningPorts, lastSeenAt: servers.lastSeenAt })
.from(servers);
const out: AgentPortRow[] = [];
for (const s of rows) {
const raw = parseJson<AgentPort[] | null>(s.listeningPorts, null);
if (!raw) continue;
for (const [key, grouped] of groupAgentPorts(raw)) {
const { protocol, port } = splitPortKey(key);
out.push({
serverId: s.id,
serverName: s.name,
serverHostname: s.hostname,
protocol,
port,
addresses: grouped.addresses,
process: grouped.process,
localOnly: grouped.localOnly,
lastSeenAt: s.lastSeenAt,
});
}
}
out.sort((a, b) => a.serverName.localeCompare(b.serverName) || a.port - b.port || a.protocol.localeCompare(b.protocol));
res.json({ ports: out, reportingServers: rows.filter((s) => s.listeningPorts !== null).length, totalServers: rows.length });
}));
// ─── Manually-recorded port openings (router/firewall/cloud security group, etc.) ──
// Blank/omitted optional fields normalize to null right here, so every downstream handler can
// just use parsed.data as-is (matching the DB columns, which store NULL, not empty strings).
const optionalText = (max: number) =>
z
.string()
.trim()
.max(max)
.nullish()
.transform((v) => v || null);
const forwardInput = z.object({
label: z.string().trim().min(1).max(200),
externalPort: z.number().int().min(1).max(65535),
protocol: z.enum(["tcp", "udp"]).default("tcp"),
serverId: z
.number()
.int()
.nullish()
.transform((v) => v ?? null),
destination: optionalText(255),
internalPort: z
.number()
.int()
.min(1)
.max(65535)
.nullish()
.transform((v) => v ?? null),
source: optionalText(200),
comment: optionalText(2000),
});
const updateForwardInput = forwardInput.partial();
portsRouter.get("/forwards", asyncHandler(async (_req, res) => {
const rows = await db.query.portForwards.findMany({ orderBy: (p, { asc }) => [asc(p.externalPort)] });
const serverRows = await db.select({ id: servers.id, name: servers.name }).from(servers);
const nameById = new Map(serverRows.map((s) => [s.id, s.name]));
res.json({
forwards: rows.map((r) => ({ ...r, serverName: r.serverId !== null ? nameById.get(r.serverId) ?? null : null })),
});
}));
portsRouter.post("/forwards", requireRole("operator"), asyncHandler(async (req, res) => {
const parsed = forwardInput.safeParse(req.body);
if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
}
const data = parsed.data;
if (data.serverId) {
const [server] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, data.serverId)).limit(1);
if (!server) return res.status(400).json({ error: "invalid_server" });
}
const [created] = await db.insert(portForwards).values(data).returning();
await recordAudit({
actor: req.currentUser!,
category: "network",
action: "create_port_forward",
targetType: "port_forward",
targetId: created.id,
detail: { label: created.label, externalPort: created.externalPort, protocol: created.protocol },
});
res.status(201).json({ forward: created });
}));
portsRouter.patch("/forwards/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = Number(req.params.id);
const parsed = updateForwardInput.safeParse(req.body);
if (!parsed.success) {
return res.status(400).json({ error: "invalid_body", details: parsed.error.flatten() });
}
const data = parsed.data;
const [existing] = await db.select().from(portForwards).where(eq(portForwards.id, id)).limit(1);
if (!existing) return res.status(404).json({ error: "not_found" });
if (data.serverId) {
const [server] = await db.select({ id: servers.id }).from(servers).where(eq(servers.id, data.serverId)).limit(1);
if (!server) return res.status(400).json({ error: "invalid_server" });
}
const [updated] = await db
.update(portForwards)
.set({ ...data, updatedAt: new Date().toISOString() })
.where(eq(portForwards.id, id))
.returning();
await recordAudit({
actor: req.currentUser!,
category: "network",
action: "update_port_forward",
targetType: "port_forward",
targetId: id,
detail: { label: updated.label, externalPort: updated.externalPort, protocol: updated.protocol },
});
res.json({ forward: updated });
}));
portsRouter.delete("/forwards/:id", requireRole("operator"), asyncHandler(async (req, res) => {
const id = Number(req.params.id);
const [existing] = await db.select().from(portForwards).where(eq(portForwards.id, id)).limit(1);
if (!existing) return res.status(404).json({ error: "not_found" });
await db.delete(portForwards).where(eq(portForwards.id, id));
await recordAudit({
actor: req.currentUser!,
category: "network",
action: "delete_port_forward",
targetType: "port_forward",
targetId: id,
detail: { label: existing.label, externalPort: existing.externalPort, protocol: existing.protocol },
});
res.status(204).end();
}));
+1 -39
View File
@@ -6,18 +6,12 @@ import { servers, serverPorts } from "../db/schema.js";
import { requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { beginScan, endScan, MAX_SCAN_SPAN, resolveScanTarget, scanPorts, toRanges } from "../services/portScan.js";
import { type AgentPort, groupAgentPorts, parseJson } from "../services/agentPorts.js";
import { asyncHandler } from "../utils/asyncHandler.js";
// Mounted under /api/servers/:id/ports by the servers router, which has already required a signed-in user.
export const serverPortsRouter = Router({ mergeParams: true });
interface AgentPort {
protocol: "tcp" | "udp";
port: number;
address: string;
process?: string;
}
interface StoredScan {
at: string;
address: string;
@@ -45,38 +39,6 @@ export interface PortEntry {
state: "open" | "reserved";
}
function parseJson<T>(text: string | null | undefined, fallback: T): T {
if (!text) return fallback;
try {
return JSON.parse(text) as T;
} catch {
return fallback;
}
}
function isLoopback(address: string): boolean {
const bare = address.replace(/%.*$/, "").replace(/^\[|\]$/g, "");
return bare.startsWith("127.") || bare === "::1";
}
/** Groups the agent's raw one-row-per-socket report into one entry per protocol+port. */
function groupAgentPorts(raw: AgentPort[]): Map<string, { addresses: string[]; process: string | null; localOnly: boolean }> {
const grouped = new Map<string, { addresses: Set<string>; process: string | null }>();
for (const p of raw) {
const key = `${p.protocol}:${p.port}`;
const entry = grouped.get(key) ?? { addresses: new Set<string>(), process: null };
entry.addresses.add(p.address);
if (!entry.process && p.process) entry.process = p.process;
grouped.set(key, entry);
}
const out = new Map<string, { addresses: string[]; process: string | null; localOnly: boolean }>();
for (const [key, entry] of grouped) {
const addresses = [...entry.addresses];
out.set(key, { addresses, process: entry.process, localOnly: addresses.every(isLoopback) });
}
return out;
}
async function buildPortList(serverId: number) {
const [server] = await db.select().from(servers).where(eq(servers.id, serverId)).limit(1);
if (!server) return null;