Connect data sources with push ingest

Manual · API and availability · Adapters · Ingest reference

This chapter describes the push extension not yet released in v1.25.0. Before setup, check that your instance lists the integration endpoints in its OpenAPI specification.

Data flow and responsibilities

Source system inside the customer network
  → local adapter: read, map, persist batch
  → outbound HTTPS / TCP 443
  → ISMS Lite: validate, store evidence, evaluate deviations
  → management client: retrieve deviations and link measures

An externally hosted VPS does not need access to the customer network. Vendor credentials stay with the adapter. It requires read access to source systems and outbound HTTPS access to the ISMS instance with a valid certificate.

Responsible party Tasks
Adapter operator Vendor access, filters, complete retrieval including pagination, stable IDs, mapping, scheduling, local file permissions and monitoring
ISMS Lite Source binding, validation, repeatable acceptance, encrypted evidence, audit logging and rule-based deviations
Domain owners Asset owners, criticality, RPO, assessment, exceptions, measures and approvals

This channel does not perform network discovery, store continuous raw logs or operate backups or network devices. ISMS Lite does not replace inventory, monitoring, SIEM or backup software. Source query completeness and the actual usability of a reported restore point must be verified at the source.

1. Create two separate keys

Create these under Settings > API access:

Key Scopes
Adapter only ingest:write
Setup and management integrations:manage, integrations:read plus assets:read and assets:write for asset sources, or backup-jobs:read and backup-jobs:write for backup job sources

Do not put the management key in the recurring adapter task. integrations:read permits reading all integration metadata and evidence in the instance. The adapter-only key may deliver data only to its assigned sources; it has no general asset write access.

Retrieve the adapter key's ID using that key:

$env:ISMS_URL = 'https://isms.example.org'
# ISMS_API_KEY contains the adapter key loaded from the secret store.
$adapterHeaders = @{ Authorization = "Bearer $env:ISMS_API_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/integrations/identity" -Headers $adapterHeaders

Use the returned apiKeyId for setup. sources is empty before the first assignment; afterwards it lists assigned sources with id, revision, enabled, coverage and objectKind.

2. Create a source

Send POST /api/v1/integrations/sources with the management key. Replace the UUID placeholders below; all shown fields belong to the configuration.

{
  "name": "Site A - inventory export",
  "apiKeyId": "UUID-OF-ADAPTER-KEY",
  "enabled": true,
  "objectKind": "asset",
  "coverage": "site-a-managed-assets",
  "expectedIntervalHours": 24,
  "missingGraceHours": 72,
  "createAssets": {
    "ownerId": "UUID-OF-ACTIVE-OWNER",
    "criticality": 3,
    "assetType": "server",
    "managedFields": ["name", "location", "ip_address", "os_platform"]
  },
  "rules": {
    "rpo": false,
    "restore": false,
    "backupFailures": null,
    "sourceStale": true
  }
}

For example, save this as source.json and send:

# ISMS_MANAGEMENT_KEY comes from the protected management environment.
$managementHeaders = @{ Authorization = "Bearer $env:ISMS_MANAGEMENT_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/integrations/sources" `
    -Method Post -Headers $managementHeaders -ContentType 'application/json' -InFile source.json

The response contains the source id and configuration revision. Retain both for the adapter.

  • coverage identifies a consistently bounded inventory, such as one site. Filter changes affecting that boundary require a new source.
  • expectedIntervalHours defines expected freshness. Schedule the actual task separately.
  • missingGraceHours is the grace period before marking an object as no longer seen after a complete snapshot.
  • createAssets permits creation with an explicitly chosen owner, asset type and criticality. Obtain the domain decision first; null disables creation.
  • For backup jobs, use objectKind: "backup_job" and createAssets: null. Create jobs first in the domain module or its API.
  • rules enables RPO, restore and freshness checks. backupFailures is a consecutive failure threshold from 1 to 20, or null to disable. See the reference for evaluation rules.

3. Bind existing records

With the management key, call POST /api/v1/integrations/sources/{id}/bindings:

{
  "externalId": "STABLE-SOURCE-SYSTEM-ID",
  "targetId": "UUID-IN-ISMS-LITE",
  "managedFields": ["name", "location", "ip_address", "os_platform"]
}

Use managedFields: [] for backup jobs or evidence-only sources. Existing objects are identified through this explicit binding, not hostname, IP or MAC address. The source/external-ID combination stays stable and cannot later be reassigned to another target.

Multiple sources may reference the same asset. Only one source may own each technical field. Ingest manages only name, location, ip_address and os_platform. It does not continually overwrite owner, criticality, RPO, risks or approvals from source data.

If a managed field has been changed manually, the entire batch fails with 409 and details.reason: "manualFieldConflict". After review, either remove the field from managedFields or deliberately adopt the current baseline by rebinding to the same target ID. More frequent retries do not resolve the conflict.

4. Deliver data and verify results

The adapter chapter covers asset export and the Veeam example. Custom adapters send JSON to POST /api/v1/integrations/sources/{id}/batches; the ingest reference describes the contract.

After the first delivery, use the management key to check:

  1. GET .../sources/{id}: Is last_observed_at current and is coverage correct?
  2. GET .../sources/{id}/bindings: Are external_id, target_id and field ownership correct?
  3. GET .../sources/{id}/observations: Were expected observations received? An asset-only export can contain no observations.
  4. GET .../sources/{id}/observations/{childId}: Are evidence content and validity correct?
  5. GET .../sources/{id}/deviations: Are there domain deviations or unknown states?

Here, ... means /api/v1/integrations. Read all list pages using offset and limit. Sources, integration evidence and deviations are managed through this API; no separate integration user interface is included.

Complete snapshot or change delivery

A delta batch reports only the objects it contains. Omission has no meaning. A full batch must contain the entire agreed coverage in one successful request. Only then can previously known, now missing objects become no longer seen after the grace period. This neither deletes nor decommissions assets.

Before sending full, retrieve all vendor pages and verify completeness. Do not send an apparently complete empty inventory after a source error. A genuinely empty complete inventory is valid. For larger inventories, use permanently separate source partitions or delta deliveries; request limits are in the reference.

Operations, configuration changes and key rotation

Schedule the local task according to expected freshness, for example with Windows Task Scheduler. Prevent overlapping runs, synchronise clocks and monitor failures and missing collections. A receipt confirms acceptance, not domain compliance.

Update sources using PUT /api/v1/integrations/sources/{id}:

{ "revision": 1, "source": { "...": "complete source configuration" } }

This abbreviated example shows only the envelope. source must contain the full configuration from step 2. Every change increments the revision. New batches must use it. objectKind and coverage are immutable; create a new source to change them. enabled: false stops acceptance and periodic evaluation without deleting history.

To rotate a key, create a new adapter key, retrieve its ID through /identity, update the source with that apiKeyId, and configure the task with the new revision and key. Then revoke the old key. Handle pending batches deliberately during the transition; never alter an already accepted batch under its existing ID.

Deleted domain records remain traceable through their original target ID. Further imports of that identity receive 409 targetDeleted and do not recreate the record. An intentional new identity needs a new source binding. Evidence and decision histories are not automatically deleted; account for retention in operational planning.