# jamf/aftermath architecture

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

- Interactive diagram: https://gitdiagram.com/jamf/aftermath
- Repository: https://github.com/jamf/aftermath

## Overview

##### Main components
- Main Application Core – Represented by the “aftermath” directory containing main.swift and other key files. This is the entry point for execution.
- Collection Modules – There are several domain-specific modules:
- Analysis (analysis folder): Parsing logs, databases, timeline generation, and storyline creation.
- Artifacts (artifacts folder): Collecting configuration profiles, log files, quarantine data, etc.
- Filesystem (filesystem folder): Walking common directories, gathering file metadata, including specialized browsers submodules.
- Network (network folder): Capturing active network connections and related preferences.
- Persistence (persistence folder): Monitoring items such as cron jobs, login items, launch agents/daemons, system extensions.
- Processes (processes folder): Using support from TrueTree, process tree generation and network-related process information.
- Endpoint Security (endpointSecurity folder): Collecting ES logs and relevant security events.
- System Recon (systemRecon folder): Environment details, installed applications, system configuration and status.
- Unified Logs (unifiedlogs folder): Handling unified logging modules.
- Extension Utilities – Found in the “extensions” directory, which offer helper methods for core data types (FileManager, String, URL).
- Helper Components – Found in “helpers” as common code pieces.
- Library Integrations – Under “libs”, third-party or additional platform-specific libraries (e.g., ProcLib, launchdXPC) are integrated.
- Optional Analysis Phase – Via the “--analyze” flag when running the tool, the system processes previously collected data archives.

##### Out the relationships and interactions
- The Main Application (aftermath/main.swift) acts as the central orchestrator that kicks off one or more collection modules based on options passed from the command line.
- Each module (for artifacts, filesystem, network, etc.) is responsible for a distinct aspect of data collection. They can be visualized as independent but interacting blocks that feed data into a common output (written to /tmp or a user-specified output directory).
- The Analysis module works separately to ingest and process a zip/archive produced by the collection phase, resulting in parsed data, timelines, and storylines.
- Some modules (e.g., endpointSecurity and processes) may use additional libraries or threads (referencing “eslogger”, “tcpdump”, and TrueTree) to handle asynchronous data collection.

##### Architectural patterns and design principles
- Modular Architecture – Each domain (artifacts, filesystem, network, etc.) is clearly separated into its own directory and module, facilitating focused maintenance and future extension.
- Command-Line Interface (CLI) Design – The use of flags (e.g., --analyze, --deep, --disable) implies a design that can flexibly control behavior at runtime.
- Separation of Concerns – Distinct modules for collection vs. analysis and granular sub-modules (e.g., file browsers under filesystem/browsers) indicate good separation of responsibilities.
- Extensibility – With explicit handling for additional unified log predicates and disabling certain features through CLI arguments, the system is designed with extensibility in mind.

##### Relevant technologies and frameworks
- Swift and Xcode – The project is built with Xcode and written in Swift.
- macOS APIs – Since Aftermath requires full disk access and system-level privileges (e.g., accessing logs, network connections, process details), it directly leverages macOS system services.
- External logs and shell commands – Modules that interact with logs (e.g., Endpoint Security) or utilize shell utilities may invoke external processes whose lifecycles are controlled by the main application.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Main Application Core"]:::core

    subgraph "Collection Modules"
        B["Artifacts Module"]:::module
        C["Filesystem Module"]:::module
        D["Network Module"]:::module
        E["Persistence Module"]:::module
        F["Processes Module"]:::module
        G["Endpoint Security Module"]:::module
        H["System Recon Module"]:::module
        I["Unified Logs Module"]:::module
    end

    J["Output/Artifact Repository"]:::output
    K["Analysis Module"]:::analysis
    L["Parsed Results (Timeline,Narrative)"]:::analysis

    subgraph "Support Components"
        M["Extension Utilities"]:::support
        N["Helper Components"]:::support
        O["Library Integrations"]:::support
    end

    subgraph "External Dependencies"
        P["macOS APIs"]:::external
        Q["TrueTree"]:::external
        R["Shell Utilities"]:::external
    end

    %% Main Core invokes Collection Modules
    A -->|"invokes"| B
    A -->|"invokes"| C
    A -->|"invokes"| D
    A -->|"invokes"| E
    A -->|"invokes"| F
    A -->|"invokes"| G
    A -->|"invokes"| H
    A -->|"invokes"| I

    %% Collection Modules output to central repository
    B -->|"outputs"| J
    C -->|"outputs"| J
    D -->|"outputs"| J
    E -->|"outputs"| J
    F -->|"outputs"| J
    G -->|"outputs"| J
    H -->|"outputs"| J
    I -->|"outputs"| J

    %% Analysis Phase consumes the output repository
    J -->|"analyzed_by"| K
    K -->|"produces"| L

    %% Optional analysis via CLI flag
    A -->|"--analyze"| K

    %% Support Dependencies (dashed connections)
    B -.-> M
    C -.-> M
    D -.-> M
    E -.-> M
    F -.-> O
    G -.-> O
    H -.-> N
    I -.-> M

    %% External Dependencies Connections
    C -.-> P
    D -.-> P
    G -.-> P
    F -.-> Q
    G -.-> Q
    D -.-> R
    F -.-> R

    %% Click Events
    click A "https://github.com/jamf/aftermath/blob/main/aftermath/main.swift"
    click K "https://github.com/jamf/aftermath/blob/main/analysis/AnalysisModule.swift"
    click B "https://github.com/jamf/aftermath/blob/main/artifacts/ArtifactsModule.swift"
    click C "https://github.com/jamf/aftermath/blob/main/filesystem/FileSystemModule.swift"
    click D "https://github.com/jamf/aftermath/blob/main/network/NetworkModule.swift"
    click E "https://github.com/jamf/aftermath/blob/main/persistence/PersistenceModule.swift"
    click F "https://github.com/jamf/aftermath/blob/main/processes/ProcessModule.swift"
    click G "https://github.com/jamf/aftermath/blob/main/endpointSecurity/ESModule.swift"
    click H "https://github.com/jamf/aftermath/blob/main/systemRecon/SystemReconModule.swift"
    click I "https://github.com/jamf/aftermath/blob/main/unifiedlogs/UnifiedLogModule.swift"
    click M "https://github.com/jamf/aftermath/tree/main/extensions"
    click N "https://github.com/jamf/aftermath/blob/main/helpers/CHelpers.swift"
    click O "https://github.com/jamf/aftermath/tree/main/libs"

    %% Style Definitions
    classDef core fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef output fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef analysis fill:#e0ccff,stroke:#6600cc,stroke-width:2px;
    classDef support fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef external fill:#ffebcc,stroke:#cc6600,stroke-width:2px;

    class A core;
    class B,C,D,E,F,G,H,I module;
    class J output;
    class K,L analysis;
    class M,N,O support;
    class P,Q,R external;
```
