generated: '2026-08-04'
method: derived
source: >-
  openapi/malwarebytes-threatdown-nebula-openapi.json,
  openapi/malwarebytes-threatdown-oneview-openapi.json — entity graph derived from
  response-schema id-reference fields and path hierarchy
summary: >-
  The ThreatDown data model is an endpoint-security estate graph rooted at the Account
  (a tenant, called a Site in OneView). Everything hangs off the Endpoint (machine):
  its Detections, Scans, Quarantine items, Assets, Suspicious Activity and CVEs.
  Configuration is applied through Group → Policy. Actions are expressed as Jobs, which
  fan out from a Parent Job by correlation_id. Identifiers are UUIDs throughout; there
  are no typed id prefixes.
identifier_convention:
  format: UUID v4
  pattern: '[\da-fA-F]{8}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{4}-?[\da-fA-F]{12}$'
  typed_prefixes: false
  note: >-
    Identifiers are bare UUIDs with no resource discriminator, so an id alone does not
    reveal what it addresses — a reader must know the field name. `machine_id` is the
    endpoint identifier throughout, including inside detection and job payloads.
  validated_at_edge: true
entities:
- name: Account
  aka: [Site (OneView), Tenant]
  description: >-
    The tenancy boundary. Addressed by the `accountid` header on Nebula and by the
    `account_id` path parameter on OneView. Every other entity is scoped to one account.
  id_field: account_id
  operations: [api.oneview.get.all.customers, api.nebula.get.groups]
  api: both
- name: Site
  description: >-
    OneView's MSP-managed customer. A Site carries an account_id once a Subscription is
    attached, and that account_id is then used for all endpoint-security operations.
  id_field: id
  parent: parent_account_id
  api: oneview
- name: Subscription
  description: >-
    The commercial entitlement attached to a Site. All per-site subscription operations
    are marked deprecated in the current definition.
  id_field: entitlement_id
  api: oneview
  deprecated: true
  see_also: lifecycle/malwarebytes-lifecycle.yml
- name: Endpoint
  aka: [Machine]
  description: >-
    A protected device running the ThreatDown Endpoint Agent. The central entity of the
    model, carrying agent state, OS info, NICs, protection status and last user.
  id_field: machine_id
  path: /nebula/v1/endpoints/{id}
  operations:
  - api.v2.nebula.post.endpoints
  - api.v2.nebula.get.endpoint.id
  - api.v2.nebula.delete.endpoint
  - api.v2.nebula.get.endpoint.id.agent_info
  - api.v2.nebula.put.endpoint.id.tags
  api: both
- name: Group
  description: A container of endpoints; the unit that a Policy is applied through.
  id_field: group_id
  path: /nebula/v1/groups/{id}
  operations: [api.nebula.get.groups, api.nebula.post.groups, api.v2.nebula.post.groups.bulk]
  hierarchical: true
  root_field: root_group_id
- name: Policy
  description: >-
    Protection configuration — scan settings, isolation behaviour, tamper protection
    password, isolation image. Clonable and promotable.
  id_field: policy_id
  path: /nebula/v1/policies/{id}
  operations: [api.nebula.get.policy, api.nebula.post.policy, api.nebula.post.policy.clone, api.nebula.put.policy.promote]
- name: Detection
  description: >-
    A malware, ransomware, exploit or PUP finding reported by the agent — carries
    threat_name, category, path, action_taken, MD5, process_name and timestamps.
  id_field: detection_id
  path: /nebula/v1/detections/{id}
  operations: [api.v2.nebula.search.detections, api.v2.nebula.get.detections.id, api.v2.nebula.detections.submit.fp]
- name: Scan
  description: A scan run on an endpoint; the container the detections of that run belong to.
  id_field: scan_id
  path: /nebula/v1/endpoints/{id}/scans/{scan_id}
  operations: [api.nebula.get.endpoint.id.scans, api.nebula.get.endpoint.id.scans.id.detections]
- name: Job
  description: >-
    A commanded action against an endpoint — Scan, Isolate, Remediate, Reboot. Status
    moves through PENDING, STARTED, TIMED_OUT, COMPLETED and is reported by the
    job_status_change webhook.
  id_field: job_id
  path: /nebula/v1/jobs/{id}
  operations: [api.v2.nebula.post.jobs, api.v2.nebula.post.jobs.bulk, api.v2.nebula.get.jobs.id, api.v2.nebula.search.jobs]
  requires_scope: execute
- name: ParentJob
  description: >-
    The fan-out container for a bulk job issuance. Children are addressed through the
    parent's correlation_id and can be searched, summarised, cancelled or reissued.
  id_field: correlation_id
  path: /nebula/v1/parent_jobs/{correlation_id}
  operations: [api.v2.nebula.post.parent_jobs, api.v2.nebula.post.parent_jobs.children, api.v2.nebula.reissue.parent_jobs]
- name: QuarantineItem
  description: A file isolated on an endpoint, restorable or deletable in bulk.
  path: /nebula/v1/quarantine
  operations: [api.nebula.get.quarantine-all, api.nebula.post.quarantine-action, api.nebula.post.quarantine-search]
- name: SuspiciousActivity
  description: >-
    An EDR behavioural finding on an endpoint, openable, closable, remediable and
    excludable.
  id_field: sa_id
  path: /nebula/v1/endpoints/{id}/sa/{sa_id}
  operations: [api.nebula.endpoint.id.sa, api.nebula.endpoint.id.sa.sa_id.remediate]
- name: CVE
  aka: [Vulnerability]
  description: A known vulnerability observed in the software inventory of the estate.
  path: /nebula/v1/cve/{id}
  operations: [api.nebula.search.cve, api.nebula.get.cve.id, api.nebula.ignore.cve, api.nebula.get.cves.bulk]
- name: Asset
  description: Software and hardware inventory collected from an endpoint.
  path: /nebula/v1/endpoints/{id}/assets
  operations: [api.v2.nebula.get.endpoint.id.assets]
- name: Drive
  description: An encryptable volume on an endpoint; its recovery key can be revealed.
  id_field: volume_id
  path: /nebula/v1/endpoints/{id}/drives
  operations: [api.nebula.get.endpoint.id.drives, api.nebula.post.endpoint.id.drives.volume_id.reveal]
  sensitivity: high
- name: Exclusion
  description: A suppression rule that stops a path, file, or behaviour being acted on.
  id_field: id
- name: IgnoreRule
  description: A rule suppressing specific CVE or activity findings.
  id_field: ignore_rule_ids
- name: Report
  description: A generated report definition, owned by a user and generatable on demand.
  id_field: id
  path: /nebula/v1/reports/{id}
  operations: [api.nebula.getall.reports, api.nebula.post.reports, api.nebula.post.reports.generate, api.nebula.put.reports.change_owner]
- name: Schedule
  description: A recurring task definition (scans, reports, patch windows).
  id_field: schedule_id
- name: User
  description: A console user; the identity whose granular permissions gate every API call.
  id_field: user_id
- name: WebhookSubscription
  description: A registered event handler URL with a secret_token and max_retries.
  id_field: subscription_id
  see_also: asyncapi/malwarebytes-threatdown-webhooks.yml
relationships:
- from: Account
  to: Endpoint
  type: has_many
  via: account_id
- from: Account
  to: Group
  type: has_many
  via: account_id
- from: Site
  to: Account
  type: has_one
  via: account_id
  note: OneView attaches an account_id to a Site once a Subscription is assigned.
- from: Site
  to: Site
  type: belongs_to
  via: parent_account_id
  note: MSP hierarchy
- from: Site
  to: Subscription
  type: has_many
  via: entitlement_id
- from: Group
  to: Endpoint
  type: has_many
  via: group_id
- from: Group
  to: Group
  type: belongs_to
  via: root_group_id
- from: Endpoint
  to: Group
  type: belongs_to
  via: group_id
- from: Endpoint
  to: Policy
  type: belongs_to
  via: policy_id
- from: Group
  to: Policy
  type: belongs_to
  via: policy_id
- from: Endpoint
  to: Detection
  type: has_many
  via: machine_id
- from: Endpoint
  to: Scan
  type: has_many
  via: machine_id
- from: Scan
  to: Detection
  type: has_many
  via: scan_id
- from: Detection
  to: Endpoint
  type: belongs_to
  via: machine_id
- from: Detection
  to: QuarantineItem
  type: has_many
  via: detection_id
- from: Endpoint
  to: SuspiciousActivity
  type: has_many
  via: machine_id
- from: Endpoint
  to: Asset
  type: has_many
  via: machine_id
- from: Endpoint
  to: Drive
  type: has_many
  via: machine_id
- from: Endpoint
  to: CVE
  type: has_many
  via: machine_id
  note: through the software inventory
- from: Endpoint
  to: Job
  type: has_many
  via: machine_id
- from: ParentJob
  to: Job
  type: has_many
  via: correlation_id
- from: Job
  to: Endpoint
  type: belongs_to
  via: machine_id
- from: WebhookSubscription
  to: Account
  type: belongs_to
  via: account_id
- from: Report
  to: User
  type: belongs_to
  via: user_id
- from: Schedule
  to: Group
  type: has_many
  via: schedule_ids
id_field_frequency:
  note: occurrences of each id-reference field across all response schemas in the Nebula definition
  account_id: 122
  machine_id: 57
  policy_id: 49
  group_id: 32
  parent_account_id: 18
  detection_id: 14
  scan_id: 14
  root_group_id: 12
  job_id: 12
  schedule_ids: 12
  user_id: 11
  correlation_id: 10
  device_id: 9
  group_ids: 9
  rule_id: 6
  entitlement_id: 5
  incident_id: 4
schema_note: >-
  components.schemas is EMPTY in both definitions — every schema is inlined at the
  operation, which is why the definitions are 17.8 MB and 19.6 MB. There is zero schema
  reuse for a tooling consumer to bind to: the Endpoint object is re-declared in full at
  each operation that returns it, and `additionalProperties: true` is common, so the
  entity graph above is reconstructed from field names rather than read from $refs.