@blogic-cz/agent-tools 0.14.61 → 0.15.1

package/README.md

@@ -178,6 +178,10 @@ bun run agent-tools/example-tool/index.ts ping
       // auto defaults to true:
       // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
       name: "ExampleVPN",
+      // Reuse package-managed connections for 30 seconds after the last command. Set 0 for immediate cleanup.
+      idleDisconnectMs: 30000,
+      // Total window for stop plus disconnected-status confirmation.
+      disconnectTimeoutMs: 10000,
       // Optional: pass IPSec shared secret to macOS scutil from env without storing the value in config.
       secretEnvVar: "EXAMPLE_VPN_IPSEC_SHARED_SECRET",
     },
@@ -187,8 +191,7 @@ bun run agent-tools/example-tool/index.ts ping
       clusterId: "your-cluster-id",
       namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
       prerequisites: [{ type: "vpn", key: "exampleVpn" }],
-      // Prerequisites are currently decoded and validated as config metadata;
-      // automatic VPN connect/disconnect execution is planned for a follow-up release.
+      // agent-tools starts disconnected VPNs, shares package-local leases, and disconnects only connections it owns.
     },
   },
   logs: {
@@ -252,6 +255,12 @@ export default { handleToolExecuteBefore };
 
 All tools support `--help` for full usage documentation. Legacy `agent-tools-*` binary names (e.g. `agent-tools-gh`) still work for backwards compatibility.
 
+### Kubernetes command safety
+
+`k8s-tool` parses generic kubectl commands into arguments and invokes `kubectl` directly. Shell pipelines, chaining, substitution, user overrides of the configured cluster or credentials, mutating `config`/`auth` subcommands, and `cluster-info dump` are rejected. Direct Secret reads, raw kubeconfig output, filename/kustomize reads, and `kubectl diff` are also blocked.
+
+Pod `exec` is limited to direct `redis-cli PING/INFO` and `ls` diagnostics. Generic exec cannot read file contents; use `logs-tool`, which confines files to the configured log directory, tails them through an internal structured operation, and applies the same case-insensitive literal substring filter locally and remotely. Configured log directories are a trusted boundary and must not permit adversarial symlink replacement during reads.
+
 ### gh-tool machine contracts
 
 `pr view` adds `headSha` and `baseSha`; failed-check evidence adds the same SHA pair. Review summaries, inline comments, and threads add `commitSha` plus `feedbackOrigin`: `current_head` only for an exact `commitSha === headSha`, `pre_existing` for a different known SHA (not an obsolescence verdict), and `unknown` when either SHA is absent. Issue comments always use `commitSha: null` and `feedbackOrigin: unknown`. `review-triage` preserves existing fields and adds `inlineComments` plus per-kind `feedbackOriginCounts`; batch triage returns the same object per PR.
@@ -414,7 +423,7 @@ Secrets are **never** stored in the config file. The `db-tool` config references
 }
 ```
 
-Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails.
+Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails. Package-managed VPNs remain reusable for `idleDisconnectMs` (default 30000) after the last lease; `0` restores immediate cleanup. Preconnected or `leave-running` connections are treated as external and never stopped automatically. If runtime state is corrupt, unknown, or contains legacy artifacts, first stop all agent-tools processes using the VPN, then remove that VPN state directory under `~/.agent-tools/runtime/vpn-prerequisites`.
 
 ```json5
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.61",
+  "version": "0.15.1",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/schemas/agent-tools.schema.json

@@ -558,16 +558,25 @@
           "enum": ["leave-running", "stop-if-started"]
         },
         "connectTimeoutMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1
         },
         "disconnectTimeoutMs": {
-          "type": "number"
-        },
-        "cooldownMs": {
-          "type": "number"
-        },
-        "leaseTtlMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "description": "Total bounded stop-and-confirm window in milliseconds."
+        },
+        "idleDisconnectMs": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "default": 30000,
+          "description": "Managed VPN reuse window after the last lease. Set to 0 for immediate cleanup."
         },
         "secretEnvVar": {
           "type": "string",

package/src/config/loader.ts

@@ -18,6 +18,20 @@ const CredentialGuardConfigSchema = Schema.Struct({
 });
 
 const CleanupPolicySchema = Schema.Literals(["leave-running", "stop-if-started"]);
+const VPN_TIMER_FIELDS = ["connectTimeoutMs", "disconnectTimeoutMs", "idleDisconnectMs"] as const;
+const MAX_TIMER_MS = 2_147_483_647;
+
+function validateVpnTimer(key: string, field: (typeof VPN_TIMER_FIELDS)[number], value: unknown) {
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > MAX_TIMER_MS
+  ) {
+    throw new Error(`VPN "${key}" ${field} must be an integer from 0 to ${MAX_TIMER_MS}.`);
+  }
+}
 
 const VpnPrerequisiteSchema = Schema.Struct({
   type: Schema.Literal("vpn"),
@@ -56,8 +70,7 @@ const VpnConfigSchema = Schema.Struct({
   defaultCleanup: Schema.optionalKey(CleanupPolicySchema),
   connectTimeoutMs: Schema.optionalKey(Schema.Number),
   disconnectTimeoutMs: Schema.optionalKey(Schema.Number),
-  cooldownMs: Schema.optionalKey(Schema.Number),
-  leaseTtlMs: Schema.optionalKey(Schema.Number),
+  idleDisconnectMs: Schema.optionalKey(Schema.Number),
   secretEnvVar: Schema.optionalKey(Schema.String),
   drivers: Schema.optionalKey(
     Schema.Struct({
@@ -215,8 +228,29 @@ export function decodeConfig(
   const sanitized = stripUnknownTopLevelKeys(parsed);
 
   try {
-    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized);
-    return decoded as AgentToolsConfig;
+    if (isRecord(sanitized) && isRecord(sanitized.vpns)) {
+      for (const [key, value] of Object.entries(sanitized.vpns)) {
+        if (!isRecord(value)) continue;
+        if ("cooldownMs" in value || "leaseTtlMs" in value) {
+          throw new Error(`VPN "${key}" uses removed cooldownMs or leaseTtlMs configuration.`);
+        }
+        for (const field of VPN_TIMER_FIELDS) {
+          if (value[field] !== undefined) validateVpnTimer(key, field, value[field]);
+        }
+      }
+    }
+    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized) as AgentToolsConfig;
+    return decoded.vpns
+      ? {
+          ...decoded,
+          vpns: Object.fromEntries(
+            Object.entries(decoded.vpns).map(([key, vpn]) => [
+              key,
+              { idleDisconnectMs: 30_000, ...vpn },
+            ]),
+          ),
+        }
+      : decoded;
   } catch (error) {
     throw new Error(
       `Invalid agent-tools config at ${configPath}: ${

package/src/config/types.ts

@@ -43,9 +43,10 @@ export type VpnConfig = {
   auto?: boolean;
   defaultCleanup?: CleanupPolicy;
   connectTimeoutMs?: number;
+  /** Total bounded stop-and-confirm window in milliseconds. */
   disconnectTimeoutMs?: number;
-  cooldownMs?: number;
-  leaseTtlMs?: number;
+  /** Managed VPN reuse window after the last lease. Defaults to 30000; 0 disconnects immediately. */
+  idleDisconnectMs?: number;
   /** Name of environment variable holding the VPN shared secret for supported drivers. */
   secretEnvVar?: string;
   drivers?: {

package/src/k8s-tool/index.ts

@@ -219,7 +219,7 @@ const kubectlCommand = Command.make(
     `Kubernetes CLI Tool for Coding Agents
 
 Executes kubectl commands against the correct cluster context.
-Supports shell pipes and complex commands.
+Parses commands into arguments and rejects shell syntax.
 
 IMPORTANT FOR AI AGENTS:
 Always use this tool instead of kubectl directly to ensure
@@ -233,24 +233,25 @@ CLUSTER CONFIGURATION:
 
 WORKFLOW FOR AI AGENTS:
   1. Use this tool for ALL kubectl operations on test/prod
-  2. Pipes are supported - use shell syntax
-  3. Use -n <namespace> for target namespace
+  2. Do not use pipes, chaining, substitution, or shell interpreters
+  3. Use logs-tool for remote log filtering
+  4. Use -n <namespace> for target namespace
 
 EXAMPLES:
   # List pods in test namespace
   bun run src/k8s-tool kubectl --env test --cmd "get pods -n my-app-test"
 
-  # Get pod logs with grep
-  bun run src/k8s-tool kubectl --env test --cmd "logs -l app=web-app -n my-app-test --tail=100 | grep error"
+  # Get pod logs (use logs-tool when filtering is required)
+  bun run src/k8s-tool kubectl --env test --cmd "logs -l app=web-app -n my-app-test --tail=100"
 
   # Check resource usage
   bun run src/k8s-tool kubectl --env test --cmd "top pod -n my-app-test"
 
-  # Describe pod with filtered output
-  bun run src/k8s-tool kubectl --env test --cmd "describe pod web-app-xxx -n my-app-test | grep -A20 Events"
+  # Describe a pod
+  bun run src/k8s-tool kubectl --env test --cmd "describe pod web-app-xxx -n my-app-test"
 
-  # Execute command in pod
-  bun run src/k8s-tool kubectl --env test --cmd "exec web-app-xxx -n my-app-test -- cat /app/logs/app.log | tail -50"
+  # Execute an allowlisted diagnostic in a pod
+  bun run src/k8s-tool kubectl --env test --cmd "exec web-app-xxx -n my-app-test -- redis-cli INFO commandstats"
 
   # Dry run - show command without executing
   bun run src/k8s-tool kubectl --env test --cmd "get pods -n my-app-test" --dry-run
@@ -367,7 +368,7 @@ const execCommand = Command.make(
     ...commonFlags,
     pod: Flag.string("pod").pipe(Flag.withDescription("Pod name")),
     execCmd: Flag.string("exec-cmd").pipe(
-      Flag.withDescription("Command to run inside the pod; wrap in quotes for spaces"),
+      Flag.withDescription("Allowlisted diagnostic: redis-cli PING/INFO or ls"),
     ),
     namespace: Flag.string("namespace").pipe(
       Flag.withDescription("Namespace containing the pod"),
@@ -391,7 +392,7 @@ const execCommand = Command.make(
       ]);
       return yield* runK8sCommand(command, { dryRun, env, format, profile });
     }),
-).pipe(Command.withDescription("Execute a command in a pod (kubectl exec <pod> -- <cmd>)"));
+).pipe(Command.withDescription("Run an allowlisted diagnostic in a pod"));
 
 const topCommand = Command.make(
   "top",

package/src/k8s-tool/security.ts

@@ -1,12 +1,5 @@
-/**
- * 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.
- */
+import { posix } from "node:path";
 
-/** Kubectl verbs that are safe for AI agents (read-only / non-destructive) */
 export const ALLOWED_KUBECTL_VERBS = [
   "get",
   "describe",
@@ -18,14 +11,10 @@ export const ALLOWED_KUBECTL_VERBS = [
   "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",
@@ -51,51 +40,278 @@ export const BLOCKED_KUBECTL_VERBS = [
 export type K8sSecurityCheckResult = {
   allowed: boolean;
   command: string;
+  argv?: string[];
   reason?: string;
+  hint?: 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();
+export function parseKubectlCommand(cmd: string): string[] | undefined {
+  const argv: string[] = [];
+  let word = "";
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  for (const char of cmd) {
+    if (escaped) {
+      word += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\n" || char === "\r") return undefined;
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else word += char;
+    } else if (char === "'" || char === '"') quote = char;
+    else if (/[$`;&|<>()[\]]/.test(char)) return undefined;
+    else if (/\s/.test(char)) {
+      if (word) {
+        argv.push(word);
+        word = "";
+      }
+    } else word += char;
+  }
+  if (quote || escaped) return undefined;
+  if (word) argv.push(word);
+  return argv.length ? argv : undefined;
+}
 
-  // Extract verb: first non-flag word
-  const verb = kubectlPart
-    .split(/\s+/)
-    .find((word) => !word.startsWith("-"))
-    ?.toLowerCase();
+const flagsWithValues = new Set([
+  "-n",
+  "--namespace",
+  "-o",
+  "--output",
+  "-l",
+  "--selector",
+  "--field-selector",
+  "-L",
+  "--label-columns",
+  "--chunk-size",
+  "--sort-by",
+  "--subresource",
+  "--template",
+  "--context",
+  "--kubeconfig",
+  "--request-timeout",
+  "-s",
+  "--server",
+  "--as",
+  "--as-group",
+  "--as-uid",
+  "--token",
+  "--certificate-authority",
+  "--cache-dir",
+  "--client-certificate",
+  "--client-key",
+  "--cluster",
+  "--password",
+  "--profile",
+  "--profile-output",
+  "--tls-server-name",
+  "--user",
+  "--username",
+]);
+const controlledFlags = new Set([
+  "-s",
+  "--context",
+  "--kubeconfig",
+  "--server",
+  "--token",
+  "--user",
+  "--username",
+  "--password",
+  "--profile",
+  "--profile-output",
+  "--as",
+  "--as-group",
+  "--as-uid",
+  "--certificate-authority",
+  "--client-certificate",
+  "--client-key",
+  "--cluster",
+  "--tls-server-name",
+  "--insecure-skip-tls-verify",
+  "--insecure-skip-tls-verify-backend",
+]);
+const attachedShortValueFlags = ["-n", "-o", "-l", "-L"] as const;
+const flagsWithoutValues = new Set([
+  "-A",
+  "--all-namespaces",
+  "--allow-missing-template-keys",
+  "--ignore-not-found",
+  "--no-headers",
+  "--output-watch-events",
+  "-R",
+  "--recursive",
+  "--server-print",
+  "--show-events",
+  "--show-kind",
+  "--show-labels",
+  "--show-managed-fields",
+  "--use-openapi-print-columns",
+  "-w",
+  "--watch",
+  "--watch-only",
+]);
+const isSecretResource = (resource: string) =>
+  resource.split(",").some((part) => /^(?:secrets?|secrets?\.[^/]+)(?:\/|$)/i.test(part));
 
-  if (!verb) {
-    return { allowed: false, command: cmd, reason: "Empty kubectl command." };
+function resourceOperand(argv: string[], verbIndex: number): string | null | undefined {
+  let flagsEnded = false;
+  for (let i = verbIndex + 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) return undefined;
+    if (!flagsEnded && arg === "--") {
+      flagsEnded = true;
+      continue;
+    }
+    if (!flagsEnded && arg.startsWith("-")) {
+      const [flag] = arg.split("=", 1);
+      if (flag !== undefined && flagsWithValues.has(flag)) {
+        if (!arg.includes("=")) i++;
+        continue;
+      }
+      if (
+        attachedShortValueFlags.some(
+          (shortFlag) => arg.startsWith(shortFlag) && arg.length > shortFlag.length,
+        )
+      )
+        continue;
+      if (flag !== undefined && flagsWithoutValues.has(flag)) continue;
+      return null;
+    }
+    return arg;
   }
+}
 
-  // 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(", ")}.`,
-    };
-  }
+export function isSafeLogPath(path: string): boolean {
+  const normalizedPath = posix.normalize(path);
+  return (
+    path.startsWith("/") &&
+    !path.split("/").includes("..") &&
+    /^\/(?!proc(?:\/|$)|sys(?:\/|$)|var\/run\/secrets(?:\/|$)).*\.log$/.test(normalizedPath) &&
+    !normalizedPath.toLowerCase().includes("serviceaccount")
+  );
+}
 
-  // 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(", ")}.`,
-    };
-  }
+function execAllowed(argv: string[], separator: number): boolean {
+  const command = argv[separator + 1];
+  const args = argv.slice(separator + 2);
+  if (!command) return false;
+  if (command === "redis-cli")
+    return (
+      (args.length === 1 && args[0] === "PING") ||
+      ((args.length === 1 || args.length === 2) && args[0]?.toUpperCase() === "INFO")
+    );
+  if (command === "ls")
+    return args.every((arg) => arg === "-la" || (arg.startsWith("/") && !arg.includes("..")));
+  return false;
+}
 
-  return { allowed: true, command: cmd, verb };
+export function isKubectlCommandAllowed(cmd: string): K8sSecurityCheckResult {
+  const argv = parseKubectlCommand(cmd);
+  if (!argv)
+    return { allowed: false, command: cmd, reason: "Empty, malformed, or shell syntax command." };
+  let verbIndex = 0;
+  while (argv[verbIndex]?.startsWith("-")) {
+    const flag = argv[verbIndex];
+    if (flag !== undefined && flagsWithValues.has(flag)) verbIndex++;
+    verbIndex++;
+  }
+  const verb = argv[verbIndex]?.toLowerCase();
+  if (!verb) return { allowed: false, command: cmd, reason: "Empty kubectl command." };
+  const denied = (reason: string, hint?: string): K8sSecurityCheckResult => ({
+    allowed: false,
+    command: cmd,
+    verb,
+    reason,
+    hint,
+  });
+  if ((BLOCKED_KUBECTL_VERBS as readonly string[]).includes(verb))
+    return denied(
+      `'${verb}' is a mutating operation blocked for AI agents. Only read-only operations are allowed: ${ALLOWED_KUBECTL_VERBS.join(", ")}.`,
+    );
+  if (!(ALLOWED_KUBECTL_VERBS as readonly string[]).includes(verb))
+    return denied(
+      `Unknown kubectl verb '${verb}'. Only known read-only operations are allowed: ${ALLOWED_KUBECTL_VERBS.join(", ")}.`,
+    );
+  const controlledFlag = argv.find((arg) => {
+    const flag = arg.split("=", 1)[0] ?? "";
+    return controlledFlags.has(flag) || (arg.startsWith("-s") && !arg.startsWith("--"));
+  });
+  if (controlledFlag !== undefined)
+    return denied(
+      `Cluster, authentication, and impersonation flag '${controlledFlag}' is controlled by the selected profile.`,
+      "Remove the override and select the intended Kubernetes profile instead.",
+    );
+  const subcommand = argv[verbIndex + 1]?.toLowerCase();
+  if (
+    verb === "config" &&
+    (subcommand === undefined || !["view", "get-contexts", "current-context"].includes(subcommand))
+  )
+    return denied(
+      "Only read-only kubectl config subcommands are allowed.",
+      "Use config view, config get-contexts, or config current-context.",
+    );
+  if (verb === "auth" && !["can-i", "whoami"].includes(subcommand ?? ""))
+    return denied(
+      "Only read-only kubectl auth subcommands are allowed.",
+      "Use auth can-i or auth whoami.",
+    );
+  if (verb === "cluster-info" && subcommand === "dump")
+    return denied(
+      "cluster-info dump is blocked because it may expose sensitive diagnostic data.",
+      "Use cluster-info without dump.",
+    );
+  const resource = resourceOperand(argv, verbIndex);
+  const hasSensitiveInputFlag = argv.some(
+    (arg) =>
+      arg === "-f" ||
+      arg.startsWith("-f") ||
+      arg === "--filename" ||
+      arg === "-k" ||
+      arg.startsWith("-k") ||
+      arg === "--kustomize" ||
+      /^(?:--filename|--kustomize)=/.test(arg) ||
+      /^--raw(?:=|$)/.test(arg),
+  );
+  if ((verb === "get" || verb === "describe") && hasSensitiveInputFlag)
+    return denied(
+      "Kubernetes Secret reads and file-based reads are blocked because they may expose credentials.",
+      "Use a targeted non-secret resource diagnostic instead.",
+    );
+  if ((verb === "get" || verb === "describe") && resource === null)
+    return denied(
+      "Unsupported flag before the resource operand.",
+      "Use a documented get/describe flag or place the resource first.",
+    );
+  const hasNamedSecretResource = argv
+    .slice(verbIndex + 1)
+    .some((arg) => arg.includes("/") && isSecretResource(arg));
+  if (
+    (verb === "get" || verb === "describe") &&
+    ((resource !== undefined && resource !== null && isSecretResource(resource)) ||
+      hasNamedSecretResource)
+  )
+    return denied(
+      "Kubernetes Secret reads and file-based reads are blocked because they may expose credentials.",
+      "Use a targeted non-secret resource diagnostic instead.",
+    );
+  if (verb === "config" && argv.includes("view") && argv.some((arg) => /^--raw(?:=|$)/.test(arg)))
+    return denied(
+      "Raw kubeconfig output is blocked because it may expose credentials.",
+      "Use 'config view' without --raw.",
+    );
+  if (verb === "exec") {
+    const separator = argv.indexOf("--", verbIndex + 1);
+    if (separator < 0 || !execAllowed(argv, separator))
+      return denied(
+        "Only narrow diagnostic commands are allowed in pods.",
+        "Use redis-cli PING/INFO or ls. Use logs-tool to read log files.",
+      );
+  }
+  return { allowed: true, command: cmd, argv, verb };
 }