# matheuzsecurity/singularity architecture

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

- Interactive diagram: https://gitdiagram.com/matheuzsecurity/singularity
- Repository: https://github.com/matheuzsecurity/singularity

## Overview

Singularity is a Linux kernel-module rootkit whose main runtime flow initializes stealth and evasion hooks; users trigger process concealment or privilege changes with signals, while a helper script sends the documented ICMP trigger. The graph includes the principal concealment stages and documented anti-detection branches. The sampled initializer shows which modules it initializes, but most module internals were not excerpted, so their interconnections are omitted rather than inferred.

Main entry points: [`main.c`](https://github.com/matheuzsecurity/singularity/blob/main/main.c) (Module Lifecycle), [`modules/bpf_hook.c`](https://github.com/matheuzsecurity/singularity/blob/main/modules/bpf_hook.c) (BPF Event Filtering), [`scripts/trigger.py`](https://github.com/matheuzsecurity/singularity/blob/main/scripts/trigger.py) (ICMP Trigger Client), [`modules/trace.c`](https://github.com/matheuzsecurity/singularity/blob/main/modules/trace.c) (Process Hiding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Kernel Runtime"]
  node_main["Module Lifecycle<br/>[main.c]"]
  node_ftrace["Ftrace Hooking<br/>[ftrace_helper.c]"]
end

subgraph group_concealment["Stealth Controls"]
  node_pidstate[("Hidden PID State<br/>[hidden_pids.c]")]
  node_process["Process Hiding<br/>[trace.c]"]
  node_filesystem["Directory Hiding<br/>[hiding_directory.c]"]
  node_stat["Path Metadata Hiding<br/>[hiding_stat.c]"]
  node_chdir["Hidden Path Blocking<br/>[hiding_chdir.c]"]
  node_readlink["Link Hiding<br/>[hiding_readlink.c]"]
  node_network["Connection Hiding<br/>[hiding_tcp.c]"]
  node_modulehide["Module Self-Hiding<br/>[hide_module.c]"]
end

subgraph group_evasion["Detection Evasion"]
  node_logs["Log Filtering"]
  node_io["I/O Filtering<br/>[hooks_write.c]"]
  node_bpf["BPF Event Filtering<br/>[bpf_hook.c]"]
  node_audit["Audit Filtering<br/>[audit.c]"]
  node_selfdefense["Hook Protection<br/>[selfdefense.c]"]
  node_lkrg["LKRG Bypass<br/>[lkrg_bypass.c]"]
  node_taint["Taint Normalization<br/>[reset_tainted.c]"]
  node_taskstats["TaskStats Filtering<br/>[task.c]"]
  node_sysrq["Sysrq Hook<br/>[sysrq_hook.c]"]
end

subgraph group_access["Access Triggers"]
  node_privilege["Signal Privilege<br/>[become_root.c]"]
  node_icmp["ICMP Shell Trigger<br/>[icmp.c]"]
  node_trigger["ICMP Trigger Client<br/>[trigger.py]"]
end

node_user(("Local Operator"))
node_remote(("Remote Operator"))

node_main -->|"initializes first"| node_lkrg
node_main -->|"initializes"| node_selfdefense
node_main -->|"initializes"| node_taint
node_main -->|"initializes"| node_privilege
node_main -->|"initializes"| node_filesystem
node_main -->|"initializes"| node_stat
node_main -->|"initializes"| node_network
node_main -->|"initializes"| node_logs
node_main -->|"initializes"| node_io
node_main -->|"initializes"| node_chdir
node_main -->|"initializes"| node_readlink
node_main -->|"initializes"| node_bpf
node_main -->|"initializes"| node_icmp
node_main -->|"initializes"| node_process
node_main -->|"initializes"| node_audit
node_main -->|"initializes"| node_taskstats
node_main -->|"initializes"| node_sysrq
node_main -->|"hides module"| node_modulehide
node_user -->|"sends signal"| node_privilege
node_user -->|"marks process"| node_process
node_remote -->|"requests trigger"| node_trigger
node_trigger -->|"sends ICMP"| node_icmp
node_bpf -->|"checks hidden PIDs"| node_pidstate

click node_main "https://github.com/matheuzsecurity/singularity/blob/main/main.c"
click node_ftrace "https://github.com/matheuzsecurity/singularity/blob/main/ftrace/ftrace_helper.c"
click node_pidstate "https://github.com/matheuzsecurity/singularity/blob/main/modules/hidden_pids.c"
click node_process "https://github.com/matheuzsecurity/singularity/blob/main/modules/trace.c"
click node_filesystem "https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_directory.c"
click node_stat "https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_stat.c"
click node_chdir "https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_chdir.c"
click node_readlink "https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_readlink.c"
click node_network "https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_tcp.c"
click node_modulehide "https://github.com/matheuzsecurity/singularity/blob/main/modules/hide_module.c"
click node_privilege "https://github.com/matheuzsecurity/singularity/blob/main/modules/become_root.c"
click node_icmp "https://github.com/matheuzsecurity/singularity/blob/main/modules/icmp.c"
click node_trigger "https://github.com/matheuzsecurity/singularity/blob/main/scripts/trigger.py"
click node_logs "https://github.com/matheuzsecurity/singularity/blob/main/modules/clear_taint_dmesg.c"
click node_io "https://github.com/matheuzsecurity/singularity/blob/main/modules/hooks_write.c"
click node_bpf "https://github.com/matheuzsecurity/singularity/blob/main/modules/bpf_hook.c"
click node_audit "https://github.com/matheuzsecurity/singularity/blob/main/modules/audit.c"
click node_selfdefense "https://github.com/matheuzsecurity/singularity/blob/main/modules/selfdefense.c"
click node_lkrg "https://github.com/matheuzsecurity/singularity/blob/main/modules/lkrg_bypass.c"
click node_taint "https://github.com/matheuzsecurity/singularity/blob/main/modules/reset_tainted.c"
click node_taskstats "https://github.com/matheuzsecurity/singularity/blob/main/modules/task.c"
click node_sysrq "https://github.com/matheuzsecurity/singularity/blob/main/modules/sysrq_hook.c"

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_main,node_ftrace toneBlue
class node_pidstate,node_process,node_filesystem,node_stat,node_chdir,node_readlink,node_network,node_modulehide toneAmber
class node_logs,node_io,node_bpf,node_audit,node_selfdefense,node_lkrg,node_taint,node_taskstats,node_sysrq toneMint
class node_privilege,node_icmp,node_trigger toneRose
class node_user,node_remote toneIndigo
```

## Components

### Kernel Runtime

- [Module Lifecycle](https://github.com/matheuzsecurity/singularity/blob/main/main.c): `main.c`
- [Ftrace Hooking](https://github.com/matheuzsecurity/singularity/blob/main/ftrace/ftrace_helper.c): `ftrace/ftrace_helper.c`

### Stealth Controls

- [Hidden PID State](https://github.com/matheuzsecurity/singularity/blob/main/modules/hidden_pids.c): `modules/hidden_pids.c`
- [Process Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/trace.c): `modules/trace.c`
- [Directory Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_directory.c): `modules/hiding_directory.c`
- [Path Metadata Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_stat.c): `modules/hiding_stat.c`
- [Hidden Path Blocking](https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_chdir.c): `modules/hiding_chdir.c`
- [Link Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_readlink.c): `modules/hiding_readlink.c`
- [Connection Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/hiding_tcp.c): `modules/hiding_tcp.c`
- [Module Self-Hiding](https://github.com/matheuzsecurity/singularity/blob/main/modules/hide_module.c): `modules/hide_module.c`

### Detection Evasion

- [Log Filtering](https://github.com/matheuzsecurity/singularity/blob/main/modules/clear_taint_dmesg.c): `modules/clear_taint_dmesg.c`
- [I/O Filtering](https://github.com/matheuzsecurity/singularity/blob/main/modules/hooks_write.c): `modules/hooks_write.c`
- [BPF Event Filtering](https://github.com/matheuzsecurity/singularity/blob/main/modules/bpf_hook.c): `modules/bpf_hook.c`
- [Audit Filtering](https://github.com/matheuzsecurity/singularity/blob/main/modules/audit.c): `modules/audit.c`
- [Hook Protection](https://github.com/matheuzsecurity/singularity/blob/main/modules/selfdefense.c): `modules/selfdefense.c`
- [LKRG Bypass](https://github.com/matheuzsecurity/singularity/blob/main/modules/lkrg_bypass.c): `modules/lkrg_bypass.c`
- [Taint Normalization](https://github.com/matheuzsecurity/singularity/blob/main/modules/reset_tainted.c): `modules/reset_tainted.c`
- [TaskStats Filtering](https://github.com/matheuzsecurity/singularity/blob/main/modules/task.c): `modules/task.c`
- [Sysrq Hook](https://github.com/matheuzsecurity/singularity/blob/main/modules/sysrq_hook.c): `modules/sysrq_hook.c`

### Access Triggers

- [Signal Privilege](https://github.com/matheuzsecurity/singularity/blob/main/modules/become_root.c): `modules/become_root.c`
- [ICMP Shell Trigger](https://github.com/matheuzsecurity/singularity/blob/main/modules/icmp.c): `modules/icmp.c`
- [ICMP Trigger Client](https://github.com/matheuzsecurity/singularity/blob/main/scripts/trigger.py): `scripts/trigger.py`

### Other components

- **Local Operator**
- **Remote Operator**

## Connections

- Module Lifecycle → LKRG Bypass: initializes first (evidence: `main.c`)
- Module Lifecycle → Hook Protection: initializes (evidence: `main.c`)
- Module Lifecycle → Taint Normalization: initializes (evidence: `main.c`)
- Module Lifecycle → Signal Privilege: initializes (evidence: `main.c`)
- Module Lifecycle → Directory Hiding: initializes (evidence: `main.c`)
- Module Lifecycle → Path Metadata Hiding: initializes (evidence: `main.c`)
- Module Lifecycle → Connection Hiding: initializes (evidence: `main.c`)
- Module Lifecycle → Log Filtering: initializes (evidence: `main.c`)
- Module Lifecycle → I/O Filtering: initializes (evidence: `main.c`)
- Module Lifecycle → Hidden Path Blocking: initializes (evidence: `main.c`)
- Module Lifecycle → Link Hiding: initializes (evidence: `main.c`)
- Module Lifecycle → BPF Event Filtering: initializes (evidence: `main.c`)
- Module Lifecycle → ICMP Shell Trigger: initializes (evidence: `main.c`)
- Module Lifecycle → Process Hiding: initializes (evidence: `main.c`)
- Module Lifecycle → Audit Filtering: initializes (evidence: `main.c`)
- Module Lifecycle → TaskStats Filtering: initializes (evidence: `main.c`)
- Module Lifecycle → Sysrq Hook: initializes (evidence: `main.c`)
- Module Lifecycle → Module Self-Hiding: hides module (evidence: `main.c`)
- Local Operator → Signal Privilege: sends signal
- Local Operator → Process Hiding: marks process
- Remote Operator → ICMP Trigger Client: requests trigger
- ICMP Trigger Client → ICMP Shell Trigger: sends ICMP
- BPF Event Filtering → Hidden PID State: checks hidden PIDs (evidence: `modules/bpf_hook.c`)