@raishin/vanguard-frontier-agentic 1.8.0 → 2.0.0

package/tests/fuzz-properties.test.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Property-based fuzz tests for security-critical logic in the exporter.
+ *
+ * Uses fast-check to generate adversarial inputs and verify the invariants
+ * that guard against path traversal, ID injection, and platform instability.
+ *
+ * Run: node tests/fuzz-properties.test.mjs
+ *
+ * Satisfies OpenSSF Scorecard FuzzingID requirement for JS/TS projects.
+ * Reference: https://github.com/ossf/scorecard/blob/main/docs/checks.md#fuzzing
+ */
+
+import assert from "node:assert/strict";
+import path from "node:path";
+import fc from "fast-check";
+
+// ── Security-critical implementations under test ─────────────────────────────
+// Reproduced verbatim from scripts/export-marketplace-agents.mjs.
+
+function assertWithin(parent, child, label) {
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  const sep = path.sep;
+  const parentWithSep = resolvedParent.endsWith(sep)
+    ? resolvedParent
+    : resolvedParent + sep;
+  if (
+    resolvedChild !== resolvedParent &&
+    !resolvedChild.startsWith(parentWithSep)
+  ) {
+    throw new Error(
+      `Refusing to ${label}: path '${resolvedChild}' escapes '${resolvedParent}'.`
+    );
+  }
+}
+
+const AGENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+const HARNESS_PATH_TRAVERSAL =
+  /[\\/]\.\.[\\/]|^\.\.[\\/]|[\\/]\.\.$|^\.\.$/;
+
+function normalizePlatform(platform, aliases) {
+  const lowered = platform.toLowerCase();
+  return Object.hasOwn(aliases, lowered) ? aliases[lowered] : lowered;
+}
+
+const ALIASES = {
+  claude: "claude-code",
+  kiroide: "kiro-ide",
+  kirocli: "kiro-cli",
+};
+
+// ── Arbitraries ───────────────────────────────────────────────────────────────
+
+const safeSegment = fc.stringMatching(/^[a-z0-9][a-z0-9-]{0,15}$/);
+const safeRelPath = fc
+  .array(safeSegment, { minLength: 1, maxLength: 4 })
+  .map((segs) => segs.join("/"));
+
+// ── 1. assertWithin ──────────────────────────────────────────────────────────
+
+fc.assert(
+  fc.property(
+    fc.string({ minLength: 1, maxLength: 50 }),
+    (dir) => {
+      assert.doesNotThrow(() => assertWithin(dir, dir, "test"));
+    }
+  ),
+  { numRuns: 200 }
+);
+console.log("PASS  assertWithin: parent is always within itself");
+
+fc.assert(
+  fc.property(
+    fc.string({ minLength: 1, maxLength: 30 }),
+    safeSegment,
+    (dir, name) => {
+      const child = path.join(dir, name);
+      assert.doesNotThrow(() => assertWithin(dir, child, "test"));
+    }
+  ),
+  { numRuns: 200 }
+);
+console.log("PASS  assertWithin: direct child is always within parent");
+
+fc.assert(
+  fc.property(safeSegment, safeSegment, (a, b) => {
+    if (a === b) return;
+    const parent = `/sandbox/${a}`;
+    const outside = `/sandbox/${b}`;
+    const resolvedParent = path.resolve(parent);
+    const resolvedOutside = path.resolve(outside);
+    const sep = path.sep;
+    if (
+      resolvedOutside !== resolvedParent &&
+      !resolvedOutside.startsWith(resolvedParent + sep)
+    ) {
+      assert.throws(
+        () => assertWithin(parent, outside, "read source"),
+        /escapes/
+      );
+    }
+  }),
+  { numRuns: 200 }
+);
+console.log("PASS  assertWithin: sibling paths outside parent always throw");
+
+fc.assert(
+  fc.property(safeSegment, safeSegment, (parentName, childName) => {
+    const parent = path.join("/sandbox", parentName);
+    const traversed = path.join(parent, "..", childName);
+    if (path.resolve(traversed) === path.resolve(parent)) return;
+    assert.throws(
+      () => assertWithin(parent, traversed, "read source"),
+      /escapes/
+    );
+  }),
+  { numRuns: 200 }
+);
+console.log("PASS  assertWithin: '..' traversal always escapes and always throws");
+
+// ── 2. Agent ID allowlist ────────────────────────────────────────────────────
+
+fc.assert(
+  fc.property(
+    fc.string({ minLength: 1, maxLength: 40 }).filter((s) => /[A-Z]/.test(s)),
+    (id) => {
+      assert.equal(AGENT_ID_PATTERN.test(id), false);
+    }
+  ),
+  { numRuns: 200 }
+);
+console.log("PASS  agent ID: uppercase letters always rejected");
+
+for (const bad of [
+  "../etc/passwd",
+  "../../secret",
+  "a/b",
+  "a\\b",
+  "a\x00b",
+  "a b",
+  ".hidden",
+  "a!b",
+  "A-good-id",
+]) {
+  assert.equal(AGENT_ID_PATTERN.test(bad), false, `Expected ${JSON.stringify(bad)} to fail`);
+}
+console.log("PASS  agent ID: path separators, spaces, dots, control chars always rejected");
+
+fc.assert(
+  fc.property(
+    fc.stringMatching(/^[a-z0-9][a-z0-9-]{0,40}$/),
+    (id) => {
+      assert.equal(AGENT_ID_PATTERN.test(id), true);
+    }
+  ),
+  { numRuns: 200 }
+);
+console.log("PASS  agent ID: valid kebab-case IDs always accepted");
+
+// ── 3. Harness path traversal guard ──────────────────────────────────────────
+
+for (const bad of ["..", "../", "../foo", "foo/../bar", "foo/.."])  {
+  assert.equal(HARNESS_PATH_TRAVERSAL.test(bad), true, `Expected traversal in ${JSON.stringify(bad)}`);
+}
+console.log("PASS  harness path: known traversal patterns detected");
+
+fc.assert(
+  fc.property(fc.string({ maxLength: 40 }), (suffix) => {
+    assert.equal(HARNESS_PATH_TRAVERSAL.test(`../${suffix}`), true);
+  }),
+  { numRuns: 200 }
+);
+console.log("PASS  harness path: paths starting with '../' always flagged");
+
+fc.assert(
+  fc.property(safeSegment, safeSegment, (before, after) => {
+    assert.equal(HARNESS_PATH_TRAVERSAL.test(`${before}/../${after}`), true);
+  }),
+  { numRuns: 200 }
+);
+console.log("PASS  harness path: '/../' in the middle always flagged");
+
+fc.assert(
+  fc.property(safeRelPath, (relPath) => {
+    assert.equal(HARNESS_PATH_TRAVERSAL.test(relPath), false);
+  }),
+  { numRuns: 200 }
+);
+console.log("PASS  harness path: clean relative paths never flagged");
+
+// ── 4. normalizePlatform stability ──────────────────────────────────────────
+
+fc.assert(
+  fc.property(fc.string({ maxLength: 50 }), (platform) => {
+    const result = normalizePlatform(platform, ALIASES);
+    assert.equal(typeof result, "string");
+    assert.equal(result, result.toLowerCase());
+  }),
+  { numRuns: 500 }
+);
+console.log("PASS  normalizePlatform: never throws, always returns lowercase string");
+
+for (const [alias, canonical] of Object.entries(ALIASES)) {
+  assert.equal(normalizePlatform(alias, ALIASES), canonical);
+  assert.equal(normalizePlatform(alias.toUpperCase(), ALIASES), canonical);
+}
+console.log("PASS  normalizePlatform: known aliases resolve to canonical form");
+
+console.log("\nAll fuzz properties passed.");

package/tests/integration/rbac-pre-flight/README.md

@@ -0,0 +1,160 @@
+# RBAC Pre-flight Integration Tests
+
+Regression harness for the least-privilege RBAC bindings of all 7 Vanguard
+Kubernetes live-guard agents. The suite creates a real kind cluster, applies
+each guard's `least-privilege-rbac.yaml`, and then asserts every row in the
+`rbac-pre-flight.md` matrices — both the universal must-not-be-yes block and
+each guard's domain-specific checks.
+
+Running this suite after any change to an RBAC manifest catches privilege
+creep and under-scoping before the change reaches a production cluster.
+
+---
+
+## Purpose
+
+Kubernetes RBAC semantics evolve across minor versions. An RBAC manifest that
+is correctly scoped on 1.28 may silently acquire broader rights on 1.30 if a
+new built-in ClusterRole or defaulting behavior changes. This suite pins the
+expected can-i matrix for every guard so that changes to Kubernetes itself,
+or accidental edits to the manifests, are caught immediately in CI.
+
+---
+
+## Requirements
+
+| Tool   | Minimum version |
+|--------|----------------|
+| kind   | 0.22            |
+| k3d    | 5.6 (alternative to kind) |
+| kubectl | 1.28           |
+| bash   | 4.0+            |
+
+The tests do not require Docker Desktop — rootless Docker or Podman work as
+long as kind can reach them.
+
+---
+
+## Running locally
+
+```bash
+# Full run: creates a kind cluster, tests all guards, destroys the cluster
+cd tests/integration/rbac-pre-flight
+./run-all.sh
+
+# Use a specific Kubernetes version (default: v1.30.6)
+KIND_K8S_VERSION=v1.29.10 ./run-all.sh
+
+# Skip cluster creation and run against your current kubeconfig context
+./run-all.sh --skip-cluster-create
+
+# Run only one guard
+./run-all.sh --guard=rbac-mutation
+
+# Combine flags
+./run-all.sh --skip-cluster-create --guard=network-arch
+```
+
+A timestamped log is always written to `/tmp/rbac-preflight-<timestamp>.log`.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | All assertions passed (SKIP rows do not count as failures) |
+| 1    | One or more assertions failed |
+
+---
+
+## How CI works
+
+The GitHub Actions workflow is at `ci/kind-rbac-preflight.yaml`. It triggers
+on any change to:
+
+- `agents/**/references/least-privilege-rbac.yaml`
+- `skills/**/references/least-privilege-rbac.yaml`
+- `agents/**/references/rbac-pre-flight.md`
+- `skills/**/references/rbac-pre-flight.md`
+- `tests/integration/rbac-pre-flight/**`
+
+The workflow runs `run-all.sh` in a matrix across four Kubernetes versions
+(1.28, 1.29, 1.30, 1.31) using `fail-fast: false` so all matrix legs
+complete even when one fails. On failure, the log file is uploaded as a
+GitHub Actions artifact.
+
+---
+
+## Understanding SKIP rows
+
+Several domain-specific checks target CRDs that are not installed in a
+vanilla kind cluster:
+
+| CRD group | Example guard | Pre-install URL |
+|-----------|--------------|-----------------|
+| `gateway.networking.k8s.io` | network-arch | https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml |
+| `cilium.io` | network-policy | https://docs.cilium.io/en/stable/installation/k8s-install-helm/ |
+| `security.istio.io`, `networking.istio.io` | mesh-policy | https://istio.io/latest/docs/setup/install/ |
+| `kyverno.io` | admission-policy | https://kyverno.io/docs/installation/ |
+| `argoproj.io` | argocd-sync | https://argo-cd.readthedocs.io/en/stable/getting_started/ |
+| `velero.io` | velero-restore | https://velero.io/docs/latest/basic-install/ |
+
+SKIP rows are informational — the binding cannot be checked without the CRD
+present. To validate those rows, pre-apply the CRDs before running the suite:
+
+```bash
+# Example: test Gateway API rows
+kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
+./run-all.sh --skip-cluster-create
+```
+
+---
+
+## Note on impersonation
+
+`kubectl auth can-i --as=<serviceaccount>` requires the requesting principal
+to have `impersonate` rights. In a kind cluster where you start as
+cluster-admin this works without additional configuration. The manifests
+themselves grant no impersonation rights to the guard ServiceAccounts.
+
+If you are running `--skip-cluster-create` against a hardened cluster, ensure
+your kubeconfig principal has `impersonate` on `users`, `groups`, and
+`serviceaccounts`.
+
+---
+
+## Adding a new guard
+
+1. Copy an existing file in `guards/` and rename it.
+2. Update the `SA` variable to the new ServiceAccount name.
+3. Call `run_universal_must_not "$SA"` at the top.
+4. Add domain-specific `assert_can` / `assert_cannot` calls extracted from
+   the guard's `references/rbac-pre-flight.md`.
+5. Call `report_guard "<guard-name>"` at the end.
+6. Register the new guard in `run-all.sh`:
+   - Add an entry to the `GUARD_FN` associative array.
+   - Add the guard name to `GUARD_ORDER`.
+   - Source the new file with `source "$SCRIPT_DIR/guards/<name>.sh"`.
+
+---
+
+## File layout
+
+```
+tests/integration/rbac-pre-flight/
+  README.md                  — this file
+  run-all.sh                 — main entrypoint
+  lib/
+    common.sh                — assert_can / assert_cannot helpers
+  guards/
+    network-arch.sh          — network-architecture-mutation guard
+    network-policy.sh        — network-policy guard
+    mesh-policy.sh           — mesh-policy guard
+    admission-policy.sh      — admission-policy guard
+    argocd-sync.sh           — argocd-sync guard
+    rbac-mutation.sh         — rbac-mutation guard
+    velero-restore.sh        — velero-restore guard
+  ci/
+    kind-rbac-preflight.yaml — GitHub Actions workflow
+```

package/tests/integration/rbac-pre-flight/ci/kind-rbac-preflight.yaml

@@ -0,0 +1,49 @@
+name: RBAC Pre-flight Integration Test
+
+on:
+  push:
+    paths:
+      - 'agents/**/references/least-privilege-rbac.yaml'
+      - 'skills/**/references/least-privilege-rbac.yaml'
+      - 'agents/**/references/rbac-pre-flight.md'
+      - 'skills/**/references/rbac-pre-flight.md'
+      - 'tests/integration/rbac-pre-flight/**'
+  pull_request:
+    paths:
+      - 'agents/**/references/least-privilege-rbac.yaml'
+      - 'skills/**/references/least-privilege-rbac.yaml'
+      - 'agents/**/references/rbac-pre-flight.md'
+      - 'skills/**/references/rbac-pre-flight.md'
+      - 'tests/integration/rbac-pre-flight/**'
+  workflow_dispatch: {}
+
+jobs:
+  rbac-pre-flight:
+    name: RBAC Pre-flight (${{ matrix.k8s-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        k8s-version: ['v1.28.15', 'v1.29.10', 'v1.30.6', 'v1.31.2']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install kind
+        uses: helm/kind-action@v1.10.0
+        with:
+          install_only: true
+
+      - name: Run RBAC pre-flight tests
+        run: |
+          chmod +x tests/integration/rbac-pre-flight/run-all.sh
+          tests/integration/rbac-pre-flight/run-all.sh
+        env:
+          KIND_K8S_VERSION: ${{ matrix.k8s-version }}
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: rbac-preflight-results-${{ matrix.k8s-version }}
+          path: /tmp/rbac-preflight-*.log

package/tests/integration/rbac-pre-flight/guards/admission-policy.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# guards/admission-policy.sh — RBAC pre-flight for kubernetes-live-admission-policy-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_admission_policy() {
+  begin_guard "admission-policy"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-admission-policy-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-admission-policy-guard-agent/references/rbac-pre-flight.md)
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Webhook configurations — operator install only
+  # Note: create mutatingwebhookconfigurations already covered by universal block;
+  # these additional verbs are domain-specific.
+  assert_cannot patch mutatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot patch validatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+
+  # Delete on policies — rollback via apply -f baseline
+  # Kyverno CRDs may not exist in vanilla kind
+  assert_cannot_or_skip delete clusterpolicies.kyverno.io "--as=$SA"
+  assert_cannot delete validatingadmissionpolicies.admissionregistration.k8s.io "--as=$SA"
+
+  # Kyverno control plane (namespace always exists once kyverno is installed;
+  # patch deployments/configmaps check works even if kyverno is absent — returns no)
+  assert_cannot patch deployments -n kyverno "--as=$SA"
+  assert_cannot patch configmaps -n kyverno "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Kyverno CRDs — skip not fail if absent
+  assert_can_or_skip create clusterpolicies.kyverno.io "--as=$SA"
+  assert_can_or_skip patch clusterpolicies.kyverno.io "--as=$SA"
+  assert_can_or_skip create policies.kyverno.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create policyexceptions.kyverno.io --all-namespaces "--as=$SA"
+  assert_can_or_skip list clusterpolicies.kyverno.io "--as=$SA"
+
+  # ValidatingAdmissionPolicy is GA in 1.30+, available in 1.28+ as beta
+  assert_can create validatingadmissionpolicies.admissionregistration.k8s.io "--as=$SA"
+
+  report_guard "admission-policy"
+}

package/tests/integration/rbac-pre-flight/guards/argocd-sync.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# guards/argocd-sync.sh — RBAC pre-flight for kubernetes-live-argocd-sync-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_argocd_sync() {
+  begin_guard "argocd-sync"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-argocd-sync-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-argocd-sync-guard-agent/references/rbac-pre-flight.md)
+  # All Argo CD CRDs are absent in vanilla kind — use assert_cannot_or_skip.
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes (Argo CD CRDs, SKIP if absent) --%b\n' "$_CYAN" "$_RESET"
+
+  # Delete on Argo CD resources — rollback via apply -f baseline
+  assert_cannot_or_skip delete applications.argoproj.io --all-namespaces "--as=$SA"
+  assert_cannot_or_skip delete applicationsets.argoproj.io --all-namespaces "--as=$SA"
+  assert_cannot_or_skip delete appprojects.argoproj.io --all-namespaces "--as=$SA"
+
+  # AppProject and ApplicationSet writes — GitOps-only territory
+  assert_cannot_or_skip create appprojects.argoproj.io -n argocd "--as=$SA"
+  assert_cannot_or_skip patch appprojects.argoproj.io -n argocd "--as=$SA"
+  assert_cannot_or_skip create applicationsets.argoproj.io -n argocd "--as=$SA"
+  assert_cannot_or_skip patch applicationsets.argoproj.io -n argocd "--as=$SA"
+
+  # Argo CD control plane (standard resources — not CRD-dependent)
+  assert_cannot patch deployments -n argocd "--as=$SA"
+  assert_cannot patch configmaps -n argocd "--as=$SA"
+  assert_cannot get secrets -n argocd "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # Argo CD CRDs — skip not fail if absent
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes (Argo CD CRDs, SKIP if absent) --%b\n' "$_CYAN" "$_RESET"
+
+  assert_can_or_skip list applications.argoproj.io -n argocd "--as=$SA"
+  assert_can_or_skip list applicationsets.argoproj.io -n argocd "--as=$SA"
+  assert_can_or_skip list appprojects.argoproj.io -n argocd "--as=$SA"
+  assert_can_or_skip patch applications.argoproj.io -n argocd "--as=$SA"
+
+  report_guard "argocd-sync"
+}

package/tests/integration/rbac-pre-flight/guards/mesh-policy.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# guards/mesh-policy.sh — RBAC pre-flight for kubernetes-live-mesh-policy-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_mesh_policy() {
+  begin_guard "mesh-policy"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-mesh-policy-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-mesh-policy-guard-agent/references/rbac-pre-flight.md)
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Delete on policies — rollback is via apply -f baseline, not delete
+  # Istio CRDs may not exist in vanilla kind
+  assert_cannot_or_skip delete authorizationpolicies.security.istio.io --all-namespaces "--as=$SA"
+  assert_cannot_or_skip delete peerauthentications.security.istio.io --all-namespaces "--as=$SA"
+
+  # istio-system control plane — core resources always present even without Istio CRDs
+  assert_cannot patch deployments -n istio-system "--as=$SA"
+  assert_cannot patch configmaps -n istio-system "--as=$SA"
+
+  # Istio Gateway resources — delegated to network-architecture guard
+  assert_cannot_or_skip create gateways.networking.istio.io --all-namespaces "--as=$SA"
+  assert_cannot_or_skip patch gateways.networking.istio.io --all-namespaces "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # Istio CRDs — skip not fail if absent in vanilla kind
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes (Istio CRDs, SKIP if absent) --%b\n' "$_CYAN" "$_RESET"
+
+  assert_can_or_skip create authorizationpolicies.security.istio.io --all-namespaces "--as=$SA"
+  assert_can_or_skip patch authorizationpolicies.security.istio.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create peerauthentications.security.istio.io --all-namespaces "--as=$SA"
+  assert_can_or_skip patch peerauthentications.security.istio.io --all-namespaces "--as=$SA"
+  assert_can_or_skip list virtualservices.networking.istio.io --all-namespaces "--as=$SA"
+  assert_can_or_skip list peerauthentications.security.istio.io --all-namespaces "--as=$SA"
+
+  report_guard "mesh-policy"
+}