Skip to content

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.json
index 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.json
index 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.ts
index 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.image
let newDigest: string | undefined
if (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 > 0
const 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 } = curSpec
const 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.ts
index 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)