Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(guardrails): bring upgrade-hook to parity with install-hook
Jose Ramirez2ee72ebf67ae
diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex 305db4444..d6708a2cb 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.460",+ "version": "0.1.461","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.460",+ "version": "0.1.461","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/image-policy": "file:../packages/image-policy",diff --git a/control-api/package.json b/control-api/package.jsonindex 5af12984c..0a440c422 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.460",+ "version": "0.1.461","description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets","main": "dist/main.js","engines": {diff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.tsindex 6164b38f3..b4c3af10d 100644--- a/control-api/src/routes/admin/registry.ts+++ b/control-api/src/routes/admin/registry.ts@@ -2168,10 +2168,14 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {}const llmHooksNs = config.llmHooksNamespace- let current: { spec?: Record<string, unknown> }+ let current: {+ spec?: Record<string, unknown>+ metadata?: { annotations?: Record<string, string>; labels?: Record<string, string> }+ }try {current = (await gateway.getResource('llmhooks', body.hookName, llmHooksNs)) as {spec?: Record<string, unknown>+ metadata?: { annotations?: Record<string, string>; labels?: Record<string, string> }}} catch (err) {res.status(404).json({@@ -2180,11 +2184,29 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {return}+ // The CR must be an upgrade OF THIS ENTRY. The only other cross-check is+ // target KIND, so naming a different entry silently re-pointed the hook at+ // another image while it inherited this CR's envSecret, capabilities,+ // imagePullSecrets and egressBindings — and kept claiming the original+ // catalog-id. The caller is an admin and so already in the TCB; the point is+ // that changing a hook's identity should be an explicit uninstall+install,+ // not a silent side effect of a mistyped entry name.+ const installedCatalogId = getCatalogId(current.metadata)+ if (installedCatalogId && installedCatalogId !== body.registryEntryName) {+ res.status(409).json({+ error: 'hook_entry_identity_mismatch',+ reason: `LlmHook "${body.hookName}" was installed from "${installedCatalogId}", not "${body.registryEntryName}" — uninstall and install to change entry`,+ })+ return+ }+// Preflight the new image (digest-pin + allowlist), mirroring install.const newImage = hookMeta.target.imagelet newDigest: string | undefinedif (newImage) {- if (!/@sha256:[0-9a-f]{64}$/.test(newImage.ref ?? '')) {+ // Anchored, and take the LAST @-segment: an unanchored test plus+ // split('@')[1] pinned "bar" for a ref like `repo@bar@sha256:…`.+ if (!/^[^@]+@sha256:[0-9a-f]{64}$/.test(newImage.ref ?? '')) {res.status(422).json({ error: 'image_ref_not_digest_pinned' })return}@@ -2195,7 +2217,7 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {res.status(422).json({ error: 'image_not_allowlisted', reason: newImage.ref })return}- newDigest = newImage.ref?.includes('@') ? newImage.ref.split('@')[1] : undefined+ newDigest = newImage.ref?.includes('@') ? newImage.ref.split('@').pop() : undefined}// Host-independent admissibility gates — upgrade-hook is the sanctioned@@ -2259,24 +2281,99 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {return}- // Build the upgraded spec: bump the version-shaped fields (image ref,- // port, path, lifecyclePoints) from the new hook_meta; PRESERVE the- // install-time credential/security wiring (envSecret, imagePullSecrets,- // security, egressBindings) and admin-set fields (capabilities/order/- // failMode/config) already on the CR.+ // Capability ceiling, re-checked on every referencing Host. Upgrade cannot+ // WIDEN capabilities (they are inherited from the CR), but a Host whose+ // capabilityCeiling was tightened after install would otherwise keep its+ // over-privileged hook through every subsequent upgrade — install is the+ // only other place the ceiling is ever enforced.+ const curCapabilities = Array.isArray((current.spec ?? {}).capabilities)+ ? ((current.spec ?? {}).capabilities as string[])+ : []+ if (curCapabilities.length > 0) {+ const overCeiling = referencingHosts+ .map(h => {+ const ceiling = h.spec?.guardrails?.capabilityCeiling ?? []+ const outside = curCapabilities.filter(c => !ceiling.includes(c))+ return outside.length > 0 ? { host: h.metadata?.name, outside } : null+ })+ .filter((x): x is { host: string | undefined; outside: string[] } => x !== null)+ if (overCeiling.length > 0) {+ res.status(403).json({+ error: 'capability_exceeds_ceiling',+ reason: `installed capabilities exceed the Host capabilityCeiling on: ${overCeiling+ .map(o => `${o.host} (${o.outside.join(', ')})`)+ .join('; ')}`,+ })+ return+ }+ }++ // An upgrade is exactly how a hook moves from a public image to a private+ // platform-registry one; without this the CR persists referencing a pull+ // secret that does not exist, the request returns 200, and the pod sits in+ // ImagePullBackOff while status.observedDigest never advances (so mcp-host+ // sees no digest mismatch and loads the descriptor anyway). Same guard the+ // recipe upgrade route already carries.+ const attachPullSecret = shouldAttachEvenfirePullSecret({+ isLocal: true,+ image: newImage?.ref,+ registryUrl: config.registryUrl,+ })+ if (attachPullSecret) {+ try {+ await ensureRegistryPullSecret(gateway, llmHooksNs)+ } catch (err) {+ const mapped = pullSecretErrorResponse(err)+ res.status(mapped.status).json(mapped.body)+ return+ }+ }++ // Build the upgraded spec from the NEW hook_meta, the same way install does.+ //+ // Only `envSecret` and `imagePullSecrets` are genuinely install-time (they+ // name Secrets this saga mints). `security`, `egressBindings` and+ // `contentAccess` all come from the registry entry, so they are+ // VERSION-SHAPED and must move with the version — previously they were+ // inherited from the old CR while assertHookAdmissible above had already+ // judged the NEW values, so the gate and the object it guards could disagree:+ // a v2 that dropped requiredEgress was admitted as egress-free yet kept the+ // old NetworkPolicy, and a v2 moving contentAccess metadata→content was+ // admitted as content-bearing while the CR stayed `metadata`, leaving+ // mcp-host's projection to strip every body — a moderation hook upgraded+ // into a no-op, with a 200.const curSpec = (current.spec ?? {}) as Record<string, unknown>const curTarget = (curSpec.target ?? {}) as Record<string, unknown>const curImage = (curTarget.image ?? {}) as Record<string, unknown>+ const hasEgress =+ Array.isArray(hookMeta.requiredEgress) && hookMeta.requiredEgress.length > 0const target: Record<string, unknown> = newImage- ? { image: { ...curImage, ref: newImage.ref, port: newImage.port } }+ ? {+ image: {+ ref: newImage.ref,+ port: newImage.port,+ ...(newImage.security ? { security: newImage.security } : {}),+ ...(curImage.envSecret ? { envSecret: curImage.envSecret } : {}),+ ...(hasEgress ? { egressBindings: hookMeta.requiredEgress } : {}),+ ...(attachPullSecret+ ? { imagePullSecrets: [EVENFIRE_REGISTRY_PULL_SECRET_NAME] }+ : curImage.imagePullSecrets+ ? { imagePullSecrets: curImage.imagePullSecrets }+ : {}),+ },+ }: hookMeta.target.service? { service: hookMeta.target.service }: { remote: hookMeta.target.remote }+ const { contentAccess: _staleContentAccess, ...curSpecSansContentAccess } = curSpecconst upgradedSpec: Record<string, unknown> = {- ...curSpec,+ ...curSpecSansContentAccess,target,- path: hookMeta.path ?? curSpec.path ?? '/',+ path: hookMeta.path ?? '/',lifecyclePoints: hookMeta.lifecyclePoints,+ ...(hookMeta.contentAccess === 'metadata' || hookMeta.contentAccess === 'content'+ ? { contentAccess: hookMeta.contentAccess }+ : {}),}// 1) Update the CR. 2) Move every referencing Host's ref (phases + pinned@@ -2284,13 +2381,38 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {// un-synced Hosts still pin the OLD digest → mcp-host quarantines the// hook there (fail-CLOSED, safe) until retried — surface a 207, not a// false success.- await updateResourceWithConflictRetry(- gateway,- 'llmhooks',- body.hookName,- { spec: upgradedSpec },- llmHooksNs- )+ // Restamp the catalog annotations. updateResource MERGES metadata.annotations+ // over current, so omitting metadata left catalog-version pinned at the old+ // version forever — getInstalledRegistryState builds its hookKeys from exactly+ // these, so the catalog kept reporting the pre-upgrade version and re-offering+ // the same upgrade — and left trust-level stale even though trustLevel was+ // just recomputed above. Both sibling upgrade routes already do this.+ try {+ await updateResourceWithConflictRetry(+ gateway,+ 'llmhooks',+ body.hookName,+ {+ metadata: {+ annotations: {+ ...catalogAnnotations(body.registryEntryName, body.registryEntryVersion),+ 'clerum.io/trust-level': trustLevel,+ },+ },+ spec: upgradedSpec,+ },+ llmHooksNs+ )+ } catch (err) {+ // A CEL rejection (e.g. a contentAccess/lifecyclePoint conflict) surfaced+ // as an unmapped 500; install maps these.+ const k8sErr = extractK8sError(err)+ if (k8sErr) {+ res.status(k8sErr.status).json({ error: k8sErr.message })+ return+ }+ throw err+ }let syncedHosts: string[]try {syncedHosts = await syncHookRefsInHosts(@@ -2305,14 +2427,41 @@ export function createAdminRegistryRouter(gateway?: K8sGateway): Router {res.status(207).json({hookName: body.hookName,digest: newDigest,+ registryEntry: body.registryEntryName,+ registryVersion: body.registryEntryVersion,+ // Only a may_deny hook denies on a digest mismatch; an advisory hook is+ // skipped-with-alert and contributes NOTHING, so a rewrite/redaction hook+ // silently stops applying on un-synced Hosts. Retrying is idempotent.warning:- 'CR upgraded but Host reference sync failed; referencing agents fail-closed until retried',+ 'CR upgraded but Host reference sync failed. Un-synced Hosts still pin the old digest: may_deny hooks fail closed there, advisory hooks are skipped and stop contributing. Retry this call.',})return}- auditLog('upgrade-hook', { hookName: body.hookName, digest: newDigest, syncedHosts })- res.status(200).json({ hookName: body.hookName, digest: newDigest, syncedHosts })+ // Registry install accounting — install and both sibling upgrades report;+ // hook upgrades were invisible. Promise.resolve() rather than a bare .catch()+ // so reporting can never fail an upgrade that already succeeded.+ const correlationId = crypto.randomUUID()+ void Promise.resolve(+ reportInstall(body.registryEntryName, correlationId, body.registryEntryVersion)+ ).catch(() => {})++ auditLog('upgrade-hook', {+ hookName: body.hookName,+ digest: newDigest,+ registryEntry: body.registryEntryName,+ registryVersion: body.registryEntryVersion,+ trustLevel,+ syncedHosts,+ })+ res.status(200).json({+ hookName: body.hookName,+ digest: newDigest,+ registryEntry: body.registryEntryName,+ registryVersion: body.registryEntryVersion,+ trustLevel,+ syncedHosts,+ })}))}diff --git a/control-api/test/routes.registryInstall.test.ts b/control-api/test/routes.registryInstall.test.tsindex 75dda3e5e..82e4f5158 100644--- a/control-api/test/routes.registryInstall.test.ts+++ b/control-api/test/routes.registryInstall.test.ts@@ -4342,12 +4342,27 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {...over,})- async function seedInstalledImageHook(gw: MockGateway, name = 'my-hook') {+ async function seedInstalledImageHook(+ gw: MockGateway,+ name = 'my-hook',+ overrides: { annotations?: Record<string, string>; spec?: Record<string, unknown> } = {}+ ) {await gw.createResource('llmhooks',{- metadata: { name },- spec: { target: { image: { ref: IMG_A, port: 8080 } }, lifecyclePoints: ['preCall'] },+ metadata: {+ name,+ annotations: overrides.annotations ?? {+ 'clerum.io/catalog-id': '@acme/hook',+ 'clerum.io/catalog-version': '1.0.0',+ 'clerum.io/trust-level': 'low',+ },+ },+ spec: {+ target: { image: { ref: IMG_A, port: 8080 } },+ lifecyclePoints: ['preCall'],+ ...(overrides.spec ?? {}),+ },},config.llmHooksNamespace)@@ -4355,7 +4370,14 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {it('refuses an image→remote upgrade that becomes content-bearing + remote at low trust (the exploit)', async () => {const gw = new MockGateway()- await seedInstalledImageHook(gw)+ // catalog-id matches the entry named below, so this exercises the KIND/TRUST+ // gates rather than the entry-identity check.+ await seedInstalledImageHook(gw, 'my-hook', {+ annotations: {+ 'clerum.io/catalog-id': '@attacker/hook',+ 'clerum.io/catalog-version': '1.0.0',+ },+ })vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)// @attacker is neither the cluster org nor official → capped at defaultHookTrustCap.vi.mocked(getEntryVersion).mockResolvedValue(@@ -4387,7 +4409,9 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {it('refuses changing the target kind on upgrade even when trust is high (image→remote)', async () => {const gw = new MockGateway()- await seedInstalledImageHook(gw)+ await seedInstalledImageHook(gw, 'my-hook', {+ annotations: { 'clerum.io/catalog-id': '@clerum/hook', 'clerum.io/catalog-version': '1.0.0' },+ })vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)// @clerum is official → curated → trust honored as high, so the content/egress// gate passes; target-kind immutability then blocks the re-target.@@ -4413,6 +4437,113 @@ describe('POST /admin/registry/upgrade-hook — gates are not bypassed', () => {expect(res.body.error).toBe('hook_target_kind_immutable')})+ it('restamps the catalog annotations and the resolved trust level', async () => {+ const gw = new MockGateway()+ await seedInstalledImageHook(gw)+ vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)+ vi.mocked(getEntryVersion).mockResolvedValue(+ hookEntry({+ name: '@acme/hook',+ trust_level: 'high',+ hook_meta: { target: { image: { ref: IMG_B, port: 8080 } }, lifecyclePoints: ['preCall'] },+ })+ )++ const res = await request(makeApp(gw))+ .post('/admin/registry/upgrade-hook')+ .send({ hookName: 'my-hook', registryEntryName: '@acme/hook', registryEntryVersion: '2.0.0' })+ .expect(200)+ // the response and the audit trail must name the version that was installed+ expect(res.body.registryVersion).toBe('2.0.0')+ expect(res.body.trustLevel).toBe('high')++ const cr = (await gw.getResource('llmhooks', 'my-hook', config.llmHooksNamespace)) as {+ metadata: { annotations: Record<string, string> }+ }+ // without the restamp these stayed at 1.0.0 / low forever, and+ // getInstalledRegistryState kept re-offering the same upgrade+ expect(cr.metadata.annotations['clerum.io/catalog-version']).toBe('2.0.0')+ expect(cr.metadata.annotations['clerum.io/trust-level']).toBe('high')+ })++ it('refuses an upgrade that names a different entry than the one installed', async () => {+ const gw = new MockGateway()+ await seedInstalledImageHook(gw)+ vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)+ vi.mocked(getEntryVersion).mockResolvedValue(+ hookEntry({+ name: '@acme/other-hook',+ trust_level: 'low',+ hook_meta: { target: { image: { ref: IMG_B, port: 8080 } }, lifecyclePoints: ['preCall'] },+ })+ )++ const res = await request(makeApp(gw))+ .post('/admin/registry/upgrade-hook')+ .send({+ hookName: 'my-hook',+ registryEntryName: '@acme/other-hook',+ registryEntryVersion: '1.0.0',+ })+ .expect(409)+ expect(res.body.error).toBe('hook_entry_identity_mismatch')+ // nothing was written+ const cr = (await gw.getResource('llmhooks', 'my-hook', config.llmHooksNamespace)) as {+ spec: { target: { image: { ref: string } } }+ }+ expect(cr.spec.target.image.ref).toBe(IMG_A)+ })++ it('moves egressBindings and contentAccess with the version instead of inheriting them', async () => {+ const gw = new MockGateway()+ // v1: a metadata-only preCall shaper WITH egress+ await seedInstalledImageHook(gw, 'my-hook', {+ spec: {+ contentAccess: 'metadata',+ target: {+ image: {+ ref: IMG_A,+ port: 8080,+ envSecret: 'my-hook-creds',+ egressBindings: [{ toFQDN: 'old.example', ports: [443] }],+ },+ },+ },+ })+ vi.mocked(resolvePublishScope).mockResolvedValue(clusterScope)+ // v2 drops the egress and becomes a real content inspector+ vi.mocked(getEntryVersion).mockResolvedValue(+ hookEntry({+ name: '@acme/hook',+ trust_level: 'low',+ hook_meta: {+ target: { image: { ref: IMG_B, port: 8080 } },+ lifecyclePoints: ['preCall'],+ contentAccess: 'content',+ },+ })+ )++ await request(makeApp(gw))+ .post('/admin/registry/upgrade-hook')+ .send({ hookName: 'my-hook', registryEntryName: '@acme/hook', registryEntryVersion: '2.0.0' })+ .expect(200)++ const cr = (await gw.getResource('llmhooks', 'my-hook', config.llmHooksNamespace)) as {+ spec: {+ contentAccess?: string+ target: { image: { egressBindings?: unknown[]; envSecret?: string } }+ }+ }+ // the reviewed egress REDUCTION must land — previously the old rule persisted+ expect(cr.spec.target.image.egressBindings).toBeUndefined()+ // and the hook must actually receive bodies — previously it stayed 'metadata'+ // and mcp-host's projection stripped every message, a silent no-op upgrade+ expect(cr.spec.contentAccess).toBe('content')+ // install-time wiring is still preserved+ expect(cr.spec.target.image.envSecret).toBe('my-hook-creds')+ })+it('allows a same-kind image→image digest bump', async () => {const gw = new MockGateway()await seedInstalledImageHook(gw)