@elinpf/dsh-ops-tool-environment 0.1.0

package/lib/relations.js

@@ -0,0 +1,146 @@
+/**
+ * Best-effort relation edges between scanned resources.
+ *
+ * Sources of truth, in order of strength:
+ *
+ * - `fronts` — a Service whose pod selector is a subset of a workload's pod
+ *   template labels fronts that workload. Deterministic, from k8s itself.
+ * - `uses-service` — a literal `env` value or a data value of a referenced
+ *   ConfigMap contains a `<name>.<namespace>.svc[.cluster.local]` address
+ *   that resolves to a scanned Service.
+ * - `uses-middleware` — composition of the two above: a workload that uses
+ *   a Service which fronts a recognized middleware instance.
+ * - `references-secret` — envFrom/valueFrom secret references, NAME only.
+ *   Secret values are never read anywhere in this package.
+ *
+ * Everything here is best-effort: a value that parses to nothing produces
+ * no edge and no error. A missing ConfigMap, a dangling Service name, a
+ * selector-less Service — all simply yield no edge.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import { isMiddlewareType } from './classify.js';
+/**
+ * Matches `<name>.<namespace>.svc` and `<name>.<namespace>.svc.cluster.local`
+ * inside arbitrary text (URLs, JDBC strings, bare hosts). Only the
+ * namespace-qualified forms — the short in-namespace form is too ambiguous.
+ */
+const SVC_PATTERN = /\b([a-z0-9](?:[a-z0-9-]*[a-z0-9])?)\.([a-z0-9](?:[a-z0-9-]*[a-z0-9])?)\.svc(?:\.cluster\.local)?\b/gi;
+function workloadRef(w) {
+    return { kind: w.kind, namespace: w.namespace, name: w.name };
+}
+function serviceRef(s) {
+    return { kind: 'Service', namespace: s.namespace, name: s.name };
+}
+function keyOf(ref) {
+    return `${ref.kind}/${ref.namespace}/${ref.name}`;
+}
+/** Extract distinct (name, namespace) Service addresses mentioned in a text value. */
+export function findServiceAddresses(value) {
+    const found = new Map();
+    for (const match of value.matchAll(SVC_PATTERN)) {
+        const name = match[1].toLowerCase();
+        const namespace = match[2].toLowerCase();
+        found.set(`${namespace}/${name}`, { name, namespace });
+    }
+    return [...found.values()];
+}
+/** A Service fronts a workload when its selector is a subset of the pod template labels. */
+function selectorMatches(selector, podLabels) {
+    return Object.entries(selector).every(([k, v]) => podLabels[k] === v);
+}
+/** Derive all relation edges for one scanned cluster. Never throws. */
+export function buildRelations(input) {
+    try {
+        const { scan, classified } = input;
+        const edges = [];
+        const seen = new Set();
+        const push = (edge) => {
+            const id = `${edge.kind}|${keyOf(edge.from)}|${keyOf(edge.to)}|${edge.via}`;
+            if (!seen.has(id)) {
+                seen.add(id);
+                edges.push(edge);
+            }
+        };
+        const servicesByKey = new Map();
+        for (const svc of scan.services)
+            servicesByKey.set(keyOf(serviceRef(svc)), svc);
+        // Service -> workload ownership edges, and the reverse index for composition.
+        const frontsByService = new Map();
+        for (const svc of scan.services) {
+            if (!svc.selector)
+                continue;
+            for (const w of classified) {
+                if (w.namespace !== svc.namespace)
+                    continue;
+                if (!selectorMatches(svc.selector, w.podLabels))
+                    continue;
+                push({ kind: 'fronts', from: serviceRef(svc), to: workloadRef(w), via: 'selector' });
+                const list = frontsByService.get(keyOf(serviceRef(svc))) ?? [];
+                list.push(w);
+                frontsByService.set(keyOf(serviceRef(svc)), list);
+            }
+        }
+        const configMapsByKey = new Map(scan.configMaps.map(cm => [`${cm.namespace}/${cm.name}`, cm]));
+        for (const w of classified) {
+            const from = workloadRef(w);
+            // Plaintext env values.
+            for (const [key, value] of Object.entries(w.env)) {
+                for (const addr of findServiceAddresses(value)) {
+                    const svc = servicesByKey.get(`Service/${addr.namespace}/${addr.name}`);
+                    if (!svc)
+                        continue;
+                    push({ kind: 'uses-service', from, to: serviceRef(svc), via: `env:${key}` });
+                }
+            }
+            // Data values of ConfigMaps this workload references.
+            for (const cmName of w.configMapRefs) {
+                const cm = configMapsByKey.get(`${w.namespace}/${cmName}`);
+                if (!cm)
+                    continue;
+                for (const [key, value] of Object.entries(cm.data)) {
+                    for (const addr of findServiceAddresses(value)) {
+                        const svc = servicesByKey.get(`Service/${addr.namespace}/${addr.name}`);
+                        if (!svc)
+                            continue;
+                        push({ kind: 'uses-service', from, to: serviceRef(svc), via: `configmap:${cmName}:${key}` });
+                    }
+                }
+            }
+            // Secret references — the name only, never a value.
+            for (const secretName of w.secretRefs) {
+                push({
+                    kind: 'references-secret',
+                    from,
+                    to: { kind: 'Secret', namespace: w.namespace, name: secretName },
+                    via: 'secretRef',
+                });
+            }
+        }
+        // Compose: workload uses a Service that fronts a middleware instance.
+        const middlewareTypes = new Map();
+        for (const w of classified) {
+            if (isMiddlewareType(w.type))
+                middlewareTypes.set(keyOf(workloadRef(w)), w.type);
+        }
+        for (const edge of edges.filter(e => e.kind === 'uses-service')) {
+            for (const instance of frontsByService.get(keyOf(edge.to)) ?? []) {
+                const type = middlewareTypes.get(keyOf(workloadRef(instance)));
+                if (!type)
+                    continue;
+                push({
+                    kind: 'uses-middleware',
+                    from: edge.from,
+                    to: workloadRef(instance),
+                    via: edge.via,
+                    targetType: type,
+                });
+            }
+        }
+        return edges;
+    }
+    catch {
+        // Best-effort by contract: a malformed scan must never break the inventory.
+        return [];
+    }
+}

package/lib/scanner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cluster scanner — the read side of the environment inventory.
+ *
+ * Runs `kubectl --kubeconfig <path> get ... -o json` for workloads
+ * (deploy/sts/ds), services, ingresses, configmaps, and secrets, and reduces
+ * the responses to a {@link ClusterScan} of plain data. No files are written
+ * here; classification and persistence live elsewhere.
+ *
+ * Security discipline (hard rules):
+ * - Secrets are read metadata-only: the kubectl call selects only
+ *   namespace/name via jsonpath, so `data`/`stringData` never enters the
+ *   process, let alone the inventory.
+ * - The kubeconfig path never appears in thrown errors — kubectl echoes it
+ *   in stderr, so every error is scrubbed before it propagates.
+ * - Container env values: only literal `value` entries are captured;
+ *   `valueFrom` contributes reference names (configMapKeyRef/secretKeyRef),
+ *   never resolved values.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { SpawnFn } from './prometheus.js';
+import type { ClusterScan } from './types.js';
+/** Injectable command runner: argv (no shell) -> captured stdout. Throws on failure. */
+export type ExecFn = (args: string[], opts: {
+    timeoutMs: number;
+}) => Promise<{
+    stdout: string;
+}>;
+export declare const SCAN_TIMEOUT_MS = 30000;
+/** A cluster scan failure. The message is always kubeconfig-path-scrubbed. */
+export declare class ScanError extends Error {
+    /** The cluster profile id this failure belongs to. */
+    readonly cluster: string;
+    constructor(message: string, 
+    /** The cluster profile id this failure belongs to. */
+    cluster: string);
+}
+/** Default runner: spawn kubectl with argv, capture stdout/stderr, 30s timeout. */
+export declare const defaultExec: ExecFn;
+export interface ScanClusterInput {
+    /** Cluster profile id — the only cluster identity that appears in output. */
+    cluster: string;
+    /** Real kubeconfig path. Used in argv only; never surfaced in output/errors. */
+    kubeconfigPath: string;
+    /** Injectable exec for tests; defaults to spawning kubectl. */
+    exec?: ExecFn;
+    /** Injectable port-forward spawn (tests); defaults to node:child_process. */
+    spawn?: SpawnFn;
+    /** Injectable fetch (tests); defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /** Scan timestamp; defaults to now (injectable for deterministic tests). */
+    now?: Date;
+    /** Per-kubectl-call timeout (ms); defaults to SCAN_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Prometheus scrape timeout (ms); defaults to the scrape's own 15s. */
+    prometheusTimeoutMs?: number;
+}
+/** Replace every occurrence of the kubeconfig path with a display token. */
+export declare function scrubKubeconfigPath(text: string, kubeconfigPath: string): string;
+/**
+ * Scan one cluster. All resource reads run against the same kubeconfig; any
+ * failure (unreachable cluster, timeout, malformed response) rejects with a
+ * ScanError whose message never contains the kubeconfig path.
+ */
+export declare function scanCluster(input: ScanClusterInput): Promise<ClusterScan>;

package/lib/scanner.js

@@ -0,0 +1,333 @@
+/**
+ * Cluster scanner — the read side of the environment inventory.
+ *
+ * Runs `kubectl --kubeconfig <path> get ... -o json` for workloads
+ * (deploy/sts/ds), services, ingresses, configmaps, and secrets, and reduces
+ * the responses to a {@link ClusterScan} of plain data. No files are written
+ * here; classification and persistence live elsewhere.
+ *
+ * Security discipline (hard rules):
+ * - Secrets are read metadata-only: the kubectl call selects only
+ *   namespace/name via jsonpath, so `data`/`stringData` never enters the
+ *   process, let alone the inventory.
+ * - The kubeconfig path never appears in thrown errors — kubectl echoes it
+ *   in stderr, so every error is scrubbed before it propagates.
+ * - Container env values: only literal `value` entries are captured;
+ *   `valueFrom` contributes reference names (configMapKeyRef/secretKeyRef),
+ *   never resolved values.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import { spawn } from 'node:child_process';
+import { scrapePrometheusTargets } from './prometheus.js';
+export const SCAN_TIMEOUT_MS = 30_000;
+/** A cluster scan failure. The message is always kubeconfig-path-scrubbed. */
+export class ScanError extends Error {
+    cluster;
+    constructor(message, 
+    /** The cluster profile id this failure belongs to. */
+    cluster) {
+        super(message);
+        this.cluster = cluster;
+        this.name = 'ScanError';
+    }
+}
+/** Default runner: spawn kubectl with argv, capture stdout/stderr, 30s timeout. */
+export const defaultExec = (args, { timeoutMs }) => new Promise((resolve, reject) => {
+    const child = spawn(args[0], args.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        reject(new Error(`command timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.on('error', (err) => {
+        clearTimeout(timer);
+        reject(err);
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        if (code === 0) {
+            resolve({ stdout: Buffer.concat(stdout).toString('utf8') });
+        }
+        else {
+            reject(new Error(`kubectl exited with code ${code ?? 'null'}: ${Buffer.concat(stderr).toString('utf8').trim()}`));
+        }
+    });
+});
+/** Replace every occurrence of the kubeconfig path with a display token. */
+export function scrubKubeconfigPath(text, kubeconfigPath) {
+    return text.split(kubeconfigPath).join('<kubeconfig>');
+}
+function parseList(json, what) {
+    try {
+        const doc = JSON.parse(json);
+        if (!doc || !Array.isArray(doc.items))
+            throw new Error('missing .items');
+        return doc;
+    }
+    catch (err) {
+        throw new Error(`cannot parse ${what} response: ${err.message}`);
+    }
+}
+function asLabels(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+function reduceWorkload(kind, item) {
+    const meta = item.metadata ?? {};
+    const podSpec = item.spec?.template?.spec ?? {};
+    const containers = [...(podSpec.containers ?? []), ...(podSpec.initContainers ?? [])];
+    const images = [];
+    const env = {};
+    const configMapRefs = new Set();
+    const secretRefs = new Set();
+    for (const container of containers) {
+        if (typeof container.image === 'string')
+            images.push(container.image);
+        for (const entry of container.env ?? []) {
+            // Literal values only — valueFrom entries contribute reference names below.
+            if (typeof entry?.name === 'string' && typeof entry?.value === 'string') {
+                env[entry.name] = entry.value;
+            }
+            const cmKeyRef = entry?.valueFrom?.configMapKeyRef;
+            if (typeof cmKeyRef?.name === 'string')
+                configMapRefs.add(cmKeyRef.name);
+            const secretKeyRef = entry?.valueFrom?.secretKeyRef;
+            if (typeof secretKeyRef?.name === 'string')
+                secretRefs.add(secretKeyRef.name);
+        }
+        for (const from of container.envFrom ?? []) {
+            if (typeof from?.configMapRef?.name === 'string')
+                configMapRefs.add(from.configMapRef.name);
+            // Secret reference: record the NAME only. Values are never touched.
+            if (typeof from?.secretRef?.name === 'string')
+                secretRefs.add(from.secretRef.name);
+        }
+    }
+    return {
+        kind,
+        namespace: meta.namespace ?? 'default',
+        name: meta.name ?? '',
+        images,
+        labels: asLabels(meta.labels),
+        podLabels: asLabels(item.spec?.template?.metadata?.labels),
+        env,
+        configMapRefs: [...configMapRefs].sort(),
+        secretRefs: [...secretRefs].sort(),
+    };
+}
+function reduceService(item) {
+    const meta = item.metadata ?? {};
+    const spec = item.spec ?? {};
+    const ports = (spec.ports ?? []).map((p) => {
+        const port = { port: p?.port };
+        if (p?.targetPort !== undefined)
+            port.targetPort = p.targetPort;
+        if (typeof p?.name === 'string')
+            port.name = p.name;
+        return port;
+    }).filter((p) => typeof p.port === 'number');
+    const selector = spec.selector && Object.keys(spec.selector).length > 0 ? asLabels(spec.selector) : null;
+    const svc = {
+        namespace: meta.namespace ?? 'default',
+        name: meta.name ?? '',
+        type: spec.type ?? 'ClusterIP',
+        ports,
+        selector,
+        labels: asLabels(meta.labels),
+    };
+    if (typeof spec.clusterIP === 'string' && spec.clusterIP !== 'None')
+        svc.clusterIP = spec.clusterIP;
+    if (typeof spec.externalName === 'string')
+        svc.externalName = spec.externalName;
+    return svc;
+}
+function reduceIngress(item) {
+    const meta = item.metadata ?? {};
+    const hosts = new Set();
+    const serviceBackends = [];
+    for (const rule of item.spec?.rules ?? []) {
+        if (typeof rule?.host === 'string')
+            hosts.add(rule.host);
+        for (const path of rule?.http?.paths ?? []) {
+            const svc = path?.backend?.service;
+            if (typeof svc?.name !== 'string')
+                continue;
+            const backend = { serviceName: svc.name };
+            const port = svc.port?.number ?? svc.port?.name;
+            if (port !== undefined)
+                backend.servicePort = port;
+            serviceBackends.push(backend);
+        }
+    }
+    return {
+        namespace: meta.namespace ?? 'default',
+        name: meta.name ?? '',
+        hosts: [...hosts].sort(),
+        serviceBackends,
+    };
+}
+function reduceConfigMap(item) {
+    const meta = item.metadata ?? {};
+    const data = {};
+    for (const [k, v] of Object.entries(item.data ?? {})) {
+        if (typeof v === 'string')
+            data[k] = v;
+    }
+    return { namespace: meta.namespace ?? 'default', name: meta.name ?? '', data };
+}
+/** Endpoints reduced to ready-address count (subsets[].addresses; notReady excluded). */
+function reduceEndpoints(item) {
+    const meta = item.metadata ?? {};
+    let addresses = 0;
+    for (const subset of item.subsets ?? []) {
+        addresses += (subset?.addresses ?? []).length;
+    }
+    return { namespace: meta.namespace ?? 'default', name: meta.name ?? '', addresses };
+}
+/**
+ * Metadata-only Secret list. The scanner asks kubectl for a jsonpath of
+ * `namespace<TAB>name` per item so Secret data never crosses into this
+ * process. Malformed lines are skipped (best-effort, never fatal).
+ */
+function parseSecretNames(output) {
+    const secrets = [];
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const tab = trimmed.indexOf('\t');
+        if (tab <= 0)
+            continue;
+        secrets.push({ namespace: trimmed.slice(0, tab), name: trimmed.slice(tab + 1) });
+    }
+    return secrets;
+}
+const SECRETS_JSONPATH = '{range .items[*]}{.metadata.namespace}{\'\\t\'}{.metadata.name}{\'\\n\'}{end}';
+/**
+ * Scan one cluster. All resource reads run against the same kubeconfig; any
+ * failure (unreachable cluster, timeout, malformed response) rejects with a
+ * ScanError whose message never contains the kubeconfig path.
+ */
+export async function scanCluster(input) {
+    const exec = input.exec ?? defaultExec;
+    const base = ['kubectl', `--kubeconfig=${input.kubeconfigPath}`];
+    const run = async (args) => {
+        try {
+            return await exec([...base, ...args], { timeoutMs: input.timeoutMs ?? SCAN_TIMEOUT_MS });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new ScanError(scrubKubeconfigPath(message, input.kubeconfigPath), input.cluster);
+        }
+    };
+    const parseOrThrow = (json, what) => {
+        try {
+            return parseList(json, what);
+        }
+        catch (err) {
+            throw new ScanError(err.message, input.cluster);
+        }
+    };
+    const [workloads, services, ingresses, configMaps] = await Promise.all([
+        run(['get', 'deployments,statefulsets,daemonsets', '--all-namespaces', '-o', 'json']),
+        run(['get', 'services', '--all-namespaces', '-o', 'json']),
+        run(['get', 'ingresses', '--all-namespaces', '-o', 'json']),
+        run(['get', 'configmaps', '--all-namespaces', '-o', 'json']),
+    ]);
+    // Secrets are metadata-only reference names — nice to have, not worth
+    // failing a cluster over: the k8s `view` ClusterRole does NOT include
+    // secrets, so a strict ro account gets Forbidden here. The workload
+    // secretRefs (from pod specs) already carry the reference names.
+    const secrets = await run(['get', 'secrets', '--all-namespaces', '-o', `jsonpath=${SECRETS_JSONPATH}`])
+        .catch(() => ({ stdout: '' }));
+    // Endpoints feed the backend-less-Service anomaly detector. Same degraded
+    // discipline: a failed read yields undefined and the detector skips —
+    // never a guess, never a scan failure.
+    const endpointsRaw = await run(['get', 'endpoints', '--all-namespaces', '-o', 'json'])
+        .catch(() => undefined);
+    // rook-ceph footprint (ticket 15): CephBlockPool/CephCluster CRs and the
+    // rook-ceph-tools pod location. Same degraded discipline as endpoints —
+    // CRDs absent or the ro account unable to list them (built-in `view`
+    // covers no ceph.rook.io resources) yields no hints, never a scan failure.
+    const cephCrsRaw = await run(['get', 'cephclusters.ceph.rook.io,cephblockpools.ceph.rook.io', '--all-namespaces', '-o', 'json'])
+        .catch(() => undefined);
+    const cephToolsRaw = await run(['get', 'pods', '--all-namespaces', '-l', 'app=rook-ceph-tools', '-o', `jsonpath=${SECRETS_JSONPATH}`])
+        .catch(() => undefined);
+    const workloadItems = [];
+    // A combined `get a,b,c -o json` returns a single List whose items mix kinds.
+    for (const item of parseOrThrow(workloads.stdout, 'workloads').items ?? []) {
+        const kind = item?.kind;
+        if (kind === 'Deployment' || kind === 'StatefulSet' || kind === 'DaemonSet') {
+            workloadItems.push(reduceWorkload(kind, item));
+        }
+    }
+    const serviceItems = (parseOrThrow(services.stdout, 'services').items ?? []).map(reduceService);
+    // Prometheus corroboration: best-effort enhancement. Any failure (no
+    // Prometheus service, port-forward timeout, unreachable API) yields
+    // undefined — the main scan result is unaffected and the cluster is NOT
+    // marked stale for this.
+    let prometheus;
+    try {
+        prometheus = await scrapePrometheusTargets({
+            kubeconfigPath: input.kubeconfigPath,
+            services: serviceItems,
+            spawn: input.spawn,
+            fetchFn: input.fetchFn,
+            ...(input.prometheusTimeoutMs !== undefined ? { timeoutMs: input.prometheusTimeoutMs } : {}),
+        });
+    }
+    catch {
+        prometheus = undefined;
+    }
+    const scan = {
+        cluster: input.cluster,
+        scannedAt: (input.now ?? new Date()).toISOString(),
+        workloads: workloadItems,
+        services: serviceItems,
+        ingresses: (parseOrThrow(ingresses.stdout, 'ingresses').items ?? []).map(reduceIngress),
+        configMaps: (parseOrThrow(configMaps.stdout, 'configmaps').items ?? []).map(reduceConfigMap),
+        secrets: parseSecretNames(secrets.stdout),
+    };
+    if (endpointsRaw !== undefined) {
+        scan.endpoints = (parseOrThrow(endpointsRaw.stdout, 'endpoints').items ?? []).map(reduceEndpoints);
+    }
+    // Fold the ceph hints: emit only when something was actually found.
+    let ceph;
+    if (cephCrsRaw !== undefined) {
+        const pools = [];
+        const clusters = [];
+        for (const item of parseOrThrow(cephCrsRaw.stdout, 'ceph CRs').items ?? []) {
+            const ns = item?.metadata?.namespace;
+            const nm = item?.metadata?.name;
+            if (typeof ns !== 'string' || typeof nm !== 'string')
+                continue;
+            if (item.kind === 'CephBlockPool')
+                pools.push({ namespace: ns, name: nm });
+            else if (item.kind === 'CephCluster')
+                clusters.push({ namespace: ns, name: nm });
+        }
+        if (pools.length + clusters.length > 0)
+            ceph = { pools, clusters };
+    }
+    // The tools-pod read reuses the namespace<TAB>name reduction (metadata only).
+    const toolsPods = cephToolsRaw !== undefined ? parseSecretNames(cephToolsRaw.stdout) : [];
+    if (toolsPods.length > 0) {
+        ceph = ceph ?? { pools: [], clusters: [] };
+        ceph.toolsPod = toolsPods[0];
+    }
+    if (ceph !== undefined)
+        scan.ceph = ceph;
+    if (prometheus !== undefined)
+        scan.prometheus = prometheus;
+    return scan;
+}