# northpolesec/santa architecture

> Architecture diagram of the GitHub repository northpolesec/santa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/northpolesec/santa
- Repository: https://github.com/northpolesec/santa

## Overview

##### Project type and purpose
- This is a macOS security tool (“Santa”) that enforces binary and file-access authorization.
- It comprises multiple user-space components (daemon, GUI agent, CLI, background services) and a kernel/system extension (via EndpointSecurity API).

##### File structure
- Top-level components under `Source/`:
- common/ – shared libraries and utilities (XPC interfaces, Protobuf definitions, caching, configuration, logging, CEL engine).
- gui/ – Swift/Objective-C GUI agent that displays block messages.
- santactl/ – CLI front-end for management (uses XPC to talk to daemon).
- santad/ – long-running daemon: monitors events (EndpointSecurity), manages policy, database, decision cache, metrics, process tree.
- santasyncservice/ – background sync service: downloads/upload rules and events from/to a remote sync server.
- santabundleservice/ – XPC “bundle” service for privileged file-access decisions.
- santametricservice/ – background metrics-collection service.
- Conf/ holds launchd plists and install scripts.
- Fuzzing/ contains fuzz-targets.
- docs/ holds a React/Docusaurus site for user/developer documentation.

##### README for additional insights
- “system extension” monitors exec/file access → events go to daemon.
- user-space components validate each other via XPC and mutual code-sign check.
- Synchronization via “sync servers” (Workshop, Moroz, etc.).

##### Elements
- Blue for core daemon & extension
- Green for user-interaction (GUI/CLI)
- Yellow for background services (Metrics, Sync, Bundle)
- Gray for external stub
- Important interfaces: Protobuf messages, DataLayer, Policy rules, XPC endpoints.

##### Adding the sync service & external sync server stub
- Inside SyncService, note Zlib compression, APNS/FCM push clients, SNTPushClientAPNS, SNTPushClientFCM, Polaris integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Boundary"
        subgraph "Core Components"
            Extension["EndpointSecurity System Extension"]:::core
            Daemon["Santa Daemon (santad)"]:::core
            DB["Local Database (SQLite)"]:::core
            Cache["Decision Cache (In-Memory)"]:::core
            subgraph "Daemon Subsystems"
                Policy["PolicyProcessor"]:::core
                ExecCont["ExecutionController"]:::core
                DecisionCacheCode["SNTDecisionCache"]:::core
                DataLayer["DataLayer"]:::core
                ProcTree["ProcessTree"]:::core
            end
        end

        subgraph "User Interaction"
            GUI["GUI Agent"]:::ui
            CLI["CLI (santactl)"]:::ui
        end

        subgraph "Background Services"
            Bundle["Bundle Service"]:::svc
            Metric["Metric Service"]:::svc
            Sync["Sync Service"]:::svc
        end

        Common["Common Library"]:::common
    end

    External["External Sync Server"]:::external

    Extension -->|"Exec/File Event"| Daemon
    Daemon -->|"Decision Request"| Extension

    Daemon -->|"Query Rules"| DB
    Daemon -->|"Cache Lookup"| Cache

    Daemon -->|"Record Event"| DB
    Daemon -->|"Emit Metrics"| Metric
    Daemon -->|"Emit Events"| Sync

    GUI -->|"XPC Interface"| Daemon
    CLI -->|"XPC Interface"| Daemon

    Daemon -->|"XPC: privileged access"| Bundle

    Sync -->|"HTTPS/gRPC: pull rules\u002Fpush events"| External

    Daemon --> Policy
    Daemon --> ExecCont
    Daemon --> DecisionCacheCode
    Daemon --> DataLayer
    Daemon --> ProcTree

    click Common "https://github.com/northpolesec/santa/tree/main/Source/common/"
    click GUI "https://github.com/northpolesec/santa/tree/main/Source/gui/"
    click CLI "https://github.com/northpolesec/santa/tree/main/Source/santactl/"
    click Daemon "https://github.com/northpolesec/santa/blob/main/Source/santad/main.mm"
    click Policy "https://github.com/northpolesec/santa/blob/main/Source/santad/SNTPolicyProcessor.mm"
    click ExecCont "https://github.com/northpolesec/santa/blob/main/Source/santad/SNTExecutionController.mm"
    click DecisionCacheCode "https://github.com/northpolesec/santa/blob/main/Source/santad/SNTDecisionCache.mm"
    click DataLayer "https://github.com/northpolesec/santa/tree/main/Source/santad/DataLayer/"
    click ProcTree "https://github.com/northpolesec/santa/tree/main/Source/santad/ProcessTree/"
    click Extension "https://github.com/northpolesec/santa/tree/main/Source/santad/EventProviders/EndpointSecurity/"
    click Bundle "https://github.com/northpolesec/santa/tree/main/Source/santabundleservice/"
    click Metric "https://github.com/northpolesec/santa/tree/main/Source/santametricservice/"
    click Sync "https://github.com/northpolesec/santa/tree/main/Source/santasyncservice/"

    classDef core fill:#cce5ff,stroke:#005cbf,color:#005cbf;
    classDef ui fill:#d4edda,stroke:#155724,color:#155724;
    classDef svc fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef common fill:#e7f3fe,stroke:#2b7bb9,color:#2b7bb9;
```
