Loupe
Free trial
Documentation

Technical

Archetype taxonomy.

Every Loupe brief carries a top-level archetype classification — one of eleven closed-vocabulary cases anchored in three industry standards. The classification is constrained at the schema layer: the on-device model cannot emit any value outside this list.

Why a closed vocabulary

A 3B on-device model is reliable enough to classifyan incident if you give it a closed list, a disambiguation rule, and a clean schema constraint at the generation layer. It is not reliable enough to invent a taxonomy on the fly. Loupe enforces the list at the framework's schema layer (Apple FoundationModels DynamicGenerationSchema with .anyOf(...) clause). Hallucinated labels — "service_disruption", "data_corruption_event" — are structurally impossible to emit. The model literally cannot produce them.

The taxonomy is grounded in three named authorities so an auditor doesn't take Loupe's word for what belongs in the list:

  • NIST SP 800-61 Rev. 2 — Computer Security Incident Handling Guide. Source for the attack / unauthorized-access / availability-attack cases.
  • ITIL 4 Service Operation — Source for the hardware / network / software / capacity / external-dependency / procedural cases.
  • ENISA Reference Incident Classification Taxonomy — Cross-checks the attack and intrusion cases against European Union Agency for Cybersecurity guidance.

The eleven archetypes

Listed in disambiguation priority order. When two could apply, the model is prompted to pick the lower-index case. Cascade propagation wins over infrastructure failure when the failure clearly travels; software failure wins over capacity failure when the bug is distinct from an OOM kill.

  1. 1

    Cascade propagation

    cascade_propagation

    A failure that spreads across components or layers (e.g., DB slowness causing app upstream timeouts causing nginx 5xx burst). Picked first when a failure clearly travels.

    Cross-cutting (ITIL 4 incident-vs-problem distinction)

  2. 2

    Infrastructure failure

    infrastructure_failure

    Hardware, OS, or platform component fault (NIC failure, kernel I/O error, MCE, hypervisor issue). The OS or platform is the root, not the application.

    ITIL 4 Service Operation — Hardware / OS

  3. 3

    Network disruption

    network_disruption

    Connectivity, routing, or transport-layer failure (BGP flap, ICMP unreachable burst, duplicate IP, NIC link-flap). Distinct from network-attack scenarios.

    ITIL 4 Service Operation — Network

  4. 4

    Software failure

    software_failure

    Application or service crash, bug, or logic fault. The code is the root — not the platform underneath.

    ITIL 4 Service Operation — Software / Application

  5. 5

    Capacity or resource failure

    capacity_or_resource_failure

    Exhaustion of memory, disk, CPU, file descriptors, threads, or connection pools. The OS killed something for OOM, or the application starved itself out.

    ITIL 4 Service Operation — Capacity

  6. 6

    External dependency failure

    external_dependency_failure

    Upstream service, third-party API, or external data source failed. Loupe correctly attributes the symptom to a system outside the customer's control.

    ITIL 4 Service Operation — External / Service

  7. 7

    Procedural or change failure

    procedural_or_change_failure

    A deploy, config push, schema migration, or operator action caused the incident. Often correlated with a change-control window.

    ITIL 4 Service Operation — Procedural / Change

  8. 8

    External attack

    external_attack

    Adversarial activity from outside the trust boundary (path-scanning, exploit attempts, web shell uploads). MITRE ATT&CK technique IDs surface in the supporting evidence when available.

    NIST SP 800-61 Rev. 2 — Attrition / Web; ENISA — Intrusion attempts

  9. 9

    Unauthorized access

    unauthorized_access

    Successful or attempted access beyond a user's privileges (credential stuffing followed by a successful login, account takeover, privilege escalation).

    NIST SP 800-61 Rev. 2 — Improper Use; ENISA — Intrusions

  10. 10

    Availability attack

    availability_attack

    Denial of service, resource exhaustion attack, or other deliberate availability impact. Distinct from accidental capacity failures.

    NIST SP 800-61 Rev. 2 — Attrition (DoS); ENISA — Availability

  11. 11

    Unclassified

    unclassified

    Used when none of the above clearly fits or the evidence is insufficient. The honest-failure escape hatch — Loupe is allowed to refuse classification rather than miscategorize.

    — (escape hatch)

Subcategory companion field

Every brief also carries a subcategory — a short noun phrase (≤80 characters) naming the specific failure mode within the archetype. Examples: "memory exhaustion in container web01-app", "DNS resolution failure for upstream auth service", "credential stuffing from 185.220.101.42".

Subcategory is free-text and not consensus-checked across runs— the closed enum bears the determinism weight. Subcategory is the human-readable specificity that turns "capacity or resource failure" into something an operator can act on.

Reproducibility

The enum is defined in Sources/Loupe/Models/InvestigationThread.swift. Schema-layer constraint is built in Sources/Loupe/Services/Narrator/NarratorOutput.swift via DynamicGenerationSchema(.anyOf(Archetype.allCases.map(\.rawValue))). The taxonomy text shipped to the model lives in NarratorPrompt.swift (the Closed-vocabulary archetypes section of the prompt).