# jonscafe/cglens architecture

> Architecture diagram of the GitHub repository jonscafe/cglens, 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/cglens
- Repository: https://github.com/jonscafe/cglens

## Overview

cglens is an offline analyzer for cglime container-memory captures. The principal workflow is analyst command → capture loading → shared analysis session → selected plugin → text or JSON report. Plugins recover distinct domains—tasks and ownership, process memory, files and page cache, ELF objects, and sockets—using kernel metadata and sparse-memory access. The graph preserves major README capabilities; relationships for unsampled plugins are documented rather than inferred from their names. Some internal scanner wiring is not shown in excerpts, so uncertain links are omitted.

Main entry points: [`cglens.py`](https://github.com/jonscafe/cglens/blob/main/cglens.py) (CLI dispatcher), [`lens/render.py`](https://github.com/jonscafe/cglens/blob/main/lens/render.py) (Report rendering), [`lens/session.py`](https://github.com/jonscafe/cglens/blob/main/lens/session.py) (Analysis session), [`lens/core/kernel.py`](https://github.com/jonscafe/cglens/blob/main/lens/core/kernel.py) (Kernel objects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command workflow"]
  node_cli["CLI dispatcher<br/>[cglens.py]"]
end

subgraph group_foundation["Capture foundation"]
  node_image["Capture image<br/>[image.py]"]
  node_btf["BTF metadata<br/>[btf.py]"]
  node_kernel["Kernel objects<br/>[kernel.py]"]
  node_layers["Sparse address spaces<br/>[layers.py]"]
  node_session["Analysis session<br/>[session.py]"]
end

subgraph group_process["Process analysis"]
  node_taskscan["Task discovery<br/>[tasks.py]"]
  node_ownership["Task ownership<br/>[ownership.py]"]
  node_psscan["All tasks<br/>[psscan.py]"]
  node_pslist["Owned processes<br/>[pslist.py]"]
  node_pstree["Process tree<br/>[pstree.py]"]
  node_vmas["VMA discovery<br/>[vmas.py]"]
  node_process_memory["Process memory tools"]
end

subgraph group_memory["Memory and files"]
  node_elfscan["ELF recovery<br/>[elf.py]"]
  node_elfplugin["ELF analysis<br/>[elfs.py]"]
  node_inodes["Inodes and cache<br/>[inodes.py]"]
  node_file_tools["File analysis"]
end

subgraph group_report["Other analysis and output"]
  node_socket_tools["Socket analysis<br/>[sockstat.py]"]
  node_grep["Memory search<br/>[grep.py]"]
  node_info["Capture information<br/>[info.py]"]
  node_render["Report rendering<br/>[render.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"runs command"| node_cli
node_cli -->|"opens capture"| node_image
node_cli -->|"creates session"| node_session
node_cli -->|"formats result"| node_render
node_image -->|"loads metadata"| node_btf
node_kernel -->|"uses type data"| node_btf
node_kernel -->|"reads address spaces"| node_layers
node_session -->|"builds kernel view"| node_kernel
node_session -->|"scans tasks"| node_taskscan
node_session -->|"judges ownership"| node_ownership
node_session -->|"finds VMAs"| node_vmas
node_session -->|"names mappings"| node_elfscan
node_session -->|"scans inodes"| node_inodes
node_psscan -->|"returns results"| node_render
node_pslist -->|"returns results"| node_render
node_pstree -->|"returns results"| node_render
node_process_memory -->|"returns results"| node_render
node_elfplugin -->|"uses scanner"| node_elfscan
node_elfplugin -->|"returns results"| node_render
node_file_tools -->|"uses inode scan"| node_inodes
node_file_tools -->|"returns results"| node_render
node_socket_tools -->|"returns results"| node_render
node_grep -->|"returns results"| node_render
node_info -->|"returns results"| node_render
node_cli -->|"dispatches plugin"| node_psscan
node_cli -->|"dispatches plugin"| node_pslist
node_cli -->|"dispatches plugin"| node_pstree
node_cli -->|"dispatches analyses"| node_process_memory
node_cli -->|"dispatches plugin"| node_elfplugin
node_cli -->|"dispatches analyses"| node_file_tools
node_cli -->|"dispatches plugin"| node_socket_tools
node_cli -->|"dispatches plugin"| node_grep
node_cli -->|"dispatches plugin"| node_info

click node_cli "https://github.com/jonscafe/cglens/blob/main/cglens.py"
click node_image "https://github.com/jonscafe/cglens/blob/main/lens/core/image.py"
click node_btf "https://github.com/jonscafe/cglens/blob/main/lens/core/btf.py"
click node_kernel "https://github.com/jonscafe/cglens/blob/main/lens/core/kernel.py"
click node_layers "https://github.com/jonscafe/cglens/blob/main/lens/core/layers.py"
click node_session "https://github.com/jonscafe/cglens/blob/main/lens/session.py"
click node_taskscan "https://github.com/jonscafe/cglens/blob/main/lens/scan/tasks.py"
click node_ownership "https://github.com/jonscafe/cglens/blob/main/lens/scan/ownership.py"
click node_psscan "https://github.com/jonscafe/cglens/blob/main/lens/plugins/psscan.py"
click node_pslist "https://github.com/jonscafe/cglens/blob/main/lens/plugins/pslist.py"
click node_pstree "https://github.com/jonscafe/cglens/blob/main/lens/plugins/pstree.py"
click node_vmas "https://github.com/jonscafe/cglens/blob/main/lens/scan/vmas.py"
click node_process_memory "https://github.com/jonscafe/cglens/tree/main/lens/plugins"
click node_elfscan "https://github.com/jonscafe/cglens/blob/main/lens/scan/elf.py"
click node_elfplugin "https://github.com/jonscafe/cglens/blob/main/lens/plugins/elfs.py"
click node_inodes "https://github.com/jonscafe/cglens/blob/main/lens/scan/inodes.py"
click node_file_tools "https://github.com/jonscafe/cglens/tree/main/lens/plugins"
click node_socket_tools "https://github.com/jonscafe/cglens/blob/main/lens/plugins/sockstat.py"
click node_grep "https://github.com/jonscafe/cglens/blob/main/lens/plugins/grep.py"
click node_info "https://github.com/jonscafe/cglens/blob/main/lens/plugins/info.py"
click node_render "https://github.com/jonscafe/cglens/blob/main/lens/render.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 toneBlue
class node_image,node_btf,node_kernel,node_layers,node_session toneAmber
class node_taskscan,node_ownership,node_psscan,node_pslist,node_pstree,node_vmas,node_process_memory toneMint
class node_elfscan,node_elfplugin,node_inodes,node_file_tools toneRose
class node_socket_tools,node_grep,node_info,node_render,node_analyst toneIndigo
```

## Components

### Command workflow

- [CLI dispatcher](https://github.com/jonscafe/cglens/blob/main/cglens.py): `cglens.py`

### Capture foundation

- [Capture image](https://github.com/jonscafe/cglens/blob/main/lens/core/image.py): `lens/core/image.py`
- [BTF metadata](https://github.com/jonscafe/cglens/blob/main/lens/core/btf.py): `lens/core/btf.py`
- [Kernel objects](https://github.com/jonscafe/cglens/blob/main/lens/core/kernel.py): `lens/core/kernel.py`
- [Sparse address spaces](https://github.com/jonscafe/cglens/blob/main/lens/core/layers.py): `lens/core/layers.py`
- [Analysis session](https://github.com/jonscafe/cglens/blob/main/lens/session.py): `lens/session.py`

### Process analysis

- [Task discovery](https://github.com/jonscafe/cglens/blob/main/lens/scan/tasks.py): `lens/scan/tasks.py`
- [Task ownership](https://github.com/jonscafe/cglens/blob/main/lens/scan/ownership.py): `lens/scan/ownership.py`
- [All tasks](https://github.com/jonscafe/cglens/blob/main/lens/plugins/psscan.py): `lens/plugins/psscan.py`
- [Owned processes](https://github.com/jonscafe/cglens/blob/main/lens/plugins/pslist.py): `lens/plugins/pslist.py`
- [Process tree](https://github.com/jonscafe/cglens/blob/main/lens/plugins/pstree.py): `lens/plugins/pstree.py`
- [VMA discovery](https://github.com/jonscafe/cglens/blob/main/lens/scan/vmas.py): `lens/scan/vmas.py`
- [Process memory tools](https://github.com/jonscafe/cglens/tree/main/lens/plugins): `lens/plugins`

### Memory and files

- [ELF recovery](https://github.com/jonscafe/cglens/blob/main/lens/scan/elf.py): `lens/scan/elf.py`
- [ELF analysis](https://github.com/jonscafe/cglens/blob/main/lens/plugins/elfs.py): `lens/plugins/elfs.py`
- [Inodes and cache](https://github.com/jonscafe/cglens/blob/main/lens/scan/inodes.py): `lens/scan/inodes.py`
- [File analysis](https://github.com/jonscafe/cglens/tree/main/lens/plugins): `lens/plugins`

### Other analysis and output

- [Socket analysis](https://github.com/jonscafe/cglens/blob/main/lens/plugins/sockstat.py): `lens/plugins/sockstat.py`
- [Memory search](https://github.com/jonscafe/cglens/blob/main/lens/plugins/grep.py): `lens/plugins/grep.py`
- [Capture information](https://github.com/jonscafe/cglens/blob/main/lens/plugins/info.py): `lens/plugins/info.py`
- [Report rendering](https://github.com/jonscafe/cglens/blob/main/lens/render.py): `lens/render.py`

### Other components

- **Analyst**

## Connections

- Analyst → CLI dispatcher: runs command (evidence: `README.md`)
- CLI dispatcher → Capture image: opens capture (evidence: `cglens.py`)
- CLI dispatcher → Analysis session: creates session (evidence: `cglens.py`)
- CLI dispatcher → Report rendering: formats result (evidence: `cglens.py`)
- Capture image → BTF metadata: loads metadata (evidence: `lens/core/image.py`)
- Kernel objects → BTF metadata: uses type data (evidence: `lens/core/kernel.py`)
- Kernel objects → Sparse address spaces: reads address spaces (evidence: `lens/core/kernel.py`)
- Analysis session → Kernel objects: builds kernel view (evidence: `lens/session.py`)
- Analysis session → Task discovery: scans tasks (evidence: `lens/session.py`)
- Analysis session → Task ownership: judges ownership (evidence: `lens/session.py`)
- Analysis session → VMA discovery: finds VMAs (evidence: `lens/session.py`)
- Analysis session → ELF recovery: names mappings (evidence: `lens/session.py`)
- Analysis session → Inodes and cache: scans inodes (evidence: `lens/session.py`)
- All tasks → Report rendering: returns results (evidence: `lens/plugins/psscan.py`)
- Owned processes → Report rendering: returns results (evidence: `lens/plugins/pslist.py`)
- Process tree → Report rendering: returns results (evidence: `lens/plugins/pstree.py`)
- Process memory tools → Report rendering: returns results (evidence: `README.md`)
- ELF analysis → ELF recovery: uses scanner (evidence: `lens/plugins/elfs.py`)
- ELF analysis → Report rendering: returns results (evidence: `lens/plugins/elfs.py`)
- File analysis → Inodes and cache: uses inode scan (evidence: `lens/plugins/files.py`)
- File analysis → Report rendering: returns results (evidence: `README.md`)
- Socket analysis → Report rendering: returns results (evidence: `lens/plugins/sockstat.py`)
- Memory search → Report rendering: returns results (evidence: `lens/plugins/grep.py`)
- Capture information → Report rendering: returns results (evidence: `lens/plugins/info.py`)
- CLI dispatcher → All tasks: dispatches plugin (evidence: `cglens.py`)
- CLI dispatcher → Owned processes: dispatches plugin (evidence: `cglens.py`)
- CLI dispatcher → Process tree: dispatches plugin (evidence: `cglens.py`)
- CLI dispatcher → Process memory tools: dispatches analyses (evidence: `README.md`)
- CLI dispatcher → ELF analysis: dispatches plugin (evidence: `cglens.py`)
- CLI dispatcher → File analysis: dispatches analyses (evidence: `README.md`)
- CLI dispatcher → Socket analysis: dispatches plugin (evidence: `README.md`)
- CLI dispatcher → Memory search: dispatches plugin (evidence: `README.md`)
- CLI dispatcher → Capture information: dispatches plugin (evidence: `README.md`)