pepr 0.12.2 → 0.13.0

package/src/lib/assets/yaml.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { dumpYaml } from "@kubernetes/client-node";
+import crypto from "crypto";
+import { promises as fs } from "fs";
+
+import { Assets } from ".";
+import { apiTokenSecret, service, tlsSecret } from "./networking";
+import { deployment, moduleSecret, namespace } from "./pods";
+import { clusterRole, clusterRoleBinding, serviceAccount } from "./rbac";
+import { webhookConfig } from "./webhooks";
+
+export function zarfYaml({ name, image, config }: Assets, path: string) {
+  const zarfCfg = {
+    kind: "ZarfPackageConfig",
+    metadata: {
+      name,
+      description: `Pepr Module: ${config.description}`,
+      url: "https://github.com/defenseunicorns/pepr",
+      version: `${config.appVersion || "0.0.1"}`,
+    },
+    components: [
+      {
+        name: "module",
+        required: true,
+        manifests: [
+          {
+            name: "module",
+            namespace: "pepr-system",
+            files: [path],
+          },
+        ],
+        images: [image],
+      },
+    ],
+  };
+
+  return dumpYaml(zarfCfg, { noRefs: true });
+}
+
+export async function allYaml(assets: Assets) {
+  const { name, tls, apiToken, path } = assets;
+
+  const code = await fs.readFile(path);
+
+  // Generate a hash of the code
+  const hash = crypto.createHash("sha256").update(code).digest("hex");
+
+  const mutateWebhook = await webhookConfig(assets, "mutate");
+  const validateWebhook = await webhookConfig(assets, "validate");
+
+  const resources = [
+    namespace,
+    clusterRole(name),
+    clusterRoleBinding(name),
+    serviceAccount(name),
+    apiTokenSecret(name, apiToken),
+    tlsSecret(name, tls),
+    deployment(assets, hash),
+    service(name),
+    moduleSecret(name, code, hash),
+  ];
+
+  if (mutateWebhook) {
+    resources.push(mutateWebhook);
+  }
+
+  if (validateWebhook) {
+    resources.push(validateWebhook);
+  }
+
+  // Convert the resources to a single YAML string
+  return resources.map(r => dumpYaml(r, { noRefs: true })).join("---\n");
+}

package/src/lib/capability.ts

@@ -1,20 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import { modelToGroupVersionKind } from "./k8s/index";
+import { pickBy } from "ramda";
+
+import { isWatchMode, modelToGroupVersionKind } from "./k8s/index";
 import { GroupVersionKind } from "./k8s/types";
-import logger from "./logger";
+import Log from "./logger";
 import {
-  BindToAction,
   Binding,
   BindingFilter,
   BindingWithName,
-  CapabilityAction,
   CapabilityCfg,
-  DeepPartial,
   Event,
   GenericClass,
-  HookPhase,
+  MutateAction,
+  MutateActionChain,
+  ValidateAction,
   WhenSelector,
 } from "./types";
 
@@ -26,9 +27,6 @@ export class Capability implements CapabilityCfg {
   private _description: string;
   private _namespaces?: string[] | undefined;
 
-  // Currently everything is considered a mutation
-  private _mutateOrValidate = HookPhase.mutate;
-
   private _bindings: Binding[] = [];
 
   get bindings(): Binding[] {
@@ -47,16 +45,13 @@ export class Capability implements CapabilityCfg {
     return this._namespaces || [];
   }
 
-  get mutateOrValidate() {
-    return this._mutateOrValidate;
-  }
-
   constructor(cfg: CapabilityCfg) {
     this._name = cfg.name;
     this._description = cfg.description;
     this._namespaces = cfg.namespaces;
-    logger.info(`Capability ${this._name} registered`);
-    logger.debug(cfg);
+
+    Log.info(`Capability ${this._name} registered`);
+    Log.debug(cfg);
   }
 
   /**
@@ -86,66 +81,81 @@ export class Capability implements CapabilityCfg {
         labels: {},
         annotations: {},
       },
-      callback: () => undefined,
     };
 
     const prefix = `${this._name}: ${model.name}`;
 
-    logger.info(`Binding created`, prefix);
+    const isNotEmpty = (value: object) => Object.keys(value).length > 0;
+    const log = (message: string, cbString: string) => {
+      const filteredObj = pickBy(isNotEmpty, binding.filters);
 
-    const Then = (cb: CapabilityAction<T>): BindToAction<T> => {
-      logger.info(`Binding action created`, prefix);
-      logger.debug(cb.toString(), prefix);
-      // Push the binding to the list of bindings for this capability as a new BindingAction
-      // with the callback function to preserve
-      this._bindings.push({
-        ...binding,
-        callback: cb,
-      });
+      Log.info(`${message} configured for ${binding.event}`, prefix);
+      Log.info(filteredObj, prefix);
+      Log.debug(cbString, prefix);
+    };
 
-      // Now only allow adding actions to the same binding
-      return { Then };
+    const Validate = (validateCallback: ValidateAction<T>): void => {
+      if (!isWatchMode) {
+        log("Validate Action", validateCallback.toString());
+
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        this._bindings.push({
+          ...binding,
+          isValidate: true,
+          validateCallback,
+        });
+      }
     };
 
-    const ThenSet = (merge: DeepPartial<InstanceType<T>>): BindToAction<T> => {
-      // Add the new action to the binding
-      Then(req => req.Merge(merge));
+    const Mutate = (mutateCallback: MutateAction<T>): MutateActionChain<T> => {
+      if (!isWatchMode) {
+        log("Mutate Action", mutateCallback.toString());
+
+        // Push the binding to the list of bindings for this capability as a new BindingAction
+        // with the callback function to preserve
+        this._bindings.push({
+          ...binding,
+          isMutate: true,
+          mutateCallback,
+        });
+      }
 
-      return { Then };
+      // Now only allow adding actions to the same binding
+      return { Validate };
     };
 
     function InNamespace(...namespaces: string[]): BindingWithName<T> {
-      logger.debug(`Add namespaces filter ${namespaces}`, prefix);
+      Log.debug(`Add namespaces filter ${namespaces}`, prefix);
       binding.filters.namespaces.push(...namespaces);
-      return { WithLabel, WithAnnotation, WithName, Then, ThenSet };
+      return { ...commonChain, WithName };
     }
 
     function WithName(name: string): BindingFilter<T> {
-      logger.debug(`Add name filter ${name}`, prefix);
+      Log.debug(`Add name filter ${name}`, prefix);
       binding.filters.name = name;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
+      return commonChain;
     }
 
     function WithLabel(key: string, value = ""): BindingFilter<T> {
-      logger.debug(`Add label filter ${key}=${value}`, prefix);
+      Log.debug(`Add label filter ${key}=${value}`, prefix);
       binding.filters.labels[key] = value;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
+      return commonChain;
     }
 
     const WithAnnotation = (key: string, value = ""): BindingFilter<T> => {
-      logger.debug(`Add annotation filter ${key}=${value}`, prefix);
+      Log.debug(`Add annotation filter ${key}=${value}`, prefix);
       binding.filters.annotations[key] = value;
-      return { WithLabel, WithAnnotation, Then, ThenSet };
+      return commonChain;
     };
 
+    const commonChain = { WithLabel, WithAnnotation, Mutate, Validate };
+
     const bindEvent = (event: Event) => {
       binding.event = event;
       return {
+        ...commonChain,
         InNamespace,
-        Then,
-        ThenSet,
-        WithAnnotation,
-        WithLabel,
         WithName,
       };
     };

package/src/lib/controller.ts

@@ -1,58 +1,75 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2023-Present The Pepr Authors
 
-import express from "express";
+import express, { NextFunction } from "express";
 import fs from "fs";
 import https from "https";
 
 import { Capability } from "./capability";
-import { Request, Response } from "./k8s/types";
+import { isWatchMode } from "./k8s";
+import { MutateResponse, Request, ValidateResponse } from "./k8s/types";
 import Log from "./logger";
-import { processor } from "./processor";
-import { ModuleConfig } from "./types";
 import { MetricsCollector } from "./metrics";
+import { mutateProcessor } from "./mutate-processor";
+import { ModuleConfig } from "./types";
+import { validateProcessor } from "./validate-processor";
 
 export class Controller {
-  private readonly app = express();
-  private running = false;
+  private readonly _app = express();
+  private _running = false;
   private metricsCollector = new MetricsCollector("pepr");
 
   // The token used to authenticate requests
-  private token = "";
+  private _token = "";
 
   constructor(
-    private readonly config: ModuleConfig,
-    private readonly capabilities: Capability[],
-    private readonly beforeHook?: (req: Request) => void,
-    private readonly afterHook?: (res: Response) => void
+    private readonly _config: ModuleConfig,
+    private readonly _capabilities: Capability[],
+    private readonly _beforeHook?: (req: Request) => void,
+    private readonly _afterHook?: (res: MutateResponse) => void,
   ) {
     // Middleware for logging requests
-    this.app.use(this.logger);
+    this._app.use(this.logger);
 
     // Middleware for parsing JSON, limit to 2mb vs 100K for K8s compatibility
-    this.app.use(express.json({ limit: "2mb" }));
+    this._app.use(express.json({ limit: "2mb" }));
+
+    if (_beforeHook) {
+      Log.info(`Using beforeHook: ${_beforeHook}`);
+    }
+
+    if (_afterHook) {
+      Log.info(`Using afterHook: ${_afterHook}`);
+    }
+
+    // Bind endpoints
+    this.bindEndpoints();
+  }
 
+  private bindEndpoints = () => {
     // Health check endpoint
-    this.app.get("/healthz", this.healthz);
+    this._app.get("/healthz", this.healthz);
 
     // Metrics endpoint
-    this.app.get("/metrics", this.metrics);
-
-    // Mutate endpoint
-    this.app.post("/mutate/:token", this.mutate);
+    this._app.get("/metrics", this.metrics);
 
-    if (beforeHook) {
-      console.info(`Using beforeHook: ${beforeHook}`);
+    if (isWatchMode) {
+      return;
     }
 
-    if (afterHook) {
-      console.info(`Using afterHook: ${afterHook}`);
-    }
-  }
+    // Require auth for webhook endpoints
+    this._app.use(["/mutate/:token", "/validate/:token"], this.validateToken);
+
+    // Mutate endpoint
+    this._app.post("/mutate/:token", this.admissionReq("Mutate"));
+
+    // Validate endpoint
+    this._app.post("/validate/:token", this.admissionReq("Validate"));
+  };
 
   /** Start the webhook server */
   public startServer = (port: number) => {
-    if (this.running) {
+    if (this._running) {
       throw new Error("Cannot start Pepr module: Pepr module was not instantiated with deferStart=true");
     }
 
@@ -62,29 +79,32 @@ export class Controller {
       cert: fs.readFileSync(process.env.SSL_CERT_PATH || "/etc/certs/tls.crt"),
     };
 
-    // Get the API token from the environment variable or the mounted secret
-    this.token = process.env.PEPR_API_TOKEN || fs.readFileSync("/app/api-token/value").toString().trim();
-    console.info(`Using API token: ${this.token}`);
+    // Get the API token if not in watch mode
+    if (!isWatchMode) {
+      // Get the API token from the environment variable or the mounted secret
+      this._token = process.env.PEPR_API_TOKEN || fs.readFileSync("/app/api-token/value").toString().trim();
+      Log.info(`Using API token: ${this._token}`);
 
-    if (!this.token) {
-      throw new Error("API token not found");
+      if (!this._token) {
+        throw new Error("API token not found");
+      }
     }
 
     // Create HTTPS server
-    const server = https.createServer(options, this.app).listen(port);
+    const server = https.createServer(options, this._app).listen(port);
 
     // Handle server listening event
     server.on("listening", () => {
-      console.log(`Server listening on port ${port}`);
+      Log.info(`Server listening on port ${port}`);
       // Track that the server is running
-      this.running = true;
+      this._running = true;
     });
 
     // Handle EADDRINUSE errors
     server.on("error", (e: { code: string }) => {
       if (e.code === "EADDRINUSE") {
-        console.log(
-          `Address in use, retrying in 2 seconds. If this persists, ensure ${port} is not in use, e.g. "lsof -i :${port}"`
+        Log.warn(
+          `Address in use, retrying in 2 seconds. If this persists, ensure ${port} is not in use, e.g. "lsof -i :${port}"`,
         );
         setTimeout(() => {
           server.close();
@@ -95,92 +115,154 @@ export class Controller {
 
     // Listen for the SIGTERM signal and gracefully close the server
     process.on("SIGTERM", () => {
-      console.log("Received SIGTERM, closing server");
+      Log.info("Received SIGTERM, closing server");
       server.close(() => {
-        console.log("Server closed");
+        Log.info("Server closed");
         process.exit(0);
       });
     });
   };
 
+  /**
+   * Middleware for logging requests
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   * @param next the next middleware function
+   */
   private logger = (req: express.Request, res: express.Response, next: express.NextFunction) => {
     const startTime = Date.now();
 
     res.on("finish", () => {
-      const now = new Date().toISOString();
       const elapsedTime = Date.now() - startTime;
-      const message = `[${now}] ${req.method} ${req.originalUrl} [${res.statusCode}] ${elapsedTime} ms\n`;
-
-      res.statusCode >= 400 ? console.error(message) : console.info(message);
+      const message = {
+        uid: req.body?.request?.uid,
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        duration: `${elapsedTime} ms`,
+      };
+
+      res.statusCode >= 300 ? Log.warn(message) : Log.info(message);
     });
 
     next();
   };
 
+  /**
+   * Validate the token in the request path
+   *
+   * @param req The incoming request
+   * @param res The outgoing response
+   * @param next The next middleware function
+   * @returns
+   */
+  private validateToken = (req: express.Request, res: express.Response, next: NextFunction) => {
+    // Validate the token
+    const { token } = req.params;
+    if (token !== this._token) {
+      const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
+      Log.warn(err);
+      res.status(401).send(err);
+      this.metricsCollector.alert();
+      return;
+    }
+
+    // Token is valid, continue
+    next();
+  };
+
+  /**
+   * Health check endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
   private healthz = (req: express.Request, res: express.Response) => {
     try {
       res.send("OK");
     } catch (err) {
-      console.error(err);
+      Log.error(err);
       res.status(500).send("Internal Server Error");
     }
   };
 
+  /**
+   * Metrics endpoint handler
+   *
+   * @param req the incoming request
+   * @param res the outgoing response
+   */
   private metrics = async (req: express.Request, res: express.Response) => {
     try {
       res.send(await this.metricsCollector.getMetrics());
     } catch (err) {
-      console.error(err);
+      Log.error(err);
       res.status(500).send("Internal Server Error");
     }
   };
 
-  private mutate = async (req: express.Request, res: express.Response) => {
-    const startTime = this.metricsCollector.observeStart();
-
-    try {
-      // Validate the token
-      const { token } = req.params;
-      if (token !== this.token) {
-        const err = `Unauthorized: invalid token '${token.replace(/[^\w]/g, "_")}'`;
-        console.warn(err);
-        res.status(401).send(err);
-        this.metricsCollector.alert();
-        return;
+  /**
+   * Admission request handler for both mutate and validate requests
+   *
+   * @param admissionKind the type of admission request
+   * @returns the request handler
+   */
+  private admissionReq = (admissionKind: "Mutate" | "Validate") => {
+    // Create the admission request handler
+    return async (req: express.Request, res: express.Response) => {
+      // Start the metrics timer
+      const startTime = this.metricsCollector.observeStart();
+
+      try {
+        // Get the request from the body or create an empty request
+        const request: Request = req.body?.request || ({} as Request);
+
+        // Run the before hook if it exists
+        this._beforeHook && this._beforeHook(request || {});
+
+        // Setup identifiers for logging
+        const name = request?.name ? `/${request.name}` : "";
+        const namespace = request?.namespace || "";
+        const gvk = request?.kind || { group: "", version: "", kind: "" };
+
+        const reqMetadata = {
+          uid: request.uid,
+          namespace,
+          name,
+        };
+
+        Log.info({ ...reqMetadata, gvk, operation: request.operation, admissionKind }, "Incoming request");
+        Log.debug({ ...reqMetadata, request }, "Incoming request body");
+
+        // Process the request
+        let response: MutateResponse | ValidateResponse;
+
+        // Call mutate or validate based on the admission kind
+        if (admissionKind === "Mutate") {
+          response = await mutateProcessor(this._config, this._capabilities, request, reqMetadata);
+        } else {
+          response = await validateProcessor(this._capabilities, request, reqMetadata);
+        }
+
+        // Run the after hook if it exists
+        this._afterHook && this._afterHook(response);
+
+        // Log the response
+        Log.debug({ ...reqMetadata, response }, "Outgoing response");
+
+        // Send a no prob bob response
+        res.send({
+          apiVersion: "admission.k8s.io/v1",
+          kind: "AdmissionReview",
+          response,
+        });
+        this.metricsCollector.observeEnd(startTime, admissionKind);
+      } catch (err) {
+        Log.error(err);
+        res.status(500).send("Internal Server Error");
+        this.metricsCollector.error();
       }
-
-      const request: Request = req.body?.request || ({} as Request);
-
-      // Run the before hook if it exists
-      this.beforeHook && this.beforeHook(request || {});
-
-      const name = request?.name ? `/${request.name}` : "";
-      const namespace = request?.namespace || "";
-      const gvk = request?.kind || { group: "", version: "", kind: "" };
-      const prefix = `${request.uid} ${namespace}${name}`;
-
-      Log.info(`Mutate [${request.operation}] ${gvk.group}/${gvk.version}/${gvk.kind}`, prefix);
-
-      // Process the request
-      const response = await processor(this.config, this.capabilities, request, prefix);
-
-      // Run the after hook if it exists
-      this.afterHook && this.afterHook(response);
-
-      // Log the response
-      Log.debug(response, prefix);
-
-      // Send a no prob bob response
-      res.send({
-        apiVersion: "admission.k8s.io/v1",
-        kind: "AdmissionReview",
-        response,
-      });
-      this.metricsCollector.observeEnd(startTime);
-    } catch (err) {
-      console.error(err);
-      res.status(500).send("Internal Server Error");
-      this.metricsCollector.error();
-    }
+    };
   };
 }

package/src/lib/fetch.ts

@@ -30,7 +30,7 @@ export type FetchResponse<T> = {
 export async function fetch<T>(url: URL | RequestInfo, init?: RequestInit): Promise<FetchResponse<T>> {
   let data = undefined as unknown as T;
   try {
-    logger.debug(`Fetching ${url}`);
+    logger.debug(init, `Fetching ${url}`);
 
     const resp = await fetchRaw(url, init);
     const contentType = resp.headers.get("content-type") || "";

package/src/lib/filter.ts

@@ -8,7 +8,7 @@ import { Binding, Event } from "./types";
 /**
  * shouldSkipRequest determines if a request should be skipped based on the binding filters.
  *
- * @param binding the capability action binding
+ * @param binding the action binding
  * @param req the incoming request
  * @returns
  */
@@ -20,8 +20,6 @@ export function shouldSkipRequest(binding: Binding, req: Request) {
   const srcObject = operation === Operation.DELETE ? req.oldObject : req.object;
   const { metadata } = srcObject || {};
 
-  console.log(metadata);
-
   // Test for matching operation
   if (!binding.event.includes(operation) && !binding.event.includes(Event.Any)) {
     return true;

package/src/lib/k8s/index.ts

@@ -3,9 +3,12 @@
 
 // Export kinds as a single object
 import * as kind from "./upstream";
-/** a is a collection of K8s types to be used within a CapabilityAction: `When(a.Configmap)` */
+/** a is a collection of K8s types to be used within a action: `When(a.Configmap)` */
 export { kind as a };
 
 export { modelToGroupVersionKind, gvkMap, RegisterKind } from "./kinds";
 
+// If the hostname is pepr-static-test-watcher-0, then we are running in watch mode
+export const isWatchMode = process.env.PEPR_WATCH_MODE === "true";
+
 export * from "./types";

package/src/lib/k8s/kinds.ts

@@ -5,6 +5,46 @@ import { GenericClass } from "../types";
 import { GroupVersionKind } from "./types";
 
 export const gvkMap: Record<string, GroupVersionKind> = {
+  /**
+   * Represents a K8s ClusterRole resource.
+   * ClusterRole is a set of permissions that can be bound to a user or group in a cluster-wide scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole}
+   */
+  V1ClusterRole: {
+    kind: "ClusterRole",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s ClusterRoleBinding resource.
+   * ClusterRoleBinding binds a ClusterRole to a user or group in a cluster-wide scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding}
+   */
+  V1ClusterRoleBinding: {
+    kind: "ClusterRoleBinding",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s Role resource.
+   * Role is a set of permissions that can be bound to a user or group in a namespace scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole}
+   */
+  V1Role: {
+    kind: "Role",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
+  /**
+   * Represents a K8s RoleBinding resource.
+   * RoleBinding binds a Role to a user or group in a namespace scope.
+   * @see {@link https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding}
+   */
+  V1RoleBinding: {
+    kind: "RoleBinding",
+    version: "v1",
+    group: "rbac.authorization.k8s.io",
+  },
   /**
    * Represents a K8s ConfigMap resource.
    * ConfigMap holds configuration data for pods to consume.