# bkili/peek-a-boo architecture

> Architecture diagram of the GitHub repository bkili/peek-a-boo, 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/bkili/peek-a-boo
- Repository: https://github.com/bkili/peek-a-boo

## Overview

Peek-A-Boo is a modular post-exploitation framework operated through an interactive CLI. Its main workflow loads configuration and plugins, accepts commands, selects a module or exploit, and runs it with shared runtime data; modules can also run declared dependencies. The graph preserves the documented configuration, plugin, exploit, OSINT, reconnaissance, privilege-escalation, and utility capabilities. Sampled files show CLI dispatch and selected module integrations; unsampled module internals are represented by their existing directories, and links without direct evidence are omitted.

Main entry points: [`core/commands`](https://github.com/bkili/peek-a-boo/tree/main/core/commands) (Command handlers), [`core/cli.py`](https://github.com/bkili/peek-a-boo/blob/main/core/cli.py) (Interactive CLI), [`modules`](https://github.com/bkili/peek-a-boo/tree/main/modules) (OSINT, recon, privilege checks), [`main.py`](https://github.com/bkili/peek-a-boo/blob/main/main.py) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and CLI"]
  node_main["Application startup<br/>[main.py]"]
  node_cli["Interactive CLI<br/>[cli.py]"]
  node_commands["Command handlers"]
  node_completer["Command completion<br/>[completer.py]"]
end

subgraph group_runtime["Framework runtime"]
  node_registry["Command registry<br/>[registry.py]"]
  node_state["Global state<br/>[state.py]"]
  node_config["Configuration<br/>[config_ops.py]"]
  node_formatter["Rich output<br/>[formatter.py]"]
  node_listing["Catalog listing<br/>[listing.py]"]
  node_base_module["Module contract<br/>[base.py]"]
  node_progress["Progress display<br/>[progress_bar.py]"]
  node_plugin_base["Plugin contract<br/>[base_plugin.py]"]
end

subgraph group_catalog["Modules and extensions"]
  node_plugin_loader["Plugin loading<br/>[plugin.py]"]
  node_plugins["Plugins"]
end

subgraph group_operations["Security operations"]
  node_modules["OSINT, recon, privilege checks"]
  node_exploits["Exploit components"]
  node_ssh["SSH and SFTP<br/>[ssh_handler.py]"]
  node_cve["CVE reference data<br/>[cve_list.py]"]
  node_holehe_runner["Email lookup runner"]
end

node_user(("Operator"))

node_user -->|"enters commands"| node_cli
node_main -->|"loads settings"| node_config
node_main -->|"loads plugins"| node_plugin_loader
node_main -->|"starts"| node_cli
node_main -->|"registers plugin commands"| node_registry
node_cli -->|"dispatches commands"| node_registry
node_cli -->|"imports handlers"| node_commands
node_cli -->|"requests completions"| node_completer
node_commands -->|"registers handlers"| node_registry
node_commands -->|"selects active module"| node_state
node_commands -->|"loads and runs"| node_modules
node_commands -->|"loads selected exploit"| node_exploits
node_commands -->|"loads selected plugin"| node_plugins
node_commands -->|"uses module interface"| node_base_module
node_plugin_loader -->|"instantiates plugins"| node_plugin_base
node_plugin_loader -->|"loads configured plugins"| node_plugins
node_modules -->|"uses remote access"| node_ssh
node_modules -->|"checks CVE data"| node_cve
node_modules -->|"runs email lookup"| node_holehe_runner
node_modules -->|"displays progress"| node_progress
node_commands -->|"saves and loads"| node_config
node_commands -->|"lists available tools"| node_listing
node_commands -->|"formats output"| node_formatter
node_completer -->|"completes tool names"| node_listing
node_cli -->|"shares runtime data"| node_state
node_plugins -->|"implements extension contract"| node_plugin_base

click node_main "https://github.com/bkili/peek-a-boo/blob/main/main.py"
click node_cli "https://github.com/bkili/peek-a-boo/blob/main/core/cli.py"
click node_commands "https://github.com/bkili/peek-a-boo/tree/main/core/commands"
click node_completer "https://github.com/bkili/peek-a-boo/blob/main/core/completer.py"
click node_registry "https://github.com/bkili/peek-a-boo/blob/main/core/registry.py"
click node_state "https://github.com/bkili/peek-a-boo/blob/main/core/state.py"
click node_config "https://github.com/bkili/peek-a-boo/blob/main/core/config_ops.py"
click node_formatter "https://github.com/bkili/peek-a-boo/blob/main/core/utils/formatter.py"
click node_listing "https://github.com/bkili/peek-a-boo/blob/main/core/utils/listing.py"
click node_base_module "https://github.com/bkili/peek-a-boo/blob/main/modules/base.py"
click node_plugin_loader "https://github.com/bkili/peek-a-boo/blob/main/core/plugin.py"
click node_plugins "https://github.com/bkili/peek-a-boo/tree/main/plugins"
click node_modules "https://github.com/bkili/peek-a-boo/tree/main/modules"
click node_exploits "https://github.com/bkili/peek-a-boo/tree/main/exploits"
click node_ssh "https://github.com/bkili/peek-a-boo/blob/main/core/utils/ssh_handler.py"
click node_cve "https://github.com/bkili/peek-a-boo/blob/main/core/utils/cve_list.py"
click node_holehe_runner "https://github.com/bkili/peek-a-boo/blob/main/core/contrib/holehe_async_runner.py"
click node_progress "https://github.com/bkili/peek-a-boo/blob/main/core/utils/progress_bar.py"
click node_plugin_base "https://github.com/bkili/peek-a-boo/blob/main/core/base_plugin.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_main,node_cli,node_commands,node_completer toneBlue
class node_registry,node_state,node_config,node_formatter,node_listing,node_base_module,node_progress,node_plugin_base toneAmber
class node_plugin_loader,node_plugins toneMint
class node_modules,node_exploits,node_ssh,node_cve,node_holehe_runner toneRose
class node_user toneIndigo
```

## Components

### Startup and CLI

- [Application startup](https://github.com/bkili/peek-a-boo/blob/main/main.py): `main.py`
- [Interactive CLI](https://github.com/bkili/peek-a-boo/blob/main/core/cli.py): `core/cli.py`
- [Command handlers](https://github.com/bkili/peek-a-boo/tree/main/core/commands): `core/commands`
- [Command completion](https://github.com/bkili/peek-a-boo/blob/main/core/completer.py): `core/completer.py`

### Framework runtime

- [Command registry](https://github.com/bkili/peek-a-boo/blob/main/core/registry.py): `core/registry.py`
- [Global state](https://github.com/bkili/peek-a-boo/blob/main/core/state.py): `core/state.py`
- [Configuration](https://github.com/bkili/peek-a-boo/blob/main/core/config_ops.py): `core/config_ops.py`
- [Rich output](https://github.com/bkili/peek-a-boo/blob/main/core/utils/formatter.py): `core/utils/formatter.py`
- [Catalog listing](https://github.com/bkili/peek-a-boo/blob/main/core/utils/listing.py): `core/utils/listing.py`
- [Module contract](https://github.com/bkili/peek-a-boo/blob/main/modules/base.py): `modules/base.py`
- [Progress display](https://github.com/bkili/peek-a-boo/blob/main/core/utils/progress_bar.py): `core/utils/progress_bar.py`
- [Plugin contract](https://github.com/bkili/peek-a-boo/blob/main/core/base_plugin.py): `core/base_plugin.py`

### Modules and extensions

- [Plugin loading](https://github.com/bkili/peek-a-boo/blob/main/core/plugin.py): `core/plugin.py`
- [Plugins](https://github.com/bkili/peek-a-boo/tree/main/plugins): `plugins`

### Security operations

- [OSINT, recon, privilege checks](https://github.com/bkili/peek-a-boo/tree/main/modules): `modules`
- [Exploit components](https://github.com/bkili/peek-a-boo/tree/main/exploits): `exploits`
- [SSH and SFTP](https://github.com/bkili/peek-a-boo/blob/main/core/utils/ssh_handler.py): `core/utils/ssh_handler.py`
- [CVE reference data](https://github.com/bkili/peek-a-boo/blob/main/core/utils/cve_list.py): `core/utils/cve_list.py`
- [Email lookup runner](https://github.com/bkili/peek-a-boo/blob/main/core/contrib/holehe_async_runner.py): `core/contrib/holehe_async_runner.py`

### Other components

- **Operator**

## Connections

- Operator → Interactive CLI: enters commands (evidence: `README.md`)
- Application startup → Configuration: loads settings (evidence: `main.py`)
- Application startup → Plugin loading: loads plugins (evidence: `main.py`)
- Application startup → Interactive CLI: starts (evidence: `main.py`)
- Application startup → Command registry: registers plugin commands (evidence: `main.py`)
- Interactive CLI → Command registry: dispatches commands (evidence: `core/cli.py`)
- Interactive CLI → Command handlers: imports handlers (evidence: `core/cli.py`)
- Interactive CLI → Command completion: requests completions (evidence: `core/cli.py`)
- Command handlers → Command registry: registers handlers (evidence: `core/commands/module_ops.py`)
- Command handlers → Global state: selects active module (evidence: `core/commands/module_ops.py`)
- Command handlers → OSINT, recon, privilege checks: loads and runs (evidence: `core/commands/module_ops.py`)
- Command handlers → Exploit components: loads selected exploit (evidence: `core/commands/module_ops.py`)
- Command handlers → Plugins: loads selected plugin (evidence: `core/commands/module_ops.py`)
- Command handlers → Module contract: uses module interface (evidence: `README.md`)
- Plugin loading → Plugin contract: instantiates plugins (evidence: `core/plugin.py`)
- Plugin loading → Plugins: loads configured plugins
- OSINT, recon, privilege checks → SSH and SFTP: uses remote access (evidence: `modules/pb_check_kernel_exploits.py`)
- OSINT, recon, privilege checks → CVE reference data: checks CVE data (evidence: `modules/pb_check_sudo_cves.py`)
- OSINT, recon, privilege checks → Email lookup runner: runs email lookup (evidence: `modules/pb_holehe_check_email.py`)
- OSINT, recon, privilege checks → Progress display: displays progress (evidence: `modules/pb_holehe_check_email.py`)
- Command handlers → Configuration: saves and loads (evidence: `core/commands/config_ops.py`)
- Command handlers → Catalog listing: lists available tools (evidence: `core/commands/display.py`)
- Command handlers → Rich output: formats output (evidence: `core/commands/display.py`)
- Command completion → Catalog listing: completes tool names (evidence: `core/completer.py`)
- Interactive CLI → Global state: shares runtime data (evidence: `README.md`)
- Plugins → Plugin contract: implements extension contract (evidence: `README.md`)