pepr 0.0.0-development

package/src/lib/helpers.ts

@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { promises as fs } from "fs";
+import { K8s, KubernetesObject, kind } from "kubernetes-fluent-client";
+import Log from "./logger";
+import { Binding, CapabilityExport } from "./types";
+import { sanitizeResourceName } from "../sdk/sdk";
+
+export class ValidationError extends Error {}
+
+export function validateCapabilityNames(capabilities: CapabilityExport[] | undefined): void {
+  if (capabilities && capabilities.length > 0) {
+    for (let i = 0; i < capabilities.length; i++) {
+      if (capabilities[i].name !== sanitizeResourceName(capabilities[i].name)) {
+        throw new ValidationError(`Capability name is not a valid Kubernetes resource name: ${capabilities[i].name}`);
+      }
+    }
+  }
+}
+
+export function validateHash(expectedHash: string): void {
+  // Require the hash to be a valid SHA-256 hash (64 characters, hexadecimal)
+  const sha256Regex = /^[a-f0-9]{64}$/i;
+  if (!expectedHash || !sha256Regex.test(expectedHash)) {
+    Log.error(`Invalid hash. Expected a valid SHA-256 hash, got ${expectedHash}`);
+    throw new ValidationError("Invalid hash");
+  }
+}
+
+type RBACMap = {
+  [key: string]: {
+    verbs: string[];
+    plural: string;
+  };
+};
+
+// check for overlap with labels and annotations between bindings and kubernetes objects
+export function checkOverlap(bindingFilters: Record<string, string>, objectFilters: Record<string, string>): boolean {
+  // True if labels/annotations are empty
+  if (Object.keys(bindingFilters).length === 0) {
+    return true;
+  }
+
+  let matchCount = 0;
+
+  for (const key in bindingFilters) {
+    // object must have label/annotation
+    if (Object.prototype.hasOwnProperty.call(objectFilters, key)) {
+      const val1 = bindingFilters[key];
+      const val2 = objectFilters[key];
+
+      // If bindingFilter has empty value for this key, only need to ensure objectFilter has this key
+      if (val1 === "" && key in objectFilters) {
+        matchCount++;
+      }
+      // If bindingFilter has a value, it must match the value in objectFilter
+      else if (val1 !== "" && val1 === val2) {
+        matchCount++;
+      }
+    }
+  }
+
+  // For single-key objects in bindingFilter or matching all keys in multiple-keys scenario
+  return matchCount === Object.keys(bindingFilters).length;
+}
+
+/**
+ * Decide to run callback after the event comes back from API Server
+ **/
+export function filterNoMatchReason(
+  binding: Partial<Binding>,
+  obj: Partial<KubernetesObject>,
+  capabilityNamespaces: string[],
+): string {
+  // binding kind is namespace with a InNamespace filter
+  if (binding.kind && binding.kind.kind === "Namespace" && binding.filters && binding.filters.namespaces.length !== 0) {
+    return `Ignoring Watch Callback: Cannot use a namespace filter in a namespace object.`;
+  }
+
+  if (typeof obj === "object" && obj !== null && "metadata" in obj && obj.metadata !== undefined && binding.filters) {
+    // binding labels and object labels dont match
+    if (obj.metadata.labels && !checkOverlap(binding.filters.labels, obj.metadata.labels)) {
+      return `Ignoring Watch Callback: No overlap between binding and object labels. Binding labels ${JSON.stringify(
+        binding.filters.labels,
+      )}, Object Labels ${JSON.stringify(obj.metadata.labels)}.`;
+    }
+
+    // binding annotations and object annotations dont match
+    if (obj.metadata.annotations && !checkOverlap(binding.filters.annotations, obj.metadata.annotations)) {
+      return `Ignoring Watch Callback: No overlap between binding and object annotations. Binding annotations ${JSON.stringify(
+        binding.filters.annotations,
+      )}, Object annotations ${JSON.stringify(obj.metadata.annotations)}.`;
+    }
+  }
+
+  // Check object is in the capability namespace
+  if (
+    Array.isArray(capabilityNamespaces) &&
+    capabilityNamespaces.length > 0 &&
+    obj.metadata &&
+    obj.metadata.namespace &&
+    !capabilityNamespaces.includes(obj.metadata.namespace)
+  ) {
+    return `Ignoring Watch Callback: Object is not in the capability namespace. Capability namespaces: ${capabilityNamespaces.join(
+      ", ",
+    )}, Object namespace: ${obj.metadata.namespace}.`;
+  }
+
+  // chceck every filter namespace is a capability namespace
+  if (
+    Array.isArray(capabilityNamespaces) &&
+    capabilityNamespaces.length > 0 &&
+    binding.filters &&
+    Array.isArray(binding.filters.namespaces) &&
+    binding.filters.namespaces.length > 0 &&
+    !binding.filters.namespaces.every(ns => capabilityNamespaces.includes(ns))
+  ) {
+    return `Ignoring Watch Callback: Binding namespace is not part of capability namespaces. Capability namespaces: ${capabilityNamespaces.join(
+      ", ",
+    )}, Binding namespaces: ${binding.filters.namespaces.join(", ")}.`;
+  }
+
+  // filter namespace is not the same of object namespace
+  if (
+    binding.filters &&
+    Array.isArray(binding.filters.namespaces) &&
+    binding.filters.namespaces.length > 0 &&
+    obj.metadata &&
+    obj.metadata.namespace &&
+    !binding.filters.namespaces.includes(obj.metadata.namespace)
+  ) {
+    return `Ignoring Watch Callback: Binding namespace and object namespace are not the same. Binding namespaces: ${binding.filters.namespaces.join(
+      ", ",
+    )}, Object namespace: ${obj.metadata.namespace}.`;
+  }
+
+  // no problems
+  return "";
+}
+
+export function addVerbIfNotExists(verbs: string[], verb: string) {
+  if (!verbs.includes(verb)) {
+    verbs.push(verb);
+  }
+}
+
+export function createRBACMap(capabilities: CapabilityExport[]): RBACMap {
+  return capabilities.reduce((acc: RBACMap, capability: CapabilityExport) => {
+    capability.bindings.forEach(binding => {
+      const key = `${binding.kind.group}/${binding.kind.version}/${binding.kind.kind}`;
+
+      acc["pepr.dev/v1/peprstore"] = {
+        verbs: ["create", "get", "patch", "watch"],
+        plural: "peprstores",
+      };
+
+      acc["apiextensions.k8s.io/v1/customresourcedefinition"] = {
+        verbs: ["patch", "create"],
+        plural: "customresourcedefinitions",
+      };
+
+      if (!acc[key] && binding.isWatch) {
+        acc[key] = {
+          verbs: ["watch"],
+          plural: binding.kind.plural || `${binding.kind.kind.toLowerCase()}s`,
+        };
+      }
+    });
+
+    return acc;
+  }, {});
+}
+
+export async function createDirectoryIfNotExists(path: string) {
+  try {
+    await fs.access(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await fs.mkdir(path, { recursive: true });
+    } else {
+      throw error;
+    }
+  }
+}
+
+export function hasEveryOverlap<T>(array1: T[], array2: T[]): boolean {
+  if (!Array.isArray(array1) || !Array.isArray(array2)) {
+    return false;
+  }
+
+  return array1.every(element => array2.includes(element));
+}
+
+export function hasAnyOverlap<T>(array1: T[], array2: T[]): boolean {
+  if (!Array.isArray(array1) || !Array.isArray(array2)) {
+    return false;
+  }
+
+  return array1.some(element => array2.includes(element));
+}
+
+export function ignoredNamespaceConflict(ignoreNamespaces: string[], bindingNamespaces: string[]) {
+  return hasAnyOverlap(bindingNamespaces, ignoreNamespaces);
+}
+
+export function bindingAndCapabilityNSConflict(bindingNamespaces: string[], capabilityNamespaces: string[]) {
+  if (!capabilityNamespaces) {
+    return false;
+  }
+  return capabilityNamespaces.length !== 0 && !hasEveryOverlap(bindingNamespaces, capabilityNamespaces);
+}
+
+export function generateWatchNamespaceError(
+  ignoredNamespaces: string[],
+  bindingNamespaces: string[],
+  capabilityNamespaces: string[],
+) {
+  let err = "";
+
+  // check if binding uses an ignored namespace
+  if (ignoredNamespaceConflict(ignoredNamespaces, bindingNamespaces)) {
+    err += `Binding uses a Pepr ignored namespace: ignoredNamespaces: [${ignoredNamespaces.join(
+      ", ",
+    )}] bindingNamespaces: [${bindingNamespaces.join(", ")}].`;
+  }
+
+  // ensure filter namespaces are part of capability namespaces
+  if (bindingAndCapabilityNSConflict(bindingNamespaces, capabilityNamespaces)) {
+    err += `Binding uses namespace not governed by capability: bindingNamespaces: [${bindingNamespaces.join(
+      ", ",
+    )}] capabilityNamespaces: [${capabilityNamespaces.join(", ")}].`;
+  }
+
+  // add a space if there is a period in the middle of the string
+  return err.replace(/\.([^ ])/g, ". $1");
+}
+
+// namespaceComplianceValidator ensures that capability bindinds respect ignored and capability namespaces
+export function namespaceComplianceValidator(capability: CapabilityExport, ignoredNamespaces?: string[]) {
+  const { namespaces: capabilityNamespaces, bindings, name } = capability;
+  const bindingNamespaces = bindings.flatMap(binding => binding.filters.namespaces);
+
+  const namespaceError = generateWatchNamespaceError(
+    ignoredNamespaces ? ignoredNamespaces : [],
+    bindingNamespaces,
+    capabilityNamespaces ? capabilityNamespaces : [],
+  );
+  if (namespaceError !== "") {
+    throw new Error(
+      `Error in ${name} capability. A binding violates namespace rules. Please check ignoredNamespaces and capability namespaces: ${namespaceError}`,
+    );
+  }
+}
+
+// check to see if all replicas are ready for all deployments in the pepr-system namespace
+// returns true if all deployments are ready, false otherwise
+export async function checkDeploymentStatus(namespace: string) {
+  const deployments = await K8s(kind.Deployment).InNamespace(namespace).Get();
+  let status = false;
+  let readyCount = 0;
+
+  for (const deployment of deployments.items) {
+    const readyReplicas = deployment.status?.readyReplicas ? deployment.status?.readyReplicas : 0;
+    if (deployment.status?.readyReplicas !== deployment.spec?.replicas) {
+      Log.info(
+        `Waiting for deployment ${deployment.metadata?.name} rollout to finish: ${readyReplicas} of ${deployment.spec?.replicas} replicas are available`,
+      );
+    } else {
+      Log.info(
+        `Deployment ${deployment.metadata?.name} rolled out: ${readyReplicas} of ${deployment.spec?.replicas} replicas are available`,
+      );
+      readyCount++;
+    }
+  }
+  if (readyCount === deployments.items.length) {
+    status = true;
+  }
+  return status;
+}
+
+// wait for all deployments in the pepr-system namespace to be ready
+export async function namespaceDeploymentsReady(namespace: string = "pepr-system") {
+  Log.info(`Checking ${namespace} deployments status...`);
+  let ready = false;
+  while (!ready) {
+    ready = await checkDeploymentStatus(namespace);
+    if (ready) {
+      return ready;
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+  Log.info(`All ${namespace} deployments are ready`);
+}
+
+// check if secret is over the size limit
+export function secretOverLimit(str: string): boolean {
+  const encoder = new TextEncoder();
+  const encoded = encoder.encode(str);
+  const sizeInBytes = encoded.length;
+  const oneMiBInBytes = 1048576;
+  return sizeInBytes > oneMiBInBytes;
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export const parseTimeout = (value: string, previous: unknown): number => {
+  const parsedValue = parseInt(value, 10);
+  const floatValue = parseFloat(value);
+  if (isNaN(parsedValue)) {
+    throw new Error("Not a number.");
+  } else if (parsedValue !== floatValue) {
+    throw new Error("Value must be an integer.");
+  } else if (parsedValue < 1 || parsedValue > 30) {
+    throw new Error("Number must be between 1 and 30.");
+  }
+  return parsedValue;
+};
+
+// Remove leading whitespace while keeping format of file
+export function dedent(file: string) {
+  // Check if the first line is empty and remove it
+  const lines = file.split("\n");
+  if (lines[0].trim() === "") {
+    lines.shift(); // Remove the first line if it's empty
+    file = lines.join("\n"); // Rejoin the remaining lines back into a single string
+  }
+
+  const match = file.match(/^[ \t]*(?=\S)/gm);
+  const indent = match && Math.min(...match.map(el => el.length));
+  if (indent && indent > 0) {
+    const re = new RegExp(`^[ \\t]{${indent}}`, "gm");
+    return file.replace(re, "");
+  }
+  return file;
+}
+
+export function replaceString(str: string, stringA: string, stringB: string) {
+  //eslint-disable-next-line
+  const escapedStringA = stringA.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const regExp = new RegExp(escapedStringA, "g");
+  return str.replace(regExp, stringB);
+}

package/src/lib/included-files.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { promises as fs } from "fs";
+
+export async function createDockerfile(version: string, description: string, includedFiles: string[]) {
+  const file = `
+    # Use an official Node.js runtime as the base image
+    FROM ghcr.io/defenseunicorns/pepr/controller:v${version}
+  
+    LABEL description="${description}"
+    
+    # Add the included files to the image
+    ${includedFiles.map(f => `ADD ${f} ${f}`).join("\n")}
+  
+    `;
+
+  await fs.writeFile("Dockerfile.controller", file, { encoding: "utf-8" });
+}

package/src/lib/k8s.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { GenericKind, GroupVersionKind, KubernetesObject, RegisterKind } from "kubernetes-fluent-client";
+
+export enum Operation {
+  CREATE = "CREATE",
+  UPDATE = "UPDATE",
+  DELETE = "DELETE",
+  CONNECT = "CONNECT",
+}
+
+/**
+ * PeprStore for internal use by Pepr. This is used to store arbitrary data in the cluster.
+ */
+export class PeprStore extends GenericKind {
+  declare data: {
+    [key: string]: string;
+  };
+}
+
+export const peprStoreGVK = {
+  kind: "PeprStore",
+  version: "v1",
+  group: "pepr.dev",
+};
+
+RegisterKind(PeprStore, peprStoreGVK);
+
+/**
+ * GroupVersionResource unambiguously identifies a resource. It doesn't anonymously include GroupVersion
+ * to avoid automatic coercion. It doesn't use a GroupVersion to avoid custom marshalling
+ */
+export interface GroupVersionResource {
+  readonly group: string;
+  readonly version: string;
+  readonly resource: string;
+}
+
+/**
+ * A Kubernetes admission request to be processed by a capability.
+ */
+export interface AdmissionRequest<T = KubernetesObject> {
+  /** UID is an identifier for the individual request/response. */
+  readonly uid: string;
+
+  /** Kind is the fully-qualified type of object being submitted (for example, v1.Pod or autoscaling.v1.Scale) */
+  readonly kind: GroupVersionKind;
+
+  /** Resource is the fully-qualified resource being requested (for example, v1.pods) */
+  readonly resource: GroupVersionResource;
+
+  /** SubResource is the sub-resource being requested, if any (for example, "status" or "scale") */
+  readonly subResource?: string;
+
+  /** RequestKind is the fully-qualified type of the original API request (for example, v1.Pod or autoscaling.v1.Scale). */
+  readonly requestKind?: GroupVersionKind;
+
+  /** RequestResource is the fully-qualified resource of the original API request (for example, v1.pods). */
+  readonly requestResource?: GroupVersionResource;
+
+  /** RequestSubResource is the sub-resource of the original API request, if any (for example, "status" or "scale"). */
+  readonly requestSubResource?: string;
+
+  /**
+   * Name is the name of the object as presented in the request. On a CREATE operation, the client may omit name and
+   * rely on the server to generate the name. If that is the case, this method will return the empty string.
+   */
+  readonly name: string;
+
+  /** Namespace is the namespace associated with the request (if any). */
+  readonly namespace?: string;
+
+  /**
+   * Operation is the operation being performed. This may be different than the operation
+   * requested. e.g. a patch can result in either a CREATE or UPDATE Operation.
+   */
+  readonly operation: Operation;
+
+  /** UserInfo is information about the requesting user */
+  readonly userInfo: {
+    /** The name that uniquely identifies this user among all active users. */
+    username?: string;
+
+    /**
+     * A unique value that identifies this user across time. If this user is deleted
+     * and another user by the same name is added, they will have different UIDs.
+     */
+    uid?: string;
+
+    /** The names of groups this user is a part of. */
+    groups?: string[];
+
+    /** Any additional information provided by the authenticator. */
+    extra?: {
+      [key: string]: string[];
+    };
+  };
+
+  /** Object is the object from the incoming request prior to default values being applied */
+  readonly object: T;
+
+  /** OldObject is the existing object. Only populated for UPDATE or DELETE requests. */
+  readonly oldObject?: T;
+
+  /** DryRun indicates that modifications will definitely not be persisted for this request. Defaults to false. */
+  readonly dryRun?: boolean;
+
+  /**
+   * Options contains the options for the operation being performed.
+   * e.g. `meta.k8s.io/v1.DeleteOptions` or `meta.k8s.io/v1.CreateOptions`. This may be
+   * different than the options the caller provided. e.g. for a patch request the performed
+   * Operation might be a CREATE, in which case the Options will a
+   * `meta.k8s.io/v1.CreateOptions` even though the caller provided `meta.k8s.io/v1.PatchOptions`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly options?: any;
+}
+
+export interface MutateResponse {
+  /** UID is an identifier for the individual request/response. This must be copied over from the corresponding AdmissionRequest. */
+  uid: string;
+
+  /** Allowed indicates whether or not the admission request was permitted. */
+  allowed: boolean;
+
+  /** Result contains extra details into why an admission request was denied. This field IS NOT consulted in any way if "Allowed" is "true". */
+  result?: string;
+
+  /** The patch body. Currently we only support "JSONPatch" which implements RFC 6902. */
+  patch?: string;
+
+  /** The type of Patch. Currently we only allow "JSONPatch". */
+  patchType?: "JSONPatch";
+
+  /**
+   * AuditAnnotations is an unstructured key value map set by remote admission controller (e.g. error=image-blacklisted).
+   *
+   * See https://kubernetes.io/docs/reference/labels-annotations-taints/audit-annotations/ for more information
+   */
+  auditAnnotations?: {
+    [key: string]: string;
+  };
+
+  /** warnings is a list of warning messages to return to the requesting API client. */
+  warnings?: string[];
+}
+
+export interface ValidateResponse extends MutateResponse {
+  /** Status contains extra details into why an admission request was denied. This field IS NOT consulted in any way if "Allowed" is "true". */
+  status?: {
+    /** A machine-readable description of why this operation is in the
+         "Failure" status. If this value is empty there is no information available. */
+    code: number;
+
+    /** A human-readable description of the status of this operation. */
+    message: string;
+  };
+}
+
+export type WebhookIgnore = {
+  /**
+   * List of Kubernetes namespaces to always ignore.
+   * Any resources in these namespaces will be ignored by Pepr.
+   *
+   * Note: `kube-system` and `pepr-system` are always ignored.
+   */
+  namespaces?: string[];
+};

package/src/lib/logger.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { pino, stdTimeFunctions } from "pino";
+
+const isPrettyLog = process.env.PEPR_PRETTY_LOGS === "true";
+
+const pretty = {
+  target: "pino-pretty",
+  options: {
+    colorize: true,
+  },
+};
+
+const transport = isPrettyLog ? pretty : undefined;
+// epochTime is the pino default
+const pinoTimeFunction =
+  process.env.PINO_TIME_STAMP === "iso" ? () => stdTimeFunctions.isoTime() : () => stdTimeFunctions.epochTime();
+const Log = pino({
+  transport,
+  timestamp: pinoTimeFunction,
+});
+
+if (process.env.LOG_LEVEL) {
+  Log.level = process.env.LOG_LEVEL;
+}
+export default Log;

package/src/lib/metrics.ts

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+/* eslint-disable class-methods-use-this */
+
+import { performance } from "perf_hooks";
+import promClient, { Counter, Registry, Summary } from "prom-client";
+import Log from "./logger";
+
+const loggingPrefix = "MetricsCollector";
+
+interface MetricNames {
+  errors: string;
+  alerts: string;
+  mutate: string;
+  validate: string;
+}
+
+interface MetricArgs {
+  name: string;
+  help: string;
+  registers: Registry[];
+}
+
+/**
+ * MetricsCollector class handles metrics collection using prom-client and performance hooks.
+ */
+export class MetricsCollector {
+  #registry: Registry;
+  #counters: Map<string, Counter<string>> = new Map();
+  #summaries: Map<string, Summary<string>> = new Map();
+  #prefix: string;
+
+  #metricNames: MetricNames = {
+    errors: "errors",
+    alerts: "alerts",
+    mutate: "Mutate",
+    validate: "Validate",
+  };
+
+  /**
+   * Creates a MetricsCollector instance with prefixed metrics.
+   * @param [prefix='pepr'] - The prefix for the metric names.
+   */
+  constructor(prefix = "pepr") {
+    this.#registry = new Registry();
+    this.#prefix = prefix;
+    this.addCounter(this.#metricNames.errors, "Mutation/Validate errors encountered");
+    this.addCounter(this.#metricNames.alerts, "Mutation/Validate bad api token received");
+    this.addSummary(this.#metricNames.mutate, "Mutation operation summary");
+    this.addSummary(this.#metricNames.validate, "Validation operation summary");
+  }
+
+  #getMetricName = (name: string) => `${this.#prefix}_${name}`;
+
+  #addMetric = <T extends Counter<string> | Summary<string>>(
+    collection: Map<string, T>,
+    MetricType: new (args: MetricArgs) => T,
+    name: string,
+    help: string,
+  ) => {
+    if (collection.has(this.#getMetricName(name))) {
+      Log.debug(`Metric for ${name} already exists`, loggingPrefix);
+      return;
+    }
+
+    const metric = new MetricType({
+      name: this.#getMetricName(name),
+      help,
+      registers: [this.#registry],
+    });
+
+    collection.set(this.#getMetricName(name), metric);
+  };
+
+  addCounter = (name: string, help: string) => {
+    this.#addMetric(this.#counters, promClient.Counter, name, help);
+  };
+
+  addSummary = (name: string, help: string) => {
+    this.#addMetric(this.#summaries, promClient.Summary, name, help);
+  };
+
+  incCounter = (name: string) => {
+    this.#counters.get(this.#getMetricName(name))?.inc();
+  };
+
+  /**
+   * Increments the error counter.
+   */
+  error = () => this.incCounter(this.#metricNames.errors);
+
+  /**
+   * Increments the alerts counter.
+   */
+  alert = () => this.incCounter(this.#metricNames.alerts);
+
+  /**
+   * Observes the duration since the provided start time and updates the summary.
+   * @param startTime - The start time.
+   * @param name - The metrics summary to increment.
+   */
+  observeEnd = (startTime: number, name: string = this.#metricNames.mutate) => {
+    this.#summaries.get(this.#getMetricName(name))?.observe(performance.now() - startTime);
+  };
+
+  /**
+   * Fetches the current metrics from the registry.
+   * @returns The metrics.
+   */
+  getMetrics = () => this.#registry.metrics();
+
+  /**
+   * Returns the current timestamp from performance.now() method. Useful for start timing an operation.
+   * @returns The timestamp.
+   */
+  static observeStart() {
+    return performance.now();
+  }
+}