Architecture Overview

18.1. Architecture Overview#

FlareInspect follows a layered architecture with clear separation between the CLI, core services, graph engine, integrations, the web dashboard, and (since v2.0) the MCP server. The resource graph is the single source of truth shared by the posture map UI, the SIEM exporters, the MCP server, and the notification dispatcher.

18.1.1. High-Level Architecture#

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   CLI Entry  │────▶│ AssessmentService│────▶│ CloudflareClient│
│  (index.js)  │     │                  │     │   (SDK + REST)  │
└──────┬───────┘     └────────┬─────────┘     └────────┬────────┘
       │                      │                         │
       │                      ▼                         │
       │             ┌──────────────────┐               │
       │             │ SecurityBaseline │◀──────────────┘
       │             │  (check defs +   │
       │             │   scoring)       │
       │             └────────┬─────────┘
       │                      │
       │                      ▼
       │             ┌──────────────────┐
       │             │  ReportService   │
       │             │  (report model)  │
       │             └────────┬─────────┘
       │                      │
       ▼                      ▼
┌─────────────┐     ┌──────────────────┐
│   Exporters  │     │  ComplianceEngine │
│ html/json/  │     │  contextualScoring│
│ sarif/csv/  │     │  diffService      │
│ md/asff/ocsf│     │  graph + paths    │ ◀── shared by posture map,
│ ecs/hec     │     └──────────────────┘     SIEM, MCP, notify
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│                Integrations layer (v2.0)                      │
│  src/core/integrations/siem/   → Elasticsearch / Splunk HEC  │
│  src/core/integrations/notify/ → Slack / Teams / webhooks    │
└──────┬──────────────────────────────────────────┬────────────┘
       │                                          │
       ▼                                          ▼
┌─────────────────────┐                ┌────────────────────┐
│  Web Dashboard (SPA) │ ◀── shared ──▶ │   MCP server       │
│  Express + static   │     graph      │   (stdio, ESM)     │
│  posture map page   │                │   6 tools          │
│  /api/posture/graph │                │   gated apply /    │
│  /api/notify        │                │   rollback         │
│  /api/integrations/*│                └────────────────────┘
└─────────────────────┘

18.1.2. Key Design Decisions#

  • CloudflareClient uses the official cloudflare v5 SDK with a rawRequest fallback for endpoints not covered by the SDK

  • SecurityBaseline is a pure data class — check definitions and scoring logic without API calls

  • AssessmentService orchestrates the full assessment flow with configurable concurrency via p-limit

  • Exporters are standalone classes that take an assessment object and produce format-specific output

  • Web server validates all inputs (UUID format, framework allowlist, concurrency cap, zone list size) before processing

  • Resource graph (src/core/graph/resourceGraph.js) is the single source of truth for the typed node/edge view of the account. Built once per assessment; consumed by attack-path detection, the posture map, the SIEM shippers (for flareinspect.node and threat.enrichments enrichment), and the MCP get_attack_paths tool

  • Edit-scope policy (src/core/auth/editScope.js) is shared verbatim by the MCP gated tools and the web /api/remediate/{apply,rollback} endpoints. One policy, two surfaces — the only way to add a new mutating entry point

  • SIEM shippers are pure functions over an assessment. The CLI, web API, and file exporters all call the same shipFindings and buildIndexTemplate functions — there is no second implementation

  • Notification channels are independent transport modules under src/core/integrations/notify/ (slack.js, teams.js, webhook.js) selected by the target flag in the CLI / the body of POST /api/notify

  • MCP server is a thin transport layer: it parses tool calls, calls the same engine modules the CLI uses, and returns the result. No business logic lives in mcp/server.mjs