# google/santa architecture

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

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

## Overview

##### Main Components Overview

a) System Components:
- Santa System Extension (kernel level)
- Santa Daemon (santad)
- GUI Agent (Santa.app)
- Command-line Utility (santactl)
- Bundle Service (santabundleservice)
- Metric Service (santametricservice)
- Sync Service (santasyncservice)

b) External Components:
- Sync Server (optional)
- Database (local)
- Event Logging System

##### Component Relationships and Data Flow

Key relationships to show:

##### Architectural Layers

**User Interface Layer**
- Santa GUI
- santactl CLI

**Service Layer**
- Bundle Service
- Metric Service
- Sync Service

**Core Layer**
- Santa Daemon
- Rule Processing
- Decision Cache

**System Layer**
- System Extension
- File Monitor
- Process Monitor

**Storage Layer**
- Local Database
- Event Logs
- Cache

##### Security Components

Security features with distinct symbols:
- Certificate validation paths
- XPC communication channels
- Signature verification
- Cache validation

##### Decision Flow

**Execution Request → Cache Check → Rule Evaluation → Certificate Validation → Decision Making → Allow/Block Action**

##### Additional Elements

- Configuration options (MONITOR/LOCKDOWN modes)
- Rule types (Binary/Certificate/Path)
- Event logging paths
- Sync protocols

##### Notes Section

Annotations for:
- Failsafe mechanisms
- Performance optimizations
- Security boundaries
- System requirements

Remember to emphasize the defense-in-depth strategy and show how Santa fits into the larger macOS security ecosystem while clearly depicting its limitations and boundaries.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef ui fill:#FFE5CC,stroke:#FF9933
    classDef service fill:#CCE5FF,stroke:#3399FF
    classDef core fill:#E5CCFF,stroke:#9933FF
    classDef system fill:#CCFFCC,stroke:#33FF33
    classDef storage fill:#FFE5E5,stroke:#FF3333
    classDef external fill:#E5E5E5,stroke:#666666

    %% User Interface Layer
    subgraph UI
        GUI["Santa GUI Agent"]:::ui
        CLI["santactl CLI"]:::ui
    end

    %% Service Layer
    subgraph Services
        BS["Bundle Service"]:::service
        MS["Metric Service"]:::service
        SS["Sync Service"]:::service
    end

    %% Core Layer
    subgraph Core
        SD["Santa Daemon"]:::core
        RP["Rule Processing"]:::core
        DC["Decision Cache"]:::core
        PT["Process Tree"]:::core
    end

    %% System Layer
    subgraph System
        SE["System Extension"]:::system
        FM["File Monitor"]:::system
        PM["Process Monitor"]:::system
    end

    %% Storage Layer
    subgraph Storage
        DB[(Local Database)]:::storage
        EL["Event Logs"]:::storage
        Cache["Cache Storage"]:::storage
    end

    %% External Components
    SyncServer["Sync Server"]:::external

    %% Relationships
    SE --> SD
    FM --> SD
    PM --> SD
    SD <--> DB
    SD <--> EL
    SD <--> Cache
    GUI <--> SD
    CLI <--> SD
    BS <--> SD
    MS <--> SD
    SS <--> SD
    SS -.-> SyncServer
    SD <--> PT
    SD <--> RP
    SD <--> DC

    %% Click Events
    click SD "https://github.com/google/santa/tree/main/Source/santad/"
    click GUI "https://github.com/google/santa/blob/main/Source/gui/SNTAppDelegate.m"
    click CLI "https://github.com/google/santa/tree/main/Source/santactl/"
    click BS "https://github.com/google/santa/blob/main/Source/santabundleservice/SNTBundleService.m"
    click MS "https://github.com/google/santa/blob/main/Source/santametricservice/SNTMetricService.m"
    click SS "https://github.com/google/santa/blob/main/Source/santasyncservice/SNTSyncService.m"
    click PT "https://github.com/google/santa/tree/main/Source/santad/ProcessTree/"

    %% Legend
    subgraph Legend
        UI_L["User Interface"]:::ui
        SVC_L["Service"]:::service
        CORE_L["Core Component"]:::core
        SYS_L["System Component"]:::system
        STORE_L["Storage"]:::storage
        EXT_L["External"]:::external
    end
```
