# jonscafe/cglime architecture

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

- Interactive diagram: https://gitdiagram.com/jonscafe/cglime
- Repository: https://github.com/jonscafe/cglime

## Overview

cglime acquires physical pages belonging to a selected container or Kubernetes pod, rather than dumping all host RAM. The documented workflow is to identify and freeze the target, acquire a LiME dump, verify it, and create an evidence package. Acquisition includes regular and slab-page attribution, compound-page handling, and an independent kpagecgroup path; analysis tools add scoped process and memory checks. README and source-index references support the shown relationships, but several orchestration and evidence-package internals were not excerpted, so those connections are left unasserted.

Main entry points: [`memcg_scan.py`](https://github.com/jonscafe/cglime/blob/main/memcg_scan.py) (Memcg scan), [`cgroupres.py`](https://github.com/jonscafe/cglime/blob/main/cgroupres.py) (Cgroup resolution), [`pslist_scoped.py`](https://github.com/jonscafe/cglime/blob/main/pslist_scoped.py) (Scoped process list), [`slab_probe.py`](https://github.com/jonscafe/cglime/blob/main/slab_probe.py) (Slab attribution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Acquisition"]
  node_cli["Command interface<br/>[cglime.py]"]
  node_lime["LiME writer<br/>[limefmt.py]"]
  node_acquire["Page-table acquisition<br/>[acquire.py]"]
  node_kpage["kpagecgroup path<br/>[kpagecg.py]"]
  node_hybrid["Hybrid dump<br/>[hybrid_dump.py]"]
end

subgraph group_attribution["Attribution"]
  node_resolve["Cgroup resolution<br/>[cgroupres.py]"]
  node_ebpf["Physical reader<br/>[rawbpf.py]"]
  node_scan["Memcg scan<br/>[memcg_scan.py]"]
  node_slab["Slab attribution<br/>[slab_probe.py]"]
  node_slabgeom["Slab geometry<br/>[slabgeom.py]"]
  node_folio["Compound pages<br/>[folio.py]"]
  node_gate["Kernel semantics<br/>[kernelgate.py]"]
end

subgraph group_validation["Validation"]
  node_calibrate["Kernel calibration<br/>[calibrate.py]"]
  node_envelope["Coverage checks<br/>[envelope.py]"]
  node_probe["Host probe<br/>[probe_host.py]"]
  node_compoundprobe["Compound probe<br/>[compound_probe.py]"]
  node_memcgprobe["Memcg probe<br/>[memcg_probe.py]"]
  node_spotcheck["Spot checks<br/>[spotcheck.py]"]
  node_analyzability["Dump analyzability<br/>[analyzability.py]"]
end

subgraph group_analysis["Live analysis"]
  node_zswap["Swap accounting<br/>[zswap.py]"]
  node_pslist["Scoped process list<br/>[pslist_scoped.py]"]
  node_btf["BTF reader<br/>[btf.py]"]
end

subgraph group_evidence["Evidence"]
  node_sidecar["Capture sidecars<br/>[sidecar.py]"]
  node_evidence["Evidence package<br/>[evidence.py]"]
  node_bundle["Capture bundle<br/>[bundle.py]"]
end

node_operator(("Operator"))
node_target(("Container or pod"))

node_operator -->|"runs commands"| node_cli
node_target -->|"supplies identifier"| node_cli
node_cli -.->|"dispatches acquisition"| node_acquire
node_cli -.->|"dispatches packaging"| node_evidence
node_acquire -->|"resolves target"| node_resolve
node_acquire -->|"uses page geometry"| node_folio
node_acquire -->|"checks kernel semantics"| node_gate
node_acquire -->|"writes LiME"| node_lime
node_scan -->|"resolves cgroups"| node_resolve
node_scan -->|"reads physical memory"| node_ebpf
node_scan -->|"handles compound pages"| node_folio
node_scan -->|"reads slab geometry"| node_slabgeom
node_scan -->|"uses calibration"| node_calibrate
node_scan -->|"checks kernel semantics"| node_gate
node_scan -->|"checks coverage"| node_envelope
node_scan -->|"accounts swap"| node_zswap
node_scan -->|"writes sidecars"| node_sidecar
node_slab -->|"resolves target"| node_resolve
node_slab -->|"reads physical memory"| node_ebpf
node_slab -->|"handles compound pages"| node_folio
node_slab -->|"reads slab geometry"| node_slabgeom
node_slab -->|"checks kernel semantics"| node_gate
node_kpage -->|"resolves target"| node_resolve
node_kpage -->|"checks coverage"| node_envelope
node_hybrid -->|"resolves target"| node_resolve
node_hybrid -->|"reads physical memory"| node_ebpf
node_calibrate -->|"calibrates constants"| node_folio
node_probe -->|"checks kernel support"| node_gate
node_compoundprobe -->|"resolves target"| node_resolve
node_compoundprobe -->|"tests compound pages"| node_folio
node_compoundprobe -->|"reads physical memory"| node_ebpf
node_memcgprobe -->|"resolves target"| node_resolve
node_memcgprobe -->|"uses page geometry"| node_folio
node_memcgprobe -->|"reads physical memory"| node_ebpf
node_pslist -->|"reads kernel types"| node_btf
node_pslist -->|"resolves target"| node_resolve
node_pslist -->|"reads physical memory"| node_ebpf
node_pslist -->|"uses slab attribution"| node_slab
node_pslist -->|"reads slab geometry"| node_slabgeom
node_pslist -->|"checks kernel semantics"| node_gate
node_zswap -->|"resolves target"| node_resolve
node_kpage -->|"checks captured totals"| node_envelope
node_operator -->|"requests package"| node_evidence

click node_cli "https://github.com/jonscafe/cglime/blob/main/cglime.py"
click node_resolve "https://github.com/jonscafe/cglime/blob/main/cgroupres.py"
click node_ebpf "https://github.com/jonscafe/cglime/blob/main/ebpf/rawbpf.py"
click node_scan "https://github.com/jonscafe/cglime/blob/main/memcg_scan.py"
click node_slab "https://github.com/jonscafe/cglime/blob/main/slab_probe.py"
click node_slabgeom "https://github.com/jonscafe/cglime/blob/main/slabgeom.py"
click node_folio "https://github.com/jonscafe/cglime/blob/main/folio.py"
click node_gate "https://github.com/jonscafe/cglime/blob/main/kernelgate.py"
click node_lime "https://github.com/jonscafe/cglime/blob/main/limefmt.py"
click node_acquire "https://github.com/jonscafe/cglime/blob/main/acquire.py"
click node_kpage "https://github.com/jonscafe/cglime/blob/main/kpagecg.py"
click node_hybrid "https://github.com/jonscafe/cglime/blob/main/hybrid_dump.py"
click node_calibrate "https://github.com/jonscafe/cglime/blob/main/calibrate.py"
click node_envelope "https://github.com/jonscafe/cglime/blob/main/envelope.py"
click node_probe "https://github.com/jonscafe/cglime/blob/main/probe_host.py"
click node_compoundprobe "https://github.com/jonscafe/cglime/blob/main/compound_probe.py"
click node_memcgprobe "https://github.com/jonscafe/cglime/blob/main/memcg_probe.py"
click node_spotcheck "https://github.com/jonscafe/cglime/blob/main/spotcheck.py"
click node_zswap "https://github.com/jonscafe/cglime/blob/main/zswap.py"
click node_pslist "https://github.com/jonscafe/cglime/blob/main/pslist_scoped.py"
click node_btf "https://github.com/jonscafe/cglime/blob/main/btf.py"
click node_sidecar "https://github.com/jonscafe/cglime/blob/main/sidecar.py"
click node_evidence "https://github.com/jonscafe/cglime/blob/main/evidence.py"
click node_bundle "https://github.com/jonscafe/cglime/blob/main/bundle.py"
click node_analyzability "https://github.com/jonscafe/cglime/blob/main/analyzability.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lime,node_acquire,node_kpage,node_hybrid toneBlue
class node_resolve,node_ebpf,node_scan,node_slab,node_slabgeom,node_folio,node_gate toneAmber
class node_calibrate,node_envelope,node_probe,node_compoundprobe,node_memcgprobe,node_spotcheck,node_analyzability toneMint
class node_zswap,node_pslist,node_btf toneRose
class node_sidecar,node_evidence,node_bundle,node_operator,node_target toneIndigo
```

## Components

### Acquisition

- [Command interface](https://github.com/jonscafe/cglime/blob/main/cglime.py): `cglime.py`
- [LiME writer](https://github.com/jonscafe/cglime/blob/main/limefmt.py): `limefmt.py`
- [Page-table acquisition](https://github.com/jonscafe/cglime/blob/main/acquire.py): `acquire.py`
- [kpagecgroup path](https://github.com/jonscafe/cglime/blob/main/kpagecg.py): `kpagecg.py`
- [Hybrid dump](https://github.com/jonscafe/cglime/blob/main/hybrid_dump.py): `hybrid_dump.py`

### Attribution

- [Cgroup resolution](https://github.com/jonscafe/cglime/blob/main/cgroupres.py): `cgroupres.py`
- [Physical reader](https://github.com/jonscafe/cglime/blob/main/ebpf/rawbpf.py): `ebpf/rawbpf.py`
- [Memcg scan](https://github.com/jonscafe/cglime/blob/main/memcg_scan.py): `memcg_scan.py`
- [Slab attribution](https://github.com/jonscafe/cglime/blob/main/slab_probe.py): `slab_probe.py`
- [Slab geometry](https://github.com/jonscafe/cglime/blob/main/slabgeom.py): `slabgeom.py`
- [Compound pages](https://github.com/jonscafe/cglime/blob/main/folio.py): `folio.py`
- [Kernel semantics](https://github.com/jonscafe/cglime/blob/main/kernelgate.py): `kernelgate.py`

### Validation

- [Kernel calibration](https://github.com/jonscafe/cglime/blob/main/calibrate.py): `calibrate.py`
- [Coverage checks](https://github.com/jonscafe/cglime/blob/main/envelope.py): `envelope.py`
- [Host probe](https://github.com/jonscafe/cglime/blob/main/probe_host.py): `probe_host.py`
- [Compound probe](https://github.com/jonscafe/cglime/blob/main/compound_probe.py): `compound_probe.py`
- [Memcg probe](https://github.com/jonscafe/cglime/blob/main/memcg_probe.py): `memcg_probe.py`
- [Spot checks](https://github.com/jonscafe/cglime/blob/main/spotcheck.py): `spotcheck.py`
- [Dump analyzability](https://github.com/jonscafe/cglime/blob/main/analyzability.py): `analyzability.py`

### Live analysis

- [Swap accounting](https://github.com/jonscafe/cglime/blob/main/zswap.py): `zswap.py`
- [Scoped process list](https://github.com/jonscafe/cglime/blob/main/pslist_scoped.py): `pslist_scoped.py`
- [BTF reader](https://github.com/jonscafe/cglime/blob/main/btf.py): `btf.py`

### Evidence

- [Capture sidecars](https://github.com/jonscafe/cglime/blob/main/sidecar.py): `sidecar.py`
- [Evidence package](https://github.com/jonscafe/cglime/blob/main/evidence.py): `evidence.py`
- [Capture bundle](https://github.com/jonscafe/cglime/blob/main/bundle.py): `bundle.py`

### Other components

- **Operator**
- **Container or pod**

## Connections

- Operator → Command interface: runs commands (evidence: `README.md`)
- Container or pod → Command interface: supplies identifier (evidence: `README.md`)
- Command interface → Page-table acquisition: dispatches acquisition
- Command interface → Evidence package: dispatches packaging
- Page-table acquisition → Cgroup resolution: resolves target (evidence: `acquire.py`)
- Page-table acquisition → Compound pages: uses page geometry (evidence: `acquire.py`)
- Page-table acquisition → Kernel semantics: checks kernel semantics (evidence: `acquire.py`)
- Page-table acquisition → LiME writer: writes LiME (evidence: `acquire.py`)
- Memcg scan → Cgroup resolution: resolves cgroups (evidence: `memcg_scan.py`)
- Memcg scan → Physical reader: reads physical memory (evidence: `memcg_scan.py`)
- Memcg scan → Compound pages: handles compound pages (evidence: `memcg_scan.py`)
- Memcg scan → Slab geometry: reads slab geometry (evidence: `memcg_scan.py`)
- Memcg scan → Kernel calibration: uses calibration (evidence: `memcg_scan.py`)
- Memcg scan → Kernel semantics: checks kernel semantics (evidence: `memcg_scan.py`)
- Memcg scan → Coverage checks: checks coverage (evidence: `memcg_scan.py`)
- Memcg scan → Swap accounting: accounts swap (evidence: `memcg_scan.py`)
- Memcg scan → Capture sidecars: writes sidecars (evidence: `memcg_scan.py`)
- Slab attribution → Cgroup resolution: resolves target (evidence: `slab_probe.py`)
- Slab attribution → Physical reader: reads physical memory (evidence: `slab_probe.py`)
- Slab attribution → Compound pages: handles compound pages (evidence: `slab_probe.py`)
- Slab attribution → Slab geometry: reads slab geometry (evidence: `slab_probe.py`)
- Slab attribution → Kernel semantics: checks kernel semantics (evidence: `slab_probe.py`)
- kpagecgroup path → Cgroup resolution: resolves target (evidence: `kpagecg.py`)
- kpagecgroup path → Coverage checks: checks coverage (evidence: `kpagecg.py`)
- Hybrid dump → Cgroup resolution: resolves target (evidence: `hybrid_dump.py`)
- Hybrid dump → Physical reader: reads physical memory (evidence: `hybrid_dump.py`)
- Kernel calibration → Compound pages: calibrates constants (evidence: `calibrate.py`)
- Host probe → Kernel semantics: checks kernel support (evidence: `probe_host.py`)
- Compound probe → Cgroup resolution: resolves target (evidence: `compound_probe.py`)
- Compound probe → Compound pages: tests compound pages (evidence: `compound_probe.py`)
- Compound probe → Physical reader: reads physical memory (evidence: `compound_probe.py`)
- Memcg probe → Cgroup resolution: resolves target (evidence: `memcg_probe.py`)
- Memcg probe → Compound pages: uses page geometry (evidence: `memcg_probe.py`)
- Memcg probe → Physical reader: reads physical memory (evidence: `memcg_probe.py`)
- Scoped process list → BTF reader: reads kernel types (evidence: `pslist_scoped.py`)
- Scoped process list → Cgroup resolution: resolves target (evidence: `pslist_scoped.py`)
- Scoped process list → Physical reader: reads physical memory (evidence: `pslist_scoped.py`)
- Scoped process list → Slab attribution: uses slab attribution (evidence: `pslist_scoped.py`)
- Scoped process list → Slab geometry: reads slab geometry (evidence: `pslist_scoped.py`)
- Scoped process list → Kernel semantics: checks kernel semantics (evidence: `pslist_scoped.py`)
- Swap accounting → Cgroup resolution: resolves target (evidence: `zswap.py`)
- kpagecgroup path → Coverage checks: checks captured totals (evidence: `kpagecg.py`)
- Operator → Evidence package: requests package (evidence: `README.md`)