✨ feat(api): identity-keyed container tracking for audit events and recent status

- Extract getContainerIdentityKey from store to model/container for shared use
- Add containerIdentityKey to audit entries for stable cross-rename tracking
- Return statusesByIdentity alongside statuses in recent-status endpoint
- Update OpenAPI schema to include statusesByIdentity in response contract

Author: s-b-e-n-s-o-n

app/api/audit-events.test.ts

@@ -27,7 +27,9 @@ describe('recordAuditEvent', () => {
       action: 'rollback',
       status: 'success',
       container: {
+        agent: 'edge-a',
         name: 'nginx',
+        watcher: 'docker-prod',
         image: { name: 'library/nginx' },
       },
       fromVersion: '1.24.0',
@@ -40,6 +42,7 @@ describe('recordAuditEvent', () => {
         action: 'rollback',
         status: 'success',
         containerName: 'nginx',
+        containerIdentityKey: 'edge-a::docker-prod::nginx',
         containerImage: 'library/nginx',
         fromVersion: '1.24.0',
         toVersion: '1.23.0',
@@ -63,4 +66,21 @@ describe('recordAuditEvent', () => {
 
     expect(mockInsertAudit).toHaveBeenCalled();
   });
+
+  test('should omit containerIdentityKey when the container has no watcher identity', () => {
+    recordAuditEvent({
+      action: 'container-update',
+      status: 'success',
+      container: {
+        name: 'nginx',
+        image: { name: 'library/nginx' },
+      },
+    });
+
+    expect(mockInsertAudit).toHaveBeenCalledWith(
+      expect.not.objectContaining({
+        containerIdentityKey: expect.any(String),
+      }),
+    );
+  });
 });

app/api/audit-events.ts

@@ -1,4 +1,5 @@
 import type { AuditEntry } from '../model/audit.js';
+import { getContainerIdentityKey } from '../model/container.js';
 import { getAuditCounter } from '../prometheus/audit.js';
 import * as auditStore from '../store/audit.js';
 
@@ -14,6 +15,8 @@ type RecordAuditEventArgs = {
   | {
       container: {
         name: AuditEntry['containerName'];
+        watcher?: string;
+        agent?: string;
         image?: { name?: AuditContainerImage };
       };
       containerName?: AuditEntry['containerName'];
@@ -42,12 +45,14 @@ export function recordAuditEvent({
   fromVersion,
   toVersion,
 }: RecordAuditEventArgs) {
+  const containerIdentityKey = container ? getContainerIdentityKey(container) : undefined;
   const entry: AuditEntry = {
     id: '',
     timestamp: new Date().toISOString(),
     action,
     containerName,
     containerImage,
+    ...(containerIdentityKey !== undefined ? { containerIdentityKey } : {}),
     status,
     ...(details !== undefined ? { details } : {}),
     ...(fromVersion !== undefined ? { fromVersion } : {}),

app/api/container.test.ts

@@ -753,10 +753,26 @@ describe('Container Router', () => {
   describe('getContainerRecentStatus', () => {
     test('should return the latest status per container using recent audit entries', () => {
       auditStore.getRecentEntries.mockReturnValue([
-        { containerName: 'api', action: 'update-failed' },
-        { containerName: 'api', action: 'update-applied' },
-        { containerName: 'worker', action: 'update-applied' },
-        { containerName: 'cache', action: 'update-available' },
+        {
+          containerName: 'api',
+          containerIdentityKey: 'edge-a::docker-prod::api',
+          action: 'update-failed',
+        },
+        {
+          containerName: 'api',
+          containerIdentityKey: 'edge-a::docker-prod::api',
+          action: 'update-applied',
+        },
+        {
+          containerName: 'worker',
+          containerIdentityKey: 'edge-b::docker-prod::worker',
+          action: 'update-applied',
+        },
+        {
+          containerName: 'cache',
+          containerIdentityKey: '::local::cache',
+          action: 'update-available',
+        },
         { containerName: 'ignore-me', action: 'container-update' },
       ]);
 
@@ -772,7 +788,20 @@ describe('Container Router', () => {
           cache: 'pending',
           worker: 'updated',
         },
+        statusesByIdentity: {
+          '::local::cache': 'pending',
+          'edge-a::docker-prod::api': 'failed',
+          'edge-b::docker-prod::worker': 'updated',
+        },
       });
+      const contractValidation = validateOpenApiJsonResponse({
+        path: '/api/containers/recent-status',
+        method: 'get',
+        statusCode: '200',
+        payload: res.json.mock.calls[0][0],
+      });
+      expect(contractValidation.valid).toBe(true);
+      expect(contractValidation.errors).toStrictEqual([]);
     });
 
     test('should ignore invalid entries and empty container names', () => {
@@ -781,6 +810,16 @@ describe('Container Router', () => {
         { action: 'update-failed' },
         { containerName: ' ', action: 'update-failed' },
         { containerName: 'trim-me', action: 'update-applied' },
+        {
+          containerName: 'duplicate-name',
+          containerIdentityKey: 'edge-a::docker-a::duplicate-name',
+          action: 'update-failed',
+        },
+        {
+          containerName: 'duplicate-name',
+          containerIdentityKey: 'edge-b::docker-b::duplicate-name',
+          action: 'update-applied',
+        },
       ]);
 
       const handler = getHandler('get', '/recent-status');
@@ -790,8 +829,13 @@ describe('Container Router', () => {
       expect(res.status).toHaveBeenCalledWith(200);
       expect(res.json).toHaveBeenCalledWith({
         statuses: {
+          'duplicate-name': 'failed',
           'trim-me': 'updated',
         },
+        statusesByIdentity: {
+          'edge-a::docker-a::duplicate-name': 'failed',
+          'edge-b::docker-b::duplicate-name': 'updated',
+        },
       });
     });
 
@@ -803,7 +847,7 @@ describe('Container Router', () => {
       handler({ query: {} }, res);
 
       expect(res.status).toHaveBeenCalledWith(200);
-      expect(res.json).toHaveBeenCalledWith({ statuses: {} });
+      expect(res.json).toHaveBeenCalledWith({ statuses: {}, statusesByIdentity: {} });
     });
   });
 

app/api/container.ts

@@ -50,6 +50,10 @@ const router = express.Router();
 const RECENT_STATUS_AUDIT_LIMIT = 100;
 
 type RecentContainerStatus = 'updated' | 'pending' | 'failed';
+type RecentContainerStatusResponse = {
+  statuses: Record<string, RecentContainerStatus>;
+  statusesByIdentity: Record<string, RecentContainerStatus>;
+};
 
 function mapAuditActionToRecentStatus(action: unknown): RecentContainerStatus | null {
   if (action === 'update-applied') return 'updated';
@@ -58,26 +62,44 @@ function mapAuditActionToRecentStatus(action: unknown): RecentContainerStatus |
   return null;
 }
 
-function buildRecentStatusByContainer(entries: unknown): Record<string, RecentContainerStatus> {
-  if (!Array.isArray(entries)) return {};
+function buildRecentStatusResponse(entries: unknown): RecentContainerStatusResponse {
+  if (!Array.isArray(entries)) {
+    return {
+      statuses: {},
+      statusesByIdentity: {},
+    };
+  }
+
   const statusByContainer: Record<string, RecentContainerStatus> = {};
+  const statusByIdentity: Record<string, RecentContainerStatus> = {};
   for (const entry of entries) {
     if (!entry || typeof entry !== 'object') continue;
-    const containerNameRaw = (entry as { containerName?: unknown }).containerName;
-    const containerName = typeof containerNameRaw === 'string' ? containerNameRaw.trim() : '';
-    if (!containerName || statusByContainer[containerName]) continue;
     const mappedStatus = mapAuditActionToRecentStatus((entry as { action?: unknown }).action);
     if (!mappedStatus) continue;
-    statusByContainer[containerName] = mappedStatus;
+
+    const containerNameRaw = (entry as { containerName?: unknown }).containerName;
+    const containerName = typeof containerNameRaw === 'string' ? containerNameRaw.trim() : '';
+    if (containerName && !statusByContainer[containerName]) {
+      statusByContainer[containerName] = mappedStatus;
+    }
+
+    const containerIdentityKeyRaw = (entry as { containerIdentityKey?: unknown })
+      .containerIdentityKey;
+    const containerIdentityKey =
+      typeof containerIdentityKeyRaw === 'string' ? containerIdentityKeyRaw.trim() : '';
+    if (containerIdentityKey && !statusByIdentity[containerIdentityKey]) {
+      statusByIdentity[containerIdentityKey] = mappedStatus;
+    }
   }
-  return statusByContainer;
+  return {
+    statuses: statusByContainer,
+    statusesByIdentity: statusByIdentity,
+  };
 }
 
 function getContainerRecentStatus(_req: Request, res: Response) {
   const recentEntries = auditStore.getRecentEntries(RECENT_STATUS_AUDIT_LIMIT);
-  res.status(200).json({
-    statuses: buildRecentStatusByContainer(recentEntries),
-  });
+  res.status(200).json(buildRecentStatusResponse(recentEntries));
 }
 
 /**

app/api/openapi/schemas.ts

@@ -322,8 +322,15 @@ export const openApiSchemas = {
           enum: ['updated', 'pending', 'failed'],
         },
       },
+      statusesByIdentity: {
+        type: 'object',
+        additionalProperties: {
+          type: 'string',
+          enum: ['updated', 'pending', 'failed'],
+        },
+      },
     },
-    required: ['statuses'],
+    required: ['statuses', 'statusesByIdentity'],
     additionalProperties: false,
   },
   WatchContainersRequest: {

app/model/audit.d.ts

@@ -28,6 +28,7 @@ export interface AuditEntry {
     | 'auth-login'
     | 'env-reveal';
   containerName: string;
+  containerIdentityKey?: string;
   containerImage?: string;
   fromVersion?: string;
   toVersion?: string;

app/model/container.ts

@@ -174,6 +174,8 @@ export interface Container {
   resultChanged?: (otherContainer: Container | undefined) => boolean;
 }
 
+export type ContainerIdentity = Partial<Pick<Container, 'agent' | 'watcher' | 'name'>>;
+
 export interface ContainerReport {
   container: Container;
   changed: boolean;
@@ -820,6 +822,24 @@ export function flatten(container: Container) {
   return containerFlatten;
 }
 
+export function getContainerIdentityKey(containerIdentity: ContainerIdentity) {
+  if (
+    !containerIdentity ||
+    typeof containerIdentity.watcher !== 'string' ||
+    containerIdentity.watcher.length === 0 ||
+    typeof containerIdentity.name !== 'string' ||
+    containerIdentity.name.length === 0
+  ) {
+    return undefined;
+  }
+
+  const agent =
+    typeof containerIdentity.agent === 'string' && containerIdentity.agent.length > 0
+      ? containerIdentity.agent
+      : '';
+  return `${agent}::${containerIdentity.watcher}::${containerIdentity.name}`;
+}
+
 /**
  * Build the business id of the container.
  * @param container

app/store/container.ts

@@ -31,6 +31,7 @@ const CONTAINER_COLLECTION_INDICES = ['data.watcher', 'data.status', 'data.updat
 const UNSAFE_QUERY_PATH_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
 const CONTAINER_QUERY_CONTROL_KEYS = new Set(['excludeRollbackContainers']);
 const STABLE_UNDEFINED_SENTINEL = '__undefined__';
+const toContainerFreshStateKey = container.getContainerIdentityKey;
 
 type SecurityStateCacheEntry = {
   security: unknown;
@@ -54,26 +55,6 @@ function toCacheKey(watcher, name) {
   return `${watcher}_${name}`;
 }
 
-function toContainerFreshStateKey(
-  containerIdentity: Partial<Pick<container.Container, 'agent' | 'watcher' | 'name'>>,
-) {
-  if (
-    !containerIdentity ||
-    typeof containerIdentity.watcher !== 'string' ||
-    containerIdentity.watcher.length === 0 ||
-    typeof containerIdentity.name !== 'string' ||
-    containerIdentity.name.length === 0
-  ) {
-    return undefined;
-  }
-
-  const agent =
-    typeof containerIdentity.agent === 'string' && containerIdentity.agent.length > 0
-      ? containerIdentity.agent
-      : '';
-  return `${agent}::${containerIdentity.watcher}::${containerIdentity.name}`;
-}
-
 export const SECURITY_STATE_CACHE_TTL_MS = toPositiveInteger(
   process.env.DD_SECURITY_STATE_CACHE_TTL_MS,
   DEFAULT_SECURITY_STATE_CACHE_TTL_MS,