@blogic-cz/agent-tools 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
   "keywords": [
     "agent",
@@ -64,13 +64,13 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-beta.20",
+    "@effect/platform-bun": "4.0.0-beta.25",
     "@toon-format/toon": "2.1.0",
-    "effect": "4.0.0-beta.20"
+    "effect": "4.0.0-beta.25"
   },
   "devDependencies": {
     "@effect/language-service": "0.77.0",
-    "@effect/vitest": "4.0.0-beta.20",
+    "@effect/vitest": "4.0.0-beta.25",
     "@types/bun": "1.3.9",
     "oxfmt": "0.35.0",
     "oxlint": "1.50.0",

package/src/k8s-tool/errors.ts

@@ -27,4 +27,19 @@ export class K8sTimeoutError extends Schema.TaggedErrorClass<K8sTimeoutError>()(
   retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
-export type K8sError = K8sContextError | K8sCommandError | K8sTimeoutError;
+export class K8sDangerousCommandError extends Schema.TaggedErrorClass<K8sDangerousCommandError>()(
+  "K8sDangerousCommandError",
+  {
+    message: Schema.String,
+    command: Schema.String,
+    verb: Schema.optionalKey(Schema.String),
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+  },
+) {}
+
+export type K8sError =
+  | K8sContextError
+  | K8sCommandError
+  | K8sTimeoutError
+  | K8sDangerousCommandError;

package/src/k8s-tool/index.ts

@@ -110,6 +110,18 @@ const runK8sCommand = (command: string, options: CommonK8sCommandOptions) =>
           };
           return Effect.succeed(errorResult);
         },
+        K8sDangerousCommandError: (error) => {
+          const errorResult: CommandResult = {
+            success: false,
+            error: error.message,
+            command: error.command,
+            hint:
+              error.hint ??
+              "AI agents can only run read-only kubectl commands. For mutating operations, use kubectl directly or ask a human operator.",
+            executionTimeMs: 0,
+          };
+          return Effect.succeed(errorResult);
+        },
       }),
     );
 

package/src/k8s-tool/security.ts

@@ -0,0 +1,99 @@
+/**
+ * K8s Security Module
+ *
+ * Validates kubectl commands before execution. Only read-only operations
+ * are allowed for AI agents. Mutating operations (delete, apply, patch, etc.)
+ * are blocked to prevent accidental or unauthorized changes to clusters.
+ */
+
+/** Kubectl verbs that are safe for AI agents (read-only / non-destructive) */
+export const ALLOWED_KUBECTL_VERBS = [
+  "get",
+  "describe",
+  "logs",
+  "top",
+  "explain",
+  "api-resources",
+  "api-versions",
+  "version",
+  "cluster-info",
+  "auth",
+  "diff",
+  "wait",
+  "exec",
+  "port-forward",
+  "config",
+] as const;
+
+/** Kubectl verbs that are explicitly blocked (mutating / destructive) */
+export const BLOCKED_KUBECTL_VERBS = [
+  "delete",
+  "drain",
+  "cordon",
+  "uncordon",
+  "taint",
+  "apply",
+  "patch",
+  "edit",
+  "replace",
+  "create",
+  "scale",
+  "rollout",
+  "set",
+  "label",
+  "annotate",
+  "expose",
+  "autoscale",
+  "run",
+  "cp",
+] as const;
+
+export type K8sSecurityCheckResult = {
+  allowed: boolean;
+  command: string;
+  reason?: string;
+  verb?: string;
+};
+
+/**
+ * Checks if a kubectl command is allowed for AI agent execution.
+ * Extracts the kubectl verb and validates against allow/block lists.
+ *
+ * Handles piped commands by checking only the kubectl portion (before first pipe).
+ */
+export function isKubectlCommandAllowed(cmd: string): K8sSecurityCheckResult {
+  const trimmed = cmd.trim();
+
+  // Handle piped commands — only validate the kubectl verb (before first |)
+  const kubectlPart = trimmed.split("|")[0].trim();
+
+  // Extract verb: first non-flag word
+  const words = kubectlPart.split(/\s+/).filter((w) => !w.startsWith("-"));
+  const verb = words[0]?.toLowerCase();
+
+  if (!verb) {
+    return { allowed: false, command: cmd, reason: "Empty kubectl command." };
+  }
+
+  // Explicit blocklist — clear message about what's blocked and why
+  if ((BLOCKED_KUBECTL_VERBS as readonly string[]).includes(verb)) {
+    return {
+      allowed: false,
+      command: cmd,
+      verb,
+      reason: `'${verb}' is a mutating operation blocked for AI agents. Only read-only operations are allowed: ${ALLOWED_KUBECTL_VERBS.join(", ")}.`,
+    };
+  }
+
+  // Allowlist — unknown verbs are also blocked for safety
+  if (!(ALLOWED_KUBECTL_VERBS as readonly string[]).includes(verb)) {
+    return {
+      allowed: false,
+      command: cmd,
+      verb,
+      reason: `Unknown kubectl verb '${verb}'. Only known read-only operations are allowed: ${ALLOWED_KUBECTL_VERBS.join(", ")}.`,
+    };
+  }
+
+  return { allowed: true, command: cmd, verb };
+}

package/src/k8s-tool/service.ts

@@ -3,9 +3,15 @@ import { Effect, Layer, Option, Ref, ServiceMap, Stream } from "effect";
 
 import type { CommandResult, Environment } from "./types";
 
-import { K8sCommandError, K8sContextError, K8sTimeoutError } from "./errors";
+import {
+  K8sCommandError,
+  K8sContextError,
+  K8sDangerousCommandError,
+  K8sTimeoutError,
+} from "./errors";
 import { ConfigService, getToolConfig } from "#config";
 import type { K8sConfig } from "#config";
+import { isKubectlCommandAllowed } from "./security";
 
 export class K8sService extends ServiceMap.Service<
   K8sService,
@@ -13,11 +19,17 @@ export class K8sService extends ServiceMap.Service<
     readonly runCommand: (
       cmd: string,
       env: Environment,
-    ) => Effect.Effect<string, K8sContextError | K8sCommandError | K8sTimeoutError>;
+    ) => Effect.Effect<
+      string,
+      K8sContextError | K8sCommandError | K8sTimeoutError | K8sDangerousCommandError
+    >;
     readonly runKubectl: (
       cmd: string,
       dryRun: boolean,
-    ) => Effect.Effect<CommandResult, K8sContextError | K8sCommandError | K8sTimeoutError>;
+    ) => Effect.Effect<
+      CommandResult,
+      K8sContextError | K8sCommandError | K8sTimeoutError | K8sDangerousCommandError
+    >;
   }
 >()("@agent-tools/K8sService") {
   static readonly layer = Layer.effect(
@@ -166,8 +178,18 @@ export class K8sService extends ServiceMap.Service<
           cmd: string,
           _env: Environment,
         ) {
-          const result = yield* executeCommand(cmd);
+          // Security: block dangerous commands before execution
+          const securityCheck = isKubectlCommandAllowed(cmd);
+          if (!securityCheck.allowed) {
+            return yield* new K8sDangerousCommandError({
+              message: securityCheck.reason ?? "Command not allowed",
+              command: cmd,
+              verb: securityCheck.verb,
+              hint: "AI agents can only run read-only kubectl commands. For mutating operations, use kubectl directly or ask a human operator.",
+            });
+          }
 
+          const result = yield* executeCommand(cmd);
           if (result.exitCode !== 0) {
             return yield* new K8sCommandError({
               message: result.stderr ?? `kubectl exited with code ${result.exitCode}`,
@@ -184,8 +206,18 @@ export class K8sService extends ServiceMap.Service<
           cmd: string,
           dryRun: boolean,
         ) {
-          const startTime = Date.now();
+          // Security: block dangerous commands before execution (even dry-run)
+          const securityCheck = isKubectlCommandAllowed(cmd);
+          if (!securityCheck.allowed) {
+            return yield* new K8sDangerousCommandError({
+              message: securityCheck.reason ?? "Command not allowed",
+              command: cmd,
+              verb: securityCheck.verb,
+              hint: "AI agents can only run read-only kubectl commands. For mutating operations, use kubectl directly or ask a human operator.",
+            });
+          }
 
+          const startTime = Date.now();
           if (dryRun) {
             const context = yield* resolveContext();
             const fullCommand = `kubectl --context ${context} ${cmd}`;