@compforge/harness-toolbox 0.5.6 → 0.6.1

package/README.md

@@ -469,3 +469,35 @@ IP literals and Kubernetes `service.namespace` names use the same API. There is
 implicit execution on the caller host or ICMP requirement. Network failure returns
 evidence; missing Python, execution failure and incomplete output throw. TLS success
 does not establish HTTP authorization, object access or application download policy.
+
+
+## Kubernetes environment and AppArmor admission
+
+`@compforge/harness-toolbox/kubernetes/environment-inspection` exports
+`inspectKubernetesEnvironment(access, instance, {timeoutMs, signal?})`. Pass an existing Common
+`WorkloadInstance`; the caller discovers and selects it (for example with `KubernetesClient.resolveWorkload`).
+The function reads that Pod, verifies its UID, reads `ip_forward` in the selected running container,
+and gets only its associated Node's `operatingSystem`, `osImage`, `kernelVersion` and `architecture`.
+It does not enumerate Nodes, select workloads or infer a host forwarding setting from the Pod namespace.
+
+```ts
+const result = await inspectKubernetesEnvironment({
+  resources: client.clusterResources(),
+  exec: client.exec.bind(client),
+}, selectedInstance, { timeoutMs: 5_000, signal });
+```
+
+Use a cluster-scoped resource view: Pod GET supplies its namespace explicitly; Node GET has none.
+The positive timeout is a shared request budget. Resource/exec adapters must honor the supplied timeout
+and cancellation signal. Node and forwarding reads retain independent successes and sanitized issues;
+`complete`, `partial` and `unavailable` describe coverage, not Service health. Cancellation throws.
+A missing or changed Pod UID prevents exec and Node attribution. A same-name replacement during the later
+name-addressed exec cannot be excluded atomically by Kubernetes; results describe a best-effort sample.
+
+`@compforge/harness-toolbox/kubernetes/apparmor` exports
+`probeAppArmorUnconfinedAdmission(executor, {namespace, serviceAccountName, image}, {timeoutMs, signal?})`.
+The caller supplies an authorized `Executor.run` channel. The function uses an explicit namespace and
+ServiceAccount impersonation with `create --dry-run=server`; it never persists a Pod. Results are
+`allowed`, `denied` (explicit AppArmor Unconfined admission rejection), or `unknown` (including generic
+RBAC, impersonation, timeout and transport failures). Acceptance does not verify Node runtime support.
+The caller owns permissions, Service semantics, scheduling and borrowed client/executor cleanup.

package/dist/kubernetes/apparmor.d.ts

@@ -0,0 +1,24 @@
+import { type ErrorKind } from "../errors";
+import type { Executor } from "./executor";
+export interface AppArmorUnconfinedAdmissionInput {
+    namespace: string;
+    serviceAccountName: string;
+    image: string;
+}
+export interface AppArmorUnconfinedAdmissionResult {
+    target: AppArmorUnconfinedAdmissionInput;
+    observedAt: string;
+    status: "allowed" | "denied" | "unknown";
+    reason?: string;
+    errorKind?: ErrorKind;
+}
+/**
+ * @spec Probe AppArmor Unconfined admission as the supplied ServiceAccount using server-side dry-run only.
+ * @rule Admission acceptance does not prove Node support. Generic RBAC/auth/transport failures remain unknown.
+ * @rule Caller owns target selection, authorization and executor lifecycle; no workload or Service discovery occurs.
+ * @link docs/toolbox.md
+ */
+export declare function probeAppArmorUnconfinedAdmission(executor: Pick<Executor, "run">, input: AppArmorUnconfinedAdmissionInput, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<AppArmorUnconfinedAdmissionResult>;

package/dist/kubernetes/apparmor.js

@@ -0,0 +1,60 @@
+import {
+  KubernetesError,
+  kubernetesCommandError
+} from "../chunk-68zz17hs.js";
+
+// src/kubernetes/apparmor.ts
+async function probeAppArmorUnconfinedAdmission(executor, input, options) {
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || !input.image.trim() || !/^[a-z0-9][a-z0-9-]*$/.test(input.namespace) || !/^[a-z0-9][a-z0-9.-]*$/.test(input.serviceAccountName)) {
+    throw new KubernetesError("AppArmor admission requires namespace, ServiceAccount, image and positive timeout", { kind: "invalid_argument" });
+  }
+  options.signal?.throwIfAborted();
+  const result = { target: { ...input }, observedAt: new Date().toISOString(), status: "unknown" };
+  const manifest = {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { generateName: "apparmor-unconfined-probe-", namespace: input.namespace },
+    spec: { serviceAccountName: input.serviceAccountName, restartPolicy: "Never", containers: [{
+      name: "probe",
+      image: input.image,
+      securityContext: {
+        appArmorProfile: { type: "Unconfined" },
+        allowPrivilegeEscalation: false,
+        capabilities: { drop: ["ALL"] },
+        runAsNonRoot: true,
+        runAsUser: 65532,
+        seccompProfile: { type: "RuntimeDefault" }
+      }
+    }] }
+  };
+  try {
+    const execution = await executor.run([
+      "create",
+      "-f",
+      "-",
+      "--dry-run=server",
+      "-o",
+      "json",
+      "--namespace",
+      input.namespace,
+      "--as",
+      `system:serviceaccount:${input.namespace}:${input.serviceAccountName}`
+    ], { ...options, stdin: JSON.stringify(manifest) });
+    options.signal?.throwIfAborted();
+    if (execution.ok)
+      return { ...result, status: "allowed" };
+    const output = `${execution.stderr}
+${execution.stdout}`;
+    if (!execution.timedOut && /apparmor/i.test(output) && /unconfined/i.test(output) && /(?:admission|violates\s+podsecurity)/i.test(output) && /(denied|forbidden|violates\s+podsecurity)/i.test(output)) {
+      return { ...result, status: "denied", reason: "Admission rejected AppArmor Unconfined" };
+    }
+    throw kubernetesCommandError(execution);
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    const kind = error instanceof KubernetesError ? error.kind : "operation_failed";
+    return { ...result, errorKind: kind, reason: `AppArmor admission could not be determined: ${kind}` };
+  }
+}
+export {
+  probeAppArmorUnconfinedAdmission
+};

package/dist/kubernetes/client.js

@@ -1,8 +1,8 @@
 import {
   KubernetesClient
-} from "../chunk-erbehkcz.js";
-import"../chunk-d2y5ewbb.js";
+} from "../chunk-7mc2jevr.js";
 import"../chunk-361x998p.js";
+import"../chunk-d2y5ewbb.js";
 import"../chunk-jt8fn3wg.js";
 import"../chunk-dfpqr0r9.js";
 import"../chunk-a9htb6cr.js";

package/dist/kubernetes/environment-inspection.d.ts

@@ -0,0 +1,36 @@
+import type { WorkloadInstance } from "@compforge/harness-common";
+import { type ErrorKind } from "../errors";
+import type { KubernetesClient } from "./client";
+import type { ResourceAccess } from "./resources";
+export interface KubernetesEnvironmentAccess {
+    /** Explicit cluster-scoped resource view; Pod requests supply their namespace, Node requests do not. */
+    resources: Pick<ResourceAccess, "get">;
+    /** Borrow the caller's authorized exec channel; this function never creates or disposes a client. */
+    exec: KubernetesClient["exec"];
+}
+export interface KubernetesEnvironmentIssue {
+    source: "pod" | "pod.ip_forward" | "node" | `node.${string}`;
+    kind: ErrorKind;
+    message: string;
+}
+export interface KubernetesEnvironmentInspection {
+    instance: WorkloadInstance;
+    observedAt: string;
+    status: "complete" | "partial" | "unavailable";
+    /** Value in the sampled Pod's network namespace, not proof of the host setting. */
+    podIpForward?: 0 | 1;
+    container?: string;
+    nodeName?: string;
+    nodeInfo: Partial<Record<"operatingSystem" | "osImage" | "kernelVersion" | "architecture", string>>;
+    issues: KubernetesEnvironmentIssue[];
+}
+/**
+ * @spec Inspect only the supplied WorkloadInstance and its Node. Discovery and sampling belong to the caller.
+ * @rule Reject a Pod already replaced at the identity read; later name-addressed exec is not atomic with that read.
+ * @rule ip_forward is Pod-netns scoped; OS metadata comes from Node status.nodeInfo, never the container image.
+ * @link docs/toolbox.md
+ */
+export declare function inspectKubernetesEnvironment(access: KubernetesEnvironmentAccess, instance: WorkloadInstance, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<KubernetesEnvironmentInspection>;

package/dist/kubernetes/environment-inspection.js

@@ -0,0 +1,107 @@
+import {
+  KubernetesError
+} from "../chunk-68zz17hs.js";
+
+// src/kubernetes/environment-inspection.ts
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+function issue(source, error) {
+  const kind = error instanceof KubernetesError ? error.kind : "operation_failed";
+  return { source, kind, message: `Kubernetes environment read failed: ${kind}` };
+}
+async function inspectKubernetesEnvironment(access, instance, options) {
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || instance.platform !== "kubernetes" || [instance.environment, instance.workload, instance.namespace, instance.pod, instance.uid].some((value) => !value?.trim())) {
+    throw new KubernetesError("Environment inspection requires a WorkloadInstance and positive timeout", { kind: "invalid_argument" });
+  }
+  const deadline = performance.now() + options.timeoutMs;
+  const request = () => {
+    options.signal?.throwIfAborted();
+    const timeoutMs = Math.ceil(deadline - performance.now());
+    if (timeoutMs <= 0)
+      throw new KubernetesError("Environment inspection budget exhausted", { kind: "timeout" });
+    return { timeoutMs, signal: options.signal };
+  };
+  const result = {
+    instance: { ...instance },
+    observedAt: new Date().toISOString(),
+    status: "unavailable",
+    nodeInfo: {},
+    issues: []
+  };
+  let pod;
+  try {
+    pod = await access.resources.get({ apiVersion: "v1", resource: "pods", namespace: instance.namespace, name: instance.pod }, request());
+    options.signal?.throwIfAborted();
+    const meta = object(pod.metadata);
+    if (meta.uid !== instance.uid || meta.name !== instance.pod || meta.namespace !== instance.namespace) {
+      throw new KubernetesError("Pod identity changed or is missing", { kind: "invalid_response" });
+    }
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    result.issues.push(issue("pod", error));
+    return result;
+  }
+  const spec = object(pod.spec), status = object(pod.status);
+  const containers = Array.isArray(spec.containers) ? spec.containers.map(object) : [];
+  const container = instance.container ? containers.find((item) => item.name === instance.container) : containers.length === 1 ? containers[0] : undefined;
+  result.container = text(container?.name);
+  result.nodeName = text(spec.nodeName);
+  const [forwardingIssues, nodeIssues] = await Promise.all([
+    (async () => {
+      try {
+        if (!result.container)
+          throw new KubernetesError("Target container is absent or ambiguous", { kind: "invalid_argument" });
+        const states = Array.isArray(status.containerStatuses) ? status.containerStatuses.map(object) : [];
+        if (status.phase !== "Running" || !object(states.find((item) => item.name === result.container)?.state).running) {
+          throw new KubernetesError("Target container is not running", { kind: "unsupported_operation" });
+        }
+        const execution = await access.exec(instance.namespace, { pod: instance.pod, container: result.container }, ["cat", "/proc/sys/net/ipv4/ip_forward"], request());
+        options.signal?.throwIfAborted();
+        if (!execution.ok)
+          throw new KubernetesError("Could not read ip_forward", { kind: execution.timedOut ? "timeout" : "operation_failed" });
+        const value = execution.stdout.trim();
+        if (value !== "0" && value !== "1")
+          throw new KubernetesError("Invalid ip_forward response", { kind: "invalid_response" });
+        result.podIpForward = value === "1" ? 1 : 0;
+        return [];
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        return [issue("pod.ip_forward", error)];
+      }
+    })(),
+    (async () => {
+      try {
+        if (!result.nodeName)
+          throw new KubernetesError("Pod nodeName is absent", { kind: "resource_not_found" });
+        const node = await access.resources.get({ apiVersion: "v1", resource: "nodes", name: result.nodeName }, request());
+        options.signal?.throwIfAborted();
+        if (node.metadata?.name !== result.nodeName)
+          throw new KubernetesError("Node identity is missing or mismatched", { kind: "invalid_response" });
+        const info = object(object(node.status).nodeInfo);
+        const issues = [];
+        for (const field of ["operatingSystem", "osImage", "kernelVersion", "architecture"]) {
+          const value = text(info[field]);
+          if (value)
+            result.nodeInfo[field] = value;
+          else
+            issues.push({ source: `node.${field}`, kind: "invalid_response", message: `Node status.nodeInfo.${field} is missing` });
+        }
+        return issues;
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        return [issue("node", error)];
+      }
+    })()
+  ]);
+  options.signal?.throwIfAborted();
+  result.issues.push(...forwardingIssues, ...nodeIssues);
+  result.status = !result.issues.length ? "complete" : result.podIpForward !== undefined || Object.keys(result.nodeInfo).length ? "partial" : "unavailable";
+  return result;
+}
+export {
+  inspectKubernetesEnvironment
+};

package/dist/kubernetes/environment.js

@@ -1,8 +1,8 @@
 import {
   KubernetesClient
-} from "../chunk-erbehkcz.js";
-import"../chunk-d2y5ewbb.js";
+} from "../chunk-7mc2jevr.js";
 import"../chunk-361x998p.js";
+import"../chunk-d2y5ewbb.js";
 import"../chunk-jt8fn3wg.js";
 import"../chunk-dfpqr0r9.js";
 import {

package/dist/kubernetes/pod-log-client.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/kubernetes/pod-log-datasource.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import {
   clientKey

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.5.6",
+  "version": "0.6.1",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -112,7 +112,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "3.1133.0",
-    "@compforge/harness-common": "0.5.13",
+    "@compforge/harness-common": "0.6.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",

package/dist/{chunk-mnad4zkp.js → chunk-010339ga.js}

@@ -2,12 +2,12 @@ import {
   PodLogByteBudget,
   runPodLogCapturePlan
 } from "./chunk-8nm9f0hh.js";
-import {
-  logTimestampNanos
-} from "./chunk-mp88s7r7.js";
 import {
   LogCaptureFile
 } from "./chunk-1vfwvgkj.js";
+import {
+  logTimestampNanos
+} from "./chunk-mp88s7r7.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";

package/dist/{chunk-erbehkcz.js → chunk-7mc2jevr.js}

@@ -1,9 +1,9 @@
-import {
-  resolveWorkload
-} from "./chunk-d2y5ewbb.js";
 import {
   KubernetesResourceTransport
 } from "./chunk-361x998p.js";
+import {
+  resolveWorkload
+} from "./chunk-d2y5ewbb.js";
 import {
   KubernetesExecTransport
 } from "./chunk-dfpqr0r9.js";