# fics/bigmac architecture

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

- Interactive diagram: https://gitdiagram.com/fics/bigmac
- Repository: https://github.com/fics/bigmac

## Overview

##### Project Type and Purpose
- BigMAC is a Python‐based command‐line tool for extracting, processing, and querying Android DAC/MAC/CAP security policies from firmware images.
- It is neither a web/full‐stack app nor a microservice suite; it is a standalone data‐processing and analysis framework with an interactive Prolog query interface.

##### Key Architectural Layers and Components
a. Ingestion & Extraction
- CLI Frontend (process.py) – parses arguments, coordinates workflow.
- Firmware Extractors (tools/android-extract.sh, extract.py, overlay.py) – pull filesystem and policy blobs from firmware.
- eval/ and tools/ modules – evaluation harness and helper scripts for bulk processing.
b. Policy Parsing & Processing
- Android Policy Config Parsers (android/ directory: file_contexts.py, initrc.py, sepolicy.py, etc.) – wrappers around libsepol and setools interacting with patched C libraries.
- security_policy.py and config.py – high-level orchestration of parsing, layering DAC/MAC/CAP.
c. Graph & Logic Layer
- segraph.py / stats.py / sedump.py – construct internal graph representation of subjects, objects, rules.
- Prolog Integration (prolog.py, graph2prolog.py, logic/ directory) – emit facts, load SWI-Prolog environment, serve interactive queries.
- logic/main*.pl – Prolog rules for querying extracted policies.
d. Persistence & Reporting
- Saved policy databases (db/ under each vendor directory) – SQLite or serialized Python objects.
- facts/*.pl and stats/*.txt – Prolog facts and statistical summaries.
- Evaluation outputs in eval/ – ground truth, CVE analysis, comparison scripts.

##### Relationships and Data Flows
- The user invokes the CLI (process.py).
- Extraction modules unpack firmware → file trees & raw policy files.
- Parser modules (android/*.py + libsepol/setools) process raw policy into in-memory structures.
- Graph builders convert structures into a property graph (segraph.py).
- Persistence layer serializes the graph to disk (db/), optionally dumps Prolog facts.
- Prolog interface loads facts, provides REPL for interactive queries.
- Evaluation scripts in eval/ ingest saved graphs or raw data, compare policies, generate reports.

##### Architectural Patterns & Principles
- Pipeline/Layered Architecture: clear separation of extraction → parsing → graph building → query.
- Plugin-like Parsers: android/*.py can be extended to support new policy sources.
- Data-flow Orientation: each step produces artifacts consumed by the next.
- External Tool Integration: libsepol and setools are patched and invoked as native libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion & Extraction
    subgraph "1. Ingestion & Extraction"
        CLI["CLI: process.py"]:::module
        EX1["extract.py"]:::module
        OL["overlay.py"]:::module
        AE["tools/android-extract.sh"]:::script
    end

    %% Policy Parsing & Processing
    subgraph "2. Policy Parsing & Processing"
        FC["android/file_contexts.py"]:::module
        IR["android/initrc.py"]:::module
        SP["android/sepolicy.py"]:::module
        CAP["android/capabilities.py"]:::module
        DAC["android/dac.py"]:::module
        PROP["android/property.py"]:::module
        AFSC["android/android_filesystem_config.h"]:::module
        AFSH["android/android_fs.h"]:::module
        SecPolicy["security_policy.py"]:::module
        Config["config.py"]:::module
    end

    %% Graph & Logic Layer
    subgraph "3. Graph & Logic Layer"
        SG["segraph.py"]:::module
        STATS["stats.py"]:::module
        SDUMP["sedump.py"]:::module
        PR["prolog.py"]:::module
        G2P["graph2prolog.py"]:::module
        LogicDir["logic/"]:::module
        mainPL["logic/main.pl"]:::module
        main2["logic/main2.pl"]:::module
        main3["logic/main3.pl"]:::module
        main4["logic/main4.pl"]:::module
        main5["logic/main5.pl"]:::module
        seaImpl["logic/sea_impl.pl"]:::module
        seaProto["logic/sea_proto_*.pl"]:::module
    end

    %% Persistence & Reporting
    subgraph "4. Persistence & Reporting"
        DB["Policy DB (db/)"]:::db
        Facts["facts/"]:::db
        StatsFiles["stats/"]:::db
    end

    %% Evaluation Harness
    subgraph "Evaluation Harness" style dashed
        Eval["eval/"]:::eval
        EvalTools["eval/tools/"]:::eval
    end

    %% Utility Modules
    UtilFile["util/file.py"]:::module
    UtilInit["util/__init__.py"]:::module

    %% External Dependencies
    subgraph "External Dependencies"
        LS["libsepol & setools"]:::external
        SWI["SWI-Prolog"]:::external
    end

    %% Data Flows
    CLI --> EX1
    CLI --> OL
    CLI --> AE

    EX1 --> FC
    OL --> FC
    AE --> FC

    FC --> SecPolicy
    IR --> SecPolicy
    SP --> SecPolicy
    CAP --> SecPolicy
    DAC --> SecPolicy
    PROP --> SecPolicy
    AFSC --> SecPolicy
    AFSH --> SecPolicy
    Config -.-> SecPolicy

    SecPolicy --> SG
    SG --> DB
    SG --> Facts
    SG --> StatsFiles

    SG --> G2P --> Facts
    Facts --> PR

    PR -.-> SWI

    LS -.-> FC
    LS -.-> SecPolicy

    DB --> Eval
    Eval --> EvalTools

    UtilFile -.-> EX1
    UtilFile -.-> OL
    UtilFile -.-> FC
    UtilInit -.-> SecPolicy

    %% Click Events
    click CLI "https://github.com/fics/bigmac/blob/master/process.py"
    click EX1 "https://github.com/fics/bigmac/blob/master/extract.py"
    click OL "https://github.com/fics/bigmac/blob/master/overlay.py"
    click AE "https://github.com/fics/bigmac/blob/master/tools/android-extract.sh"
    click FC "https://github.com/fics/bigmac/blob/master/android/file_contexts.py"
    click IR "https://github.com/fics/bigmac/blob/master/android/initrc.py"
    click SP "https://github.com/fics/bigmac/blob/master/android/sepolicy.py"
    click CAP "https://github.com/fics/bigmac/blob/master/android/capabilities.py"
    click DAC "https://github.com/fics/bigmac/blob/master/android/dac.py"
    click PROP "https://github.com/fics/bigmac/blob/master/android/property.py"
    click AFSC "https://github.com/fics/bigmac/blob/master/android/android_filesystem_config.h"
    click AFSH "https://github.com/fics/bigmac/blob/master/android/android_fs.h"
    click SecPolicy "https://github.com/fics/bigmac/blob/master/security_policy.py"
    click Config "https://github.com/fics/bigmac/blob/master/config.py"
    click SG "https://github.com/fics/bigmac/blob/master/segraph.py"
    click STATS "https://github.com/fics/bigmac/blob/master/stats.py"
    click SDUMP "https://github.com/fics/bigmac/blob/master/sedump.py"
    click PR "https://github.com/fics/bigmac/blob/master/prolog.py"
    click G2P "https://github.com/fics/bigmac/blob/master/graph2prolog.py"
    click LogicDir "https://github.com/fics/bigmac/tree/master/logic/"
    click mainPL "https://github.com/fics/bigmac/blob/master/logic/main.pl"
    click main2 "https://github.com/fics/bigmac/blob/master/logic/main2.pl"
    click main3 "https://github.com/fics/bigmac/blob/master/logic/main3.pl"
    click main4 "https://github.com/fics/bigmac/blob/master/logic/main4.pl"
    click main5 "https://github.com/fics/bigmac/blob/master/logic/main5.pl"
    click seaImpl "https://github.com/fics/bigmac/blob/master/logic/sea_impl.pl"
    click seaProto "https://github.com/fics/bigmac/blob/master/logic/sea_proto_*.pl"
    click DB "https://github.com/fics/bigmac/tree/master/facts/"
    click Facts "https://github.com/fics/bigmac/tree/master/facts/"
    click StatsFiles "https://github.com/fics/bigmac/tree/master/stats/"
    click Eval "https://github.com/fics/bigmac/tree/master/eval/"
    click EvalTools "https://github.com/fics/bigmac/tree/master/eval/tools/"
    click UtilFile "https://github.com/fics/bigmac/blob/master/util/file.py"
    click UtilInit "https://github.com/fics/bigmac/blob/master/util/__init__.py"

    %% Styles
    classDef module fill:#FFCC00,stroke:#333,stroke-width:1px;
    classDef db fill:#FFFF99,stroke:#333,stroke-width:1px;
    classDef external fill:#88CCEE,stroke:#333,stroke-width:1px;
    classDef eval fill:#CCFFFF,stroke:#333,stroke-width:1px;
    classDef script fill:#FFEEAA,stroke:#333,stroke-width:1px;
```
