@x12i/memorix-retrieval 1.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @x12i/memorix-retrieval
+
+Descriptor-driven retrieval/composition layer for Memorix entity and event data.
+
+## Positioning
+
+| Package | Role |
+|---------|------|
+| `@x12i/memorix` | Low-level entity collection I/O, discovery, raw document access |
+| `@x12i/memorix-retrieval` | Descriptor-driven lists, items, relations, and content-object reads |
+
+**Catalox** defines what to fetch. This package reads Mongo and composes API-ready JSON. **@x12i/helpers** fetches external content objects when needed.
+
+## Quick start
+
+Set `MONGO_URI` and provide a Catalox client. Database names, entity vs event routing, and collection resolution are handled internally.
+
+```bash
+MONGO_URI=mongodb://localhost:27017
+```
+
+```typescript
+import {
+  createMemorixRetrievalFromEnv,
+  fetchMemorixList,
+  fetchMemorixItem,
+} from "@x12i/memorix-retrieval";
+
+const client = await createMemorixRetrievalFromEnv({ catalox });
+
+const list = await fetchMemorixList(client, {
+  listId: "assets-main-list",
+  page: { limit: 50, offset: 0 },
+});
+
+const item = await fetchMemorixItem(client, {
+  itemDescriptorId: "asset-detail-item",
+  entityId: "10.150.68.31",
+});
+
+await client.close?.();
+```
+
+Lazy connect (same env, no upfront `await`):
+
+```typescript
+import { createMemorixRetrieval, fetchMemorixList } from "@x12i/memorix-retrieval";
+
+const client = createMemorixRetrieval({ catalox });
+// connects to Mongo on first read using MONGO_URI
+```
+
+Optional content storage (credentials are never read from descriptors):
+
+```typescript
+import { createGcsClient } from "@x12i/helpers/gcs";
+
+const client = await createMemorixRetrievalFromEnv({
+  catalox,
+  contentReaders: { gcs: createGcsClient({ bucket: "memorix-content" }) },
+});
+```
+
+## Advanced (optional)
+
+Override defaults only when you need to:
+
+| Option | Purpose |
+|--------|---------|
+| `MEMORIX_ENTITIES_DB` / `MEMORIX_EVENTS_DB` | Non-default database names |
+| `MEMORIX_ENTITIES_COLLECTION_*` / `MEMORIX_EVENTS_COLLECTION_*` | Per-type collection overrides |
+| `memorixDb` | Code overrides for entity/event DB names |
+| `xronox` | Inject a pre-configured Xronox client instead of built-in Mongo reads |
+| `mongo` | Reuse an existing `MongoClient` |
+| `processEnv` | Custom env object (default: `process.env`) |
+
+Entity descriptors declare `target: "entity" | "event"` (default `entity`):
+
+| Descriptor | Database |
+|------------|----------|
+| `assets`, `variabilities-groups` | `memorix-entities` |
+| `vulnerabilities` | `memorix-events` |
+
+See [docs/MEMORIX-DATABASE-CONVENTIONS.md](docs/MEMORIX-DATABASE-CONVENTIONS.md).
+
+## Catalox seeds
+
+Source of truth: `catalox-seeds/inputs/`
+
+```bash
+npm run catalox:seed:memorix-retrieval:validate
+npm run catalox:seed:memorix-retrieval:apply
+```
+
+Every seeded item shares scope from `catalox-seeds/inputs/scope.json`:
+
+```json
+{
+  "scope": {
+    "domains": ["network", "vulnerabilities"],
+    "agents": ["neo"]
+  }
+}
+```
+
+```bash
+npm run mongo:check-collections
+npm run smoke:retrieval -- --list assets-main-list --limit 5
+```
+
+## Build & test
+
+```bash
+npm run build
+npm test
+```
+
+## Publish
+
+From the x12i workspace root:
+
+```bash
+./scripts/publish-memorix-packages.sh
+```

package/catalox-seeds/inputs/entity-descriptors/assets.json

@@ -0,0 +1,296 @@
+{
+  "id": "assets",
+  "entityName": "assets",
+  "target": "entity",
+  "collectionPrefix": "assets",
+  "identity": {
+    "allowedIdFields": [
+      "entityId",
+      "eventId"
+    ],
+    "requiredExactlyOne": true,
+    "defaultIdField": "entityId"
+  },
+  "defaults": {
+    "canonicalContentType": "snapshots",
+    "dataRoot": "data",
+    "effectiveDatePath": "capturedAt",
+    "fallbackEffectiveDatePaths": [
+      "snapshot.capturedAt",
+      "data.xdr.last_seen"
+    ]
+  },
+  "contentTypes": {
+    "snapshots": {
+      "postfix": "snapshots",
+      "collection": "assets-snapshots",
+      "dataRoot": "data",
+      "isCanonical": true,
+      "effectiveDatePath": "capturedAt",
+      "fallbackEffectiveDatePaths": [
+        "snapshot.capturedAt",
+        "data.xdr.last_seen"
+      ]
+    }
+  },
+  "properties": {
+    "ipAddress": {
+      "label": "IP Address",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.ip_address"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "source": {
+      "label": "Source",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data._source"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "hostName": {
+      "label": "Host Name",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.host_name"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "xdrOperationalStatus": {
+      "label": "XDR Operational Status",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.operational_status"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "xdrAgentStatus": {
+      "label": "XDR Agent Status",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.agent_status"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "agentType": {
+      "label": "Agent Type",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.agent_type"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "lastSeen": {
+      "label": "Last Seen",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.last_seen"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "datetime"
+    },
+    "users": {
+      "label": "Users",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr.users"
+      },
+      "humanReadable": true,
+      "sortable": false,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "array"
+    },
+    "hasVulnerabilities": {
+      "label": "Has Vulnerabilities",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.vulnerabilities.hasVulnerabilities"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "boolean"
+    },
+    "criticalVulnerabilities": {
+      "label": "Critical Vulnerabilities",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.vulnerabilities.count.critical"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "highVulnerabilities": {
+      "label": "High Vulnerabilities",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.vulnerabilities.count.high"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "mediumVulnerabilities": {
+      "label": "Medium Vulnerabilities",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.vulnerabilities.count.medium"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "lowVulnerabilities": {
+      "label": "Low Vulnerabilities",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.vulnerabilities.count.low"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "potentialImpactLevel": {
+      "label": "Potential Impact",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.potentialImpact.level"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "string"
+    },
+    "potentialImpactConfidence": {
+      "label": "Impact Confidence",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.potentialImpact.confidence"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "potentialImpactStory": {
+      "label": "Potential Impact Story",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.potentialImpact.story"
+      },
+      "humanReadable": false,
+      "sortable": false,
+      "filterable": false,
+      "list": false,
+      "item": true,
+      "valueType": "array"
+    },
+    "pathsCount": {
+      "label": "Paths Count",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.pathsCount"
+      },
+      "humanReadable": true,
+      "sortable": true,
+      "filterable": true,
+      "list": true,
+      "item": true,
+      "valueType": "number"
+    },
+    "rawXdr": {
+      "label": "Raw XDR",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.xdr"
+      },
+      "humanReadable": false,
+      "sortable": false,
+      "filterable": false,
+      "list": false,
+      "item": true,
+      "valueType": "object"
+    }
+  },
+  "relations": {
+    "assetVulnerabilities": {
+      "targetEntity": "vulnerabilities",
+      "type": "oneToMany",
+      "source": {
+        "contentType": "snapshots",
+        "path": "data.ip_address"
+      },
+      "target": {
+        "contentType": "snapshots",
+        "path": "data.assetIp"
+      },
+      "defaultMode": "array",
+      "defaultArrayProperty": "vulnerabilities",
+      "targetFields": [
+        "vulnerabilityId",
+        "pluginName",
+        "severityLevel",
+        "riskLevel",
+        "priorityScore",
+        "cveIds"
+      ]
+    }
+  }
+}