mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-28 11:17:07 +00:00
feat: Compose Network Inspector and exposure intent guard (#1360)
* feat: add Compose Network Inspector facts engine Render a stack's authored effective model and pair it with the live Docker snapshot to derive per-stack networking facts: project networks with external and internal flags, service-to-network membership and aliases, published ports with host-binding scope, network_mode, and extra_hosts, plus runtime drift (runtime-only attachments, foreign networks, and declared-but-unused or missing networks). Extend the effective-model parser with service network membership, extra_hosts, and label keys (key names only, never values), and add a key-space normalized network model with adapters from both the rendered model and the raw declared compose so the Inspector and drift share one comparison. Expose GET /api/stacks/:stackName/networking: advisory and read-only, it renders the authored model only and never returns or logs raw stderr, env values, or label values. * feat: store and edit per-stack and per-service exposure intent Add a stack_exposure_intent table (intent values constrained by a CHECK, unique per node, stack, and service) with DAO methods to read, upsert, clear one row, and clear all rows for a stack. The classification is stored independently of the generated networking facts so a later mismatch stays detectable; service rows are kept separately from the stack-level row (service ''). Expose GET and PUT /api/stacks/:stackName/exposure: GET requires read access, PUT requires edit access and validates the intent against the allowed set. Sending intent null clears that row, returning the scope to unset so a service inherits the stack intent again. Intent rows are cleared when the stack is deleted and when the owning node is removed, so a later same-named stack never picks up stale classification. * feat: add exposure-aware Compose Doctor findings Feed the Compose Doctor's effective-model context with the stored exposure intent (resolved into a stack-level value plus per-service overrides) and the dossier's documented access-URL ports, read fail-soft so a metadata read error skips these checks rather than failing the preflight. Add five deterministic findings on top of that context: - a service classified internal or same-node that publishes a host port (same-node tolerates a loopback bind), - a sensitive database or admin image published on all interfaces, - a port-publishing stack with no exposure intent set, - a published port not reflected in the documented access URLs, - reverse-proxy labels with no documented URL or reverse-proxy intent. The rules stay pure functions over the preflight context; the registry completeness test pins the new rule set. * feat: detect compose network drift in the drift ledger Extend the spatial drift engine with two network-level findings: a running container attached to a stack-owned or foreign network that compose does not declare (one finding per service), and a declared network that no running service uses or that is absent from the runtime (one stack-level finding, every network named by its resolved runtime name). The comparison reuses the same helper the Network Inspector uses, so the two surfaces never disagree. Network drift runs only when the stack has running containers and the runtime is reachable, preserving the existing missing-runtime, parse-error, and unreachable behavior. The findings persist through the existing drift ledger and surface on the Drift tab, which now labels the two new kinds. * feat: link a Docker network back to its owning stack Add a cross-component open-stack event and make the owning-stack badge on a managed network in Resources a link: clicking it loads that stack on its node and opens the editor, reusing the existing fleet navigation. A latest-ref keeps the window listener current without re-subscribing each render. Image and volume badges are unchanged; only a managed network opts in via the new optional handler. * feat: add the Networking tab to the stack detail panel Add a capability-gated Networking tab that reads the per-stack networking facts and exposure intent. It shows the project networks (with external, internal, and created-by-stack flags), per-service network membership and aliases, published ports with their host-binding scope, network_mode and extra_hosts, and runtime drift, degrading to the declared model when the runtime is unavailable. Users can classify the stack and each service (internal, LAN, reverse proxy, public, and so on) or clear a row to inherit; the controls are read-only when the user cannot edit, and a broken exposure response never tears down the facts view. A new compose-networking capability is added to both registries so older nodes hide the tab, and the tab cross-links to the Doctor for the deploy and security findings. * docs: document the Compose Networking tab Add a feature page covering the Networking tab: the network facts, published ports and host bindings, the exposure-intent classification and inheritance, the exposure-aware Doctor findings, runtime drift, and a troubleshooting section. Register it in the docs navigation next to Compose Doctor. * feat: add a redacted network summary to the Stack Dossier export Append a network exposure section to the dossier Markdown: the stack and per-service exposure intents, the networks with their external and internal flags, and each service's published ports with their binding scope. It carries only names, intents, port numbers, and scope, never an env value or a label value. The summary is fetched only when the user exports (copy or download), so opening the panel costs nothing, and it degrades to omitting the section when the data is unavailable. The whole-fleet dossier export collects the same summary per stack, rethrowing the unauthorized sentinel like the sibling loaders. * feat: add a Fleet networking filter for exposure and drift Add a per-node networking summary that classifies a node's stacks as exposed (a host port published beyond loopback), unknown-exposure (publishes ports with no exposure intent set), or network-drift. It reads each stack's compose with the light dependency parser and one Docker snapshot, so it stays cheap across a node's full stack set, and it skips drift when the runtime is unreachable rather than inventing it. Serve it node-locally at GET /api/networking/summary, and aggregate it fleet-wide at GET /api/fleet/networking-summary: the hub computes its own summary in-process and reaches each remote through its node-local route, degrading an unreachable or older node to a skip. Because the aggregate lives under the proxy-exempt /api/fleet prefix it is never wrongly proxied. The Fleet overview gains a networking filter chip backed by that aggregate, fetched fail-soft and detached so it never gates the grid. * fix: spin the Networking refresh button while it reloads The refresh button silently refetched the same data, so a click gave no feedback. Track a refreshing state and spin the icon while the load is in flight, disabling the button, matching the Compose Doctor preflight button. * fix: apply effective per-service exposure intent to unclassified checks The "unclassified exposure" decisions only consulted the stack-level intent row, so a service classified directly (with no stack row) was still reported as unclassified, and a service explicitly marked unknown over a classified stack was missed. Both the exposure-unclassified preflight rule and the networking summary's unknown-exposure bucket now resolve the effective intent per publishing service (service row overrides stack row), matching the precedence already used by the exposure-internal-published rule. * fix: resolve drift network names via the compose top-level name When a compose file sets a top-level name:, Docker prefixes resource names with that project name instead of the stack directory. The light dependency parser dropped name:, so network-drift normalization compared runtime networks against directory-prefixed names and reported false network-undeclared / network-missing findings. Carry the parsed project name through DeclaredCompose and use it when normalizing declared networks for drift, while still filtering containers by the stack directory.
This commit is contained in:
Anso
@@ -8,6 +8,7 @@ import { ControlIdentityMismatchError, FleetSyncService, StaleSyncPushError } fr
|
||||
import { MAX_SYNC_ROWS, SYNC_ERROR_CODES } from '../services/fleetSyncConstants';
|
||||
import { FleetUpdateTrackerService, type UpdateTracker, type TerminalStatus, UPDATE_TIMEOUT_MS, UPDATE_TIMEOUT_MSG, TERMINAL_TTL_MS } from '../services/FleetUpdateTrackerService';
|
||||
import { NodeRegistry } from '../services/NodeRegistry';
|
||||
import { computeNodeNetworkingSummary, type NodeNetworkingSummary } from '../services/network/networkingSummary';
|
||||
import DockerController from '../services/DockerController';
|
||||
import { FileSystemService } from '../services/FileSystemService';
|
||||
import { ComposeService } from '../services/ComposeService';
|
||||
@@ -702,6 +703,75 @@ fleetRouter.get('/dependency-map', authMiddleware, async (_req: Request, res: Re
|
||||
}
|
||||
});
|
||||
|
||||
interface FleetNetworkingSummaryNode {
|
||||
nodeId: number;
|
||||
nodeName: string;
|
||||
status: 'ok' | 'error';
|
||||
summary: NodeNetworkingSummary | null;
|
||||
error: string | null;
|
||||
}
|
||||
|
||||
function isNodeNetworkingSummary(v: unknown): v is NodeNetworkingSummary {
|
||||
if (!v || typeof v !== 'object') return false;
|
||||
const o = v as Record<string, unknown>;
|
||||
return (['exposed', 'unknownExposure', 'networkDrift'] as const).every(k => {
|
||||
const b = o[k] as { count?: unknown; stacks?: unknown } | undefined;
|
||||
return !!b && typeof b.count === 'number' && Array.isArray(b.stacks);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Fleet-wide networking summary for the overview filter. Auth-only (read-only,
|
||||
* Community). Hub-exempt under /api/fleet, so it is never proxied: it builds the
|
||||
* hub's summary in-process and reaches each remote through its node-local
|
||||
* /api/networking/summary route. A remote on an older version (no route) returns
|
||||
* 404 and degrades to a skip, so one unreachable or unsupported node never fails
|
||||
* the filter for the rest.
|
||||
*/
|
||||
fleetRouter.get('/networking-summary', authMiddleware, async (_req: Request, res: Response): Promise<void> => {
|
||||
try {
|
||||
const db = DatabaseService.getInstance();
|
||||
const nodes = db.getNodes();
|
||||
|
||||
const results = await Promise.allSettled(
|
||||
nodes.map(async (node: Node): Promise<FleetNetworkingSummaryNode> => {
|
||||
if (node.type === 'local') {
|
||||
const summary = await computeNodeNetworkingSummary(node.id);
|
||||
return { nodeId: node.id, nodeName: node.name, status: 'ok', summary, error: null };
|
||||
}
|
||||
const target = NodeRegistry.getInstance().getProxyTarget(node.id);
|
||||
if (!target) {
|
||||
return { nodeId: node.id, nodeName: node.name, status: 'error', summary: null, error: formatNoTargetError(node) };
|
||||
}
|
||||
const resp = await fetch(
|
||||
`${target.apiUrl.replace(/\/$/, '')}/api/networking/summary`,
|
||||
{ headers: { ...(target.apiToken ? { Authorization: `Bearer ${target.apiToken}` } : {}) }, signal: AbortSignal.timeout(15000) },
|
||||
);
|
||||
if (!resp.ok) {
|
||||
return { nodeId: node.id, nodeName: node.name, status: 'error', summary: null, error: `Remote returned ${resp.status}` };
|
||||
}
|
||||
const summary = await resp.json().catch(() => null);
|
||||
if (!isNodeNetworkingSummary(summary)) {
|
||||
console.error(`[Fleet] Networking summary: node ${sanitizeForLog(node.name)} returned an unexpected payload (status ${resp.status})`);
|
||||
return { nodeId: node.id, nodeName: node.name, status: 'error', summary: null, error: 'Remote returned an unexpected summary payload' };
|
||||
}
|
||||
return { nodeId: node.id, nodeName: node.name, status: 'ok', summary, error: null };
|
||||
}),
|
||||
);
|
||||
|
||||
const perNode: FleetNetworkingSummaryNode[] = results.map((result, i) => {
|
||||
if (result.status === 'fulfilled') return result.value;
|
||||
console.error(`[Fleet] Networking summary fetch failed for node ${nodes[i].name}:`, result.reason);
|
||||
return { nodeId: nodes[i].id, nodeName: nodes[i].name, status: 'error', summary: null, error: getErrorMessage(result.reason, 'Failed to reach node') };
|
||||
});
|
||||
|
||||
res.json({ nodes: perNode });
|
||||
} catch (error) {
|
||||
console.error('[Fleet] Networking summary error:', error);
|
||||
res.status(500).json({ error: 'Failed to build fleet networking summary' });
|
||||
}
|
||||
});
|
||||
|
||||
fleetRouter.get('/node/:nodeId/stacks', authMiddleware, async (req: Request, res: Response): Promise<void> => {
|
||||
try {
|
||||
const nodeId = parseIntParam(req, res, 'nodeId', 'node ID');
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
import { Router, type Request, type Response } from 'express';
|
||||
import { computeNodeNetworkingSummary } from '../services/network/networkingSummary';
|
||||
import { getErrorMessage } from '../utils/errors';
|
||||
import { sanitizeForLog } from '../utils/safeLog';
|
||||
|
||||
export const networkingRouter = Router();
|
||||
|
||||
// Node-local networking summary for the Fleet view filter. Auth-only and
|
||||
// read-only (Community). The fleet aggregate computes the hub's summary by
|
||||
// calling the underlying service in-process and reaches each remote through
|
||||
// this route, so a remote is summarized on the node that owns its stacks.
|
||||
networkingRouter.get('/summary', async (req: Request, res: Response): Promise<void> => {
|
||||
try {
|
||||
res.json(await computeNodeNetworkingSummary(req.nodeId));
|
||||
} catch (error) {
|
||||
console.error('[Networking] Failed to build node summary:', sanitizeForLog(getErrorMessage(error, 'unknown')));
|
||||
res.status(500).json({ error: 'Failed to build networking summary' });
|
||||
}
|
||||
});
|
||||
@@ -16,6 +16,8 @@ import { enforcePolicyPreDeploy } from '../services/PolicyEnforcement';
|
||||
import { buildStackDriftReport, type DriftFindingKind, type StackDriftReport } from '../services/DriftDetectionService';
|
||||
import { DriftLedgerService, type DriftTemporal } from '../services/DriftLedgerService';
|
||||
import { ComposeDoctorService } from '../services/ComposeDoctorService';
|
||||
import { buildStackNetworkFacts } from '../services/network/composeNetworkInspector';
|
||||
import { EXPOSURE_INTENTS, type ExposureIntent } from '../services/network/types';
|
||||
import { UpdateGuardService } from '../services/UpdateGuardService';
|
||||
import { HealthGateService } from '../services/HealthGateService';
|
||||
import { classifyFailure } from '../services/updateGuard/failureClassifier';
|
||||
@@ -950,6 +952,7 @@ stacksRouter.delete('/:stackName', async (req: Request, res: Response) => {
|
||||
DatabaseService.getInstance().deleteGitSource(stackName);
|
||||
DatabaseService.getInstance().deleteStackDossier(req.nodeId, stackName);
|
||||
DatabaseService.getInstance().deleteStackDriftFindings(req.nodeId, stackName);
|
||||
DatabaseService.getInstance().deleteStackExposureIntents(req.nodeId, stackName);
|
||||
if (debug) console.debug(`[Stacks:debug] Delete: db OK`, { stackName: sanitizedName });
|
||||
} catch (dbErr) {
|
||||
console.error('[Stacks] Database cleanup failed for %s; files already removed:', sanitizeForLog(stackName), dbErr);
|
||||
@@ -1127,6 +1130,82 @@ stacksRouter.post('/:stackName/preflight/run', async (req: Request, res: Respons
|
||||
}
|
||||
});
|
||||
|
||||
// Compose Network Inspector: per-stack networking facts (network map, service
|
||||
// membership, published ports/bindings, network_mode, extra_hosts, runtime
|
||||
// drift) derived from the authored effective model + live snapshot. Read-only
|
||||
// and advisory; auto-proxies to the active node. Never returns raw render
|
||||
// stderr, env values, or label values.
|
||||
stacksRouter.get('/:stackName/networking', async (req: Request, res: Response) => {
|
||||
const stackName = req.params.stackName as string;
|
||||
if (!requirePermission(req, res, 'stack:read', 'stack', stackName)) return;
|
||||
if (!(await requireStackExists(req.nodeId, stackName, res))) return;
|
||||
try {
|
||||
res.json(await buildStackNetworkFacts(req.nodeId, stackName));
|
||||
} catch (error) {
|
||||
console.error('[Stacks] Failed to build networking facts for %s:', sanitizeForLog(stackName),
|
||||
sanitizeForLog(inspect(error, { depth: 4 })));
|
||||
res.status(500).json({ error: 'Failed to build networking facts' });
|
||||
}
|
||||
});
|
||||
|
||||
// Exposure intent: the user's per-stack (service '') and per-service exposure
|
||||
// classification, stored separately from generated facts so mismatches stay
|
||||
// detectable. Rows are stored independently; precedence (a service row taking
|
||||
// priority over the stack row, an absent service row inheriting the stack
|
||||
// intent) is applied by the consumers that read these rows, not enforced here.
|
||||
// Clearing a row (intent null) deletes it, returning that scope to unset.
|
||||
const ExposurePutSchema = z.object({
|
||||
service: z.string().max(255).optional().default(''),
|
||||
intent: z.enum(EXPOSURE_INTENTS).nullable(),
|
||||
});
|
||||
|
||||
function exposurePayload(nodeId: number, stackName: string): {
|
||||
intents: { service: string; intent: ExposureIntent; updatedAt: number; updatedBy: string | null }[];
|
||||
} {
|
||||
return {
|
||||
intents: DatabaseService.getInstance().getStackExposureIntents(nodeId, stackName).map(r => ({
|
||||
service: r.service, intent: r.intent, updatedAt: r.updated_at, updatedBy: r.updated_by,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
stacksRouter.get('/:stackName/exposure', async (req: Request, res: Response) => {
|
||||
const stackName = req.params.stackName as string;
|
||||
if (!requirePermission(req, res, 'stack:read', 'stack', stackName)) return;
|
||||
if (!(await requireStackExists(req.nodeId, stackName, res))) return;
|
||||
try {
|
||||
res.json(exposurePayload(req.nodeId, stackName));
|
||||
} catch (error) {
|
||||
console.error('[Stacks] Failed to read exposure intent for %s:', sanitizeForLog(stackName),
|
||||
sanitizeForLog(getErrorMessage(error, 'unknown')));
|
||||
res.status(500).json({ error: 'Failed to read exposure intent' });
|
||||
}
|
||||
});
|
||||
|
||||
stacksRouter.put('/:stackName/exposure', async (req: Request, res: Response) => {
|
||||
const stackName = req.params.stackName as string;
|
||||
if (!requirePermission(req, res, 'stack:edit', 'stack', stackName)) return;
|
||||
if (!(await requireStackExists(req.nodeId, stackName, res))) return;
|
||||
const parsed = ExposurePutSchema.safeParse(req.body);
|
||||
if (!parsed.success) {
|
||||
res.status(400).json({ error: 'Invalid exposure intent' });
|
||||
return;
|
||||
}
|
||||
const { service, intent } = parsed.data;
|
||||
try {
|
||||
if (intent === null) {
|
||||
DatabaseService.getInstance().deleteStackExposureIntent(req.nodeId, stackName, service);
|
||||
} else {
|
||||
DatabaseService.getInstance().setStackExposureIntent(req.nodeId, stackName, service, intent, req.user?.username ?? null);
|
||||
}
|
||||
res.json(exposurePayload(req.nodeId, stackName));
|
||||
} catch (error) {
|
||||
console.error('[Stacks] Failed to save exposure intent for %s:', sanitizeForLog(stackName),
|
||||
sanitizeForLog(getErrorMessage(error, 'unknown')));
|
||||
res.status(500).json({ error: 'Failed to save exposure intent' });
|
||||
}
|
||||
});
|
||||
|
||||
// Update guard: readiness reports computed on demand from existing stores
|
||||
// (preflight runs, drift findings, backup slot, update preview, live Docker
|
||||
// state). Node-scoped like preflight: a remote stack is evaluated on the node
|
||||
|
||||
Reference in New Issue
Block a user