pepr 0.33.0 → 0.34.0

package/src/cli/init/index.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { execSync } from "child_process";
+import { resolve } from "path";
+import prompts from "prompts";
+
+import { RootCmd } from "../root";
+import {
+  codeSettings,
+  eslint,
+  genPeprTS,
+  genPkgJSON,
+  gitignore,
+  helloPepr,
+  prettier,
+  readme,
+  samplesYaml,
+  snippet,
+  tsConfig,
+} from "./templates";
+import { createDir, sanitizeName, write } from "./utils";
+import { confirm, walkthrough } from "./walkthrough";
+
+export default function (program: RootCmd) {
+  program
+    .command("init")
+    .description("Initialize a new Pepr Module")
+    // skip auto npm install and git init
+    .option("--skip-post-init", "Skip npm install, git init and VSCode launch")
+    .action(async opts => {
+      let pkgOverride = "";
+
+      // Overrides for testing. @todo: don't be so gross with Node CLI testing
+      if (process.env.TEST_MODE === "true") {
+        prompts.inject(["pepr-test-module", "A test module for Pepr", "ignore", "y"]);
+        pkgOverride = "file:../pepr-0.0.0-development.tgz";
+      }
+
+      const response = await walkthrough();
+      const dirName = sanitizeName(response.name);
+      const packageJSON = genPkgJSON(response, pkgOverride);
+      const peprTS = genPeprTS();
+
+      const confirmed = await confirm(dirName, packageJSON, peprTS.path);
+
+      if (confirmed) {
+        console.log("Creating new Pepr module...");
+
+        try {
+          await createDir(dirName);
+          await createDir(resolve(dirName, ".vscode"));
+          await createDir(resolve(dirName, "capabilities"));
+
+          await write(resolve(dirName, gitignore.path), gitignore.data);
+          await write(resolve(dirName, eslint.path), eslint.data);
+          await write(resolve(dirName, prettier.path), prettier.data);
+          await write(resolve(dirName, packageJSON.path), packageJSON.data);
+          await write(resolve(dirName, readme.path), readme.data);
+          await write(resolve(dirName, tsConfig.path), tsConfig.data);
+          await write(resolve(dirName, peprTS.path), peprTS.data);
+          await write(resolve(dirName, ".vscode", snippet.path), snippet.data);
+          await write(resolve(dirName, ".vscode", codeSettings.path), codeSettings.data);
+          await write(resolve(dirName, "capabilities", samplesYaml.path), samplesYaml.data);
+          await write(resolve(dirName, "capabilities", helloPepr.path), helloPepr.data);
+
+          if (!opts.skipPostInit) {
+            // run npm install from the new directory
+            process.chdir(dirName);
+            execSync("npm install", {
+              stdio: "inherit",
+            });
+
+            // setup git
+            execSync("git init", {
+              stdio: "inherit",
+            });
+
+            // try to open vscode
+            try {
+              execSync("code .", {
+                stdio: "inherit",
+              });
+            } catch (e) {
+              // vscode not found, do nothing
+            }
+          }
+
+          console.log(`New Pepr module created at ${dirName}`);
+          console.log(`Open VSCode or your editor of choice in ${dirName} to get started!`);
+        } catch (e) {
+          if (e instanceof Error) {
+            console.error(`Error creating Pepr module:`, e);
+          }
+          process.exit(1);
+        }
+      }
+    });
+}

package/src/cli/init/templates.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { dumpYaml } from "@kubernetes/client-node";
+import { inspect } from "util";
+import { v4 as uuidv4, v5 as uuidv5 } from "uuid";
+
+import eslintJSON from "../../templates/.eslintrc.template.json";
+import prettierJSON from "../../templates/.prettierrc.json";
+import samplesJSON from "../../templates/capabilities/hello-pepr.samples.json";
+import { gitIgnore, helloPeprTS, packageJSON, peprTS, readmeMd } from "../../templates/data.json";
+import peprSnippetsJSON from "../../templates/pepr.code-snippets.json";
+import settingsJSON from "../../templates/settings.json";
+import tsConfigJSON from "../../templates/tsconfig.module.json";
+import { sanitizeName } from "./utils";
+import { InitOptions } from "./walkthrough";
+
+export const { dependencies, devDependencies, peerDependencies, scripts, version } = packageJSON;
+
+export function genPkgJSON(opts: InitOptions, pgkVerOverride?: string) {
+  // Generate a random UUID for the module based on the module name
+  const uuid = uuidv5(opts.name, uuidv4());
+  // Generate a name for the module based on the module name
+  const name = sanitizeName(opts.name);
+  // Make typescript a dev dependency
+  const { typescript } = peerDependencies;
+
+  const testEnv = {
+    MY_CUSTOM_VAR: "example-value",
+    ZARF_VAR: "###ZARF_VAR_THING###",
+  };
+
+  const data = {
+    name,
+    version: "0.0.1",
+    description: opts.description,
+    keywords: ["pepr", "k8s", "policy-engine", "pepr-module", "security"],
+    engines: {
+      node: ">=18.0.0",
+    },
+    pepr: {
+      uuid: pgkVerOverride ? "static-test" : uuid,
+      onError: opts.errorBehavior,
+      webhookTimeout: 10,
+      customLabels: {
+        namespace: {
+          "pepr.dev": "",
+        },
+      },
+      alwaysIgnore: {
+        namespaces: [],
+      },
+      includedFiles: [],
+      env: pgkVerOverride ? testEnv : {},
+    },
+    scripts: {
+      "k3d-setup": scripts["test:journey:k3d"],
+    },
+    dependencies: {
+      pepr: pgkVerOverride || version,
+    },
+    devDependencies: {
+      typescript,
+    },
+  };
+
+  return {
+    data,
+    path: "package.json",
+    print: inspect(data, false, 5, true),
+  };
+}
+
+export function genPeprTS() {
+  return {
+    path: "pepr.ts",
+    data: peprTS,
+  };
+}
+
+export const readme = {
+  path: "README.md",
+  data: readmeMd,
+};
+
+export const helloPepr = {
+  path: "hello-pepr.ts",
+  data: helloPeprTS,
+};
+
+export const gitignore = {
+  path: ".gitignore",
+  data: gitIgnore,
+};
+
+export const samplesYaml = {
+  path: "hello-pepr.samples.yaml",
+  data: samplesJSON.map(r => dumpYaml(r, { noRefs: true })).join("---\n"),
+};
+
+export const snippet = {
+  path: "pepr.code-snippets",
+  data: peprSnippetsJSON,
+};
+
+export const codeSettings = {
+  path: "settings.json",
+  data: settingsJSON,
+};
+
+export const tsConfig = {
+  path: "tsconfig.json",
+  data: tsConfigJSON,
+};
+
+export const prettier = {
+  path: ".prettierrc",
+  data: prettierJSON,
+};
+
+export const eslint = {
+  path: ".eslintrc.json",
+  data: eslintJSON,
+};

package/src/cli/init/utils.test.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { expect, test } from "@jest/globals";
+
+import { sanitizeName } from "./utils";
+
+test("sanitizeName() sanitizes names correctly", () => {
+  const cases = [
+    {
+      input: "My Test Module",
+      expected: "my-test-module",
+    },
+    {
+      input: "!! 123 @@ Module",
+      expected: "123-module",
+    },
+    {
+      input: "---Test-Module---",
+      expected: "test-module",
+    },
+  ];
+
+  for (const { input, expected } of cases) {
+    const result = sanitizeName(input);
+    expect(result).toBe(expected);
+  }
+});

package/src/cli/init/utils.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { promises as fs } from "fs";
+
+/**
+ * Sanitize a user input name to be used as a pepr module directory name
+ *
+ * @param name the user input name
+ * @returns the sanitized name
+ */
+export function sanitizeName(name: string) {
+  // Replace any characters outside of [^a-z0-9-] with "-"
+  let sanitized = name.toLowerCase().replace(/[^a-z0-9-]+/gi, "-");
+
+  // Remove any leading or trailing hyphens
+  sanitized = sanitized.replace(/^-+|-+$/g, "");
+
+  // Replace multiple hyphens with a single hyphen
+  sanitized = sanitized.replace(/--+/g, "-");
+
+  return sanitized;
+}
+
+/**
+ * Creates a directory and throws an error if it already exists
+ *
+ * @param dir - The directory to create
+ */
+export async function createDir(dir: string) {
+  try {
+    await fs.mkdir(dir);
+  } catch (err) {
+    // The directory already exists
+    if (err && (err as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new Error(`Directory ${dir} already exists`);
+    } else {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Write data to a file on disk
+ * @param path - The path to the file
+ * @param data - The data to write
+ * @returns A promise that resolves when the file has been written
+ */
+export function write(path: string, data: unknown) {
+  // If the data is not a string, stringify it
+  if (typeof data !== "string") {
+    data = JSON.stringify(data, null, 2);
+  }
+  return fs.writeFile(path, data as string);
+}

package/src/cli/init/walkthrough.test.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { expect, test } from "@jest/globals";
+import prompts from "prompts";
+
+import { walkthrough } from "./walkthrough";
+
+test("walkthrough() returns expected results", async () => {
+  // Inject predefined answers for the prompts
+  prompts.inject(["My Test Module", "A test module for Pepr", 0]);
+
+  const result = await walkthrough();
+
+  // Check the returned object
+  expect(result).toEqual({
+    name: "My Test Module",
+    description: "A test module for Pepr",
+    errorBehavior: 0,
+  });
+});

package/src/cli/init/walkthrough.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { promises as fs } from "fs";
+import prompt, { Answers, PromptObject } from "prompts";
+
+import { Errors } from "../../lib/errors";
+import { eslint, gitignore, prettier, readme, tsConfig } from "./templates";
+import { sanitizeName } from "./utils";
+
+export type InitOptions = Answers<"name" | "description" | "errorBehavior">;
+
+export function walkthrough(): Promise<InitOptions> {
+  const askName: PromptObject = {
+    type: "text",
+    name: "name",
+    message:
+      "Enter a name for the new Pepr module. This will create a new directory based on the name.\n",
+    validate: async val => {
+      try {
+        const name = sanitizeName(val);
+        await fs.access(name, fs.constants.F_OK);
+
+        return "A directory with this name already exists";
+      } catch (e) {
+        return val.length > 2 || "The name must be at least 3 characters long";
+      }
+    },
+  };
+
+  const askDescription: PromptObject = {
+    type: "text",
+    name: "description",
+    message: "(Recommended) Enter a description for the new Pepr module.\n",
+  };
+
+  const askErrorBehavior: PromptObject = {
+    type: "select",
+    name: "errorBehavior",
+    message: "How do you want Pepr to handle errors encountered during K8s operations?",
+    choices: [
+      {
+        title: "Reject the operation",
+        value: Errors.reject,
+        description:
+          "In the event that Pepr is down or other module errors occur, the operation will not be allowed to continue. (Recommended for production.)",
+      },
+      {
+        title: "Ignore",
+        value: Errors.ignore,
+        description:
+          "In the event that Pepr is down or other module errors occur, an entry will be generated in the Pepr Controller Log and the operation will be allowed to continue. (Recommended for development, not for production.)",
+        selected: true,
+      },
+      {
+        title: "Log an audit event",
+        value: Errors.audit,
+        description:
+          "Pepr will continue processing and generate an entry in the Pepr Controller log as well as an audit event in the cluster.",
+      },
+    ],
+  };
+
+  return prompt([askName, askDescription, askErrorBehavior]) as Promise<InitOptions>;
+}
+
+export async function confirm(
+  dirName: string,
+  packageJSON: { path: string; print: string },
+  peprTSPath: string,
+) {
+  console.log(`
+  To be generated:
+
+    \x1b[1m${dirName}\x1b[0m
+    ├── \x1b[1m${eslint.path}\x1b[0m
+    ├── \x1b[1m${gitignore.path}\x1b[0m
+    ├── \x1b[1m${prettier.path}\x1b[0m
+    ├── \x1b[1mcapabilties\x1b[0m
+    │   ├── \x1b[1mhello-pepr.samples.yaml\x1b[0m     
+    │   └── \x1b[1mhello-pepr.ts\x1b[0m     
+    ├── \x1b[1m${packageJSON.path}\x1b[0m
+${packageJSON.print.replace(/^/gm, "    │   ")}
+    ├── \x1b[1m${peprTSPath}\x1b[0m
+    ├── \x1b[1m${readme.path}\x1b[0m
+    └── \x1b[1m${tsConfig.path}\x1b[0m
+      `);
+
+  const confirm = await prompt({
+    type: "confirm",
+    name: "confirm",
+    message: "Create the new Pepr module?",
+  });
+
+  return confirm.confirm;
+}

package/src/cli/kfc.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { execSync } from "child_process";
+import prompt from "prompts";
+
+import { RootCmd } from "./root";
+
+export default function (program: RootCmd) {
+  program
+    .command("kfc [args...]")
+    .description("Execute Kubernetes Fluent Client commands")
+    .action(async (args: string[]) => {
+      const { confirm } = await prompt({
+        type: "confirm",
+        name: "confirm",
+        message:
+          "For commands that generate files, this may overwrite any previously generated files.\n" +
+          "Are you sure you want to continue?",
+      });
+
+      // If the user doesn't confirm, exit
+      if (!confirm) {
+        return;
+      }
+
+      try {
+        // If the user doesn't provide any kfc arguments, show the kfc help
+        if (args.length === 0) {
+          args.push("--help");
+        }
+
+        // Join the args array into a space-separated string
+        const argsString = args.join(" ");
+
+        // Create the CRD generated class
+        execSync(`kubernetes-fluent-client ${argsString}`, {
+          stdio: "inherit",
+        });
+      } catch (e) {
+        console.error(`Error creating CRD generated class:`, e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/monitor.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Log as K8sLog, KubeConfig } from "@kubernetes/client-node";
+import { K8s, kind } from "kubernetes-fluent-client";
+import stream from "stream";
+import { ResponseItem } from "../lib/types";
+import { RootCmd } from "./root";
+
+export default function (program: RootCmd) {
+  program
+    .command("monitor [module-uuid]")
+    .description("Monitor a Pepr Module")
+    .action(async uuid => {
+      let labels: string[];
+      let errorMessage: string;
+
+      if (!uuid) {
+        labels = ["pepr.dev/controller", "admission"];
+        errorMessage = `No pods found with admission labels`;
+      } else {
+        labels = ["app", `pepr-${uuid}`];
+        errorMessage = `No pods found for module ${uuid}`;
+      }
+
+      // Get the logs for the `app=pepr-${module}` or `pepr.dev/controller=admission` pod selector
+      const pods = await K8s(kind.Pod)
+        .InNamespace("pepr-system")
+        .WithLabel(labels[0], labels[1])
+        .Get();
+
+      const podNames = pods.items.flatMap(pod => pod.metadata!.name) as string[];
+
+      if (podNames.length < 1) {
+        console.error(errorMessage);
+        process.exit(1);
+      }
+
+      const kc = new KubeConfig();
+      kc.loadFromDefault();
+
+      const log = new K8sLog(kc);
+
+      const logStream = new stream.PassThrough();
+      logStream.on("data", async chunk => {
+        const respMsg = `"msg":"Check response"`;
+        // Split the chunk into lines
+        const lines = await chunk.toString().split("\n");
+
+        for (const line of lines) {
+          // Check for `"msg":"Hello Pepr"`
+          if (line.includes(respMsg)) {
+            try {
+              const payload = JSON.parse(line.trim());
+              const isMutate = payload.res.patchType || payload.res.warnings;
+
+              const name = `${payload.namespace}${payload.name}`;
+              const uid = payload.res.uid;
+
+              if (isMutate) {
+                const plainPatch =
+                  payload.res?.patch !== undefined && payload.res?.patch !== null
+                    ? atob(payload.res.patch)
+                    : "";
+
+                const patch = plainPatch !== "" && JSON.stringify(JSON.parse(plainPatch), null, 2);
+                const patchType = payload.res.patchType || payload.res.warnings || "";
+                const allowOrDeny = payload.res.allowed ? "🔀" : "🚫";
+                console.log(`\n${allowOrDeny}  MUTATE     ${name} (${uid})`);
+                if (patchType.length > 0) {
+                  console.log(`\n\u001b[1;34m${patch}\u001b[0m`);
+                }
+              } else {
+                const failures = Array.isArray(payload.res) ? payload.res : [payload.res];
+
+                const filteredFailures = failures
+                  .filter((r: ResponseItem) => !r.allowed)
+                  .map((r: ResponseItem) => r.status.message);
+                if (filteredFailures.length > 0) {
+                  console.log(`\n❌  VALIDATE   ${name} (${uid})`);
+                  console.log(`\u001b[1;31m${filteredFailures}\u001b[0m`);
+                } else {
+                  console.log(`\n✅  VALIDATE   ${name} (${uid})`);
+                }
+              }
+            } catch {
+              console.warn(`\nIGNORED - Unable to parse line: ${line}.`);
+            }
+          }
+        }
+      });
+
+      for (const podName of podNames) {
+        await log.log("pepr-system", podName, "server", logStream, {
+          follow: true,
+          pretty: false,
+          timestamps: false,
+        });
+      }
+    });
+}

package/src/cli/root.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { Command } from "commander";
+
+export class RootCmd extends Command {
+  // eslint-disable-next-line class-methods-use-this
+  createCommand(name: string) {
+    const cmd = new Command(name);
+    return cmd;
+  }
+}

package/src/cli/update.ts

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { execSync } from "child_process";
+import fs from "fs";
+import { resolve } from "path";
+import prompt from "prompts";
+
+import {
+  codeSettings,
+  helloPepr,
+  prettier,
+  samplesYaml,
+  snippet,
+  tsConfig,
+} from "./init/templates";
+import { write } from "./init/utils";
+import { RootCmd } from "./root";
+
+export default function (program: RootCmd) {
+  program
+    .command("update")
+    .description("Update this Pepr module. Not recommended for prod as it may change files.")
+    .option("--skip-template-update", "Skip updating the template files")
+    .action(async opts => {
+      if (!opts.skipTemplateUpdate) {
+        const { confirm } = await prompt({
+          type: "confirm",
+          name: "confirm",
+          message:
+            "This will overwrite previously auto-generated files including the capabilities/HelloPepr.ts file.\n" +
+            "Are you sure you want to continue?",
+        });
+
+        // If the user doesn't confirm, exit
+        if (!confirm) {
+          return;
+        }
+      }
+
+      console.log("Updating the Pepr module...");
+
+      try {
+        // Update Pepr for the module
+        execSync("npm install pepr@latest", {
+          stdio: "inherit",
+        });
+
+        // Don't update the template files if the user specified the --skip-template-update flag
+        if (!opts.skipTemplateUpdate) {
+          execSync("npx pepr update-templates", {
+            stdio: "inherit",
+          });
+        }
+
+        console.log(`✅ Module updated successfully`);
+      } catch (e) {
+        console.error(`Error updating Pepr module:`, e);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("update-templates", { hidden: true })
+    .description("Perform template updates")
+    .action(async opts => {
+      console.log("Updating Pepr config and template tiles...");
+
+      try {
+        // Don't update the template files if the user specified the --skip-template-update flag
+        if (!opts.skipTemplateUpdate) {
+          await write(resolve(prettier.path), prettier.data);
+          await write(resolve(tsConfig.path), tsConfig.data);
+          await write(resolve(".vscode", snippet.path), snippet.data);
+          await write(resolve(".vscode", codeSettings.path), codeSettings.data);
+
+          // Update the samples.yaml file if it exists
+          const samplePath = resolve("capabilities", samplesYaml.path);
+          if (fs.existsSync(samplePath)) {
+            fs.unlinkSync(samplePath);
+            await write(samplePath, samplesYaml.data);
+          }
+
+          // Update the HelloPepr.ts file if it exists
+          const tsPath = resolve("capabilities", helloPepr.path);
+          if (fs.existsSync(tsPath)) {
+            await write(tsPath, helloPepr.data);
+          }
+        }
+      } catch (e) {
+        console.error(`Error updating template files:`, e);
+        process.exit(1);
+      }
+    });
+}