# brightio/penelope architecture

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

- Interactive diagram: https://gitdiagram.com/brightio/penelope
- Repository: https://github.com/brightio/penelope

## Overview

##### Project Type and Purpose
- Penelope is a standalone Python-based tool focused on managing and streamlining reverse and bind shell sessions. It simplifies post-exploitation workflows by providing features like PTY auto-upgrade, session logging, file transfers, and integration with external exploits (such as Meterpreter modules).
- The project is essentially a specialized network/terminal handler with modules for managing multiple sessions and shell interactions.

##### File Structure
- The top-level file, penelope.py, is the main entry point.
- The extras directory contains supplementary exploit scripts (e.g., exploit_bind.py, exploit_reverse.py), additional resources (peneloperc), and shell upgrade scripts (tty_upgrade.sh), which serve as auxiliary modules to extend or integrate new behaviors.
- The presence of pyproject.toml indicates the project’s packaging/configuration, but note that the main operations rely solely on Python’s standard library.

##### README for Insights
- The README details the various features such as session management, file server capabilities, and shell upgrade capabilities.
- It explains how Penelope handles both reverse and bind shells, and it emphasizes multi-session handling, logging, and a modular main menu interface.
- There’s also a section on modules – showing a demonstration of features like the Meterpreter module. This highlights that while the core remains simple, extensions and integrations are supported.

a. Main Components:
- Main Entry Point: penelope.py, which orchestrates operations.
- Command Line Interface (CLI): Manages argument parsing, mode selection (listening, connecting, file server mode) and user input handling.
- Session Manager: Oversees session creation, maintenance of multiple shell sessions, automatic PTY upgrades, attachment/detachment of shells, and logging of interactions.
- Network Interface/Listener Module: Listens for incoming connections on specified ports, manages interface binding (like as specified with "-i"), and triggers session logging.
- File Transfer Module: Supports downloading/uploading files and folders (including HTTP file serving when the -s switch is used).
- Exploit/Extras Modules: Located in the extras directory, these include scripts for reverse and bind exploits which might be invoked manually or by import in other Python scripts.
- Logging and Utility Module: Although not explicitly split into a directory or file (all are part of penelope.py), this handles session logging, timestamp insertion, and potentially debugging output.

b. Relationships and Interactions:
- The CLI parses the user’s command line arguments and passes control to the appropriate modules (either to start a listener, connect to a target, serve files, or spawn shells).
- The Network Listener initiates a socket on the designated port and IP address (interface) and funnels new sessions to the Session Manager.
- The Session Manager maintains and logs multiple sessions, initiates PTY upgrades and interacts with file transfer functionalities.
- The Exploit/Extras Modules can be invoked separately (or imported) to establish shell sessions via different methods (bind vs. reverse), thereby interlinking with the core session management.
- A logging utility captures all terminal interactions, which may be represented as a separate data flow component.

c. Architectural Patterns:
- Modularity: While Penelope is a single script, it still demonstrates separation of concerns by isolating session handling, network communications, file transfers, and exploit integrations.
- Command/Strategy Pattern: Based on user-provided command line options, the program dynamically selects and executes features (e.g., auto-upgrading shells, various modes of file transfer).
- Integration Points: The tool is designed to work with external exploit modules (and can be imported) which suggests a plugin-like extensibility model.

d. Relevant Technologies & Frameworks:
- Built-in libraries (socket, subprocess, and logging) may be conceptually displayed as underpinning critical operations.

##### Execution
- It to the CLI component, which then branches off to the different service components (Session Manager, Network Listener, File Transfer, and Extras).
- To show feedback loops where necessary (e.g., Session Manager logging back to the Logging Module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    UT("User Terminal (Input)"):::core
    P("penelope.py"):::core
    Config("Configuration (Packaging)"):::core
    CLI("CLI (Argument Parsing & Mode Selection)"):::core
    NL("Network Listener (Socket Handling & Interface Binding)"):::core
    SM("Session Manager (Multi-Session, PTY Upgrade, Logging)"):::core
    FT("File Transfer Module (HTTP File Serving)"):::core
    LU("Logging Utility"):::core

    subgraph "Extras Modules"
        ER("Exploit Reverse Shell"):::extra
        EB("Exploit Bind Shell"):::extra
        SU("Shell Upgrade Script"):::extra
    end

    %% Connections
    UT -->|"input"| CLI
    P -->|"execute"| CLI
    Config -->|"config read"| P
    CLI -->|"listen/connect"| NL
    CLI -->|"init sessions"| SM
    CLI -->|"serve files"| FT
    CLI -->|"invoke exploits"| ER
    CLI -->|"invoke exploits"| EB
    CLI -->|"invoke upgrade"| SU
    NL -->|"new connection"| SM
    SM -->|"log"| LU
    SM -->|"PTYupgrade"| SU

    %% Styles
    classDef core fill:#DDEEFF,stroke:#333,stroke-width:2px;
    classDef extra fill:#CCE5CC,stroke:#333,stroke-width:2px;

    %% Click Events
    click P "https://github.com/brightio/penelope/blob/main/penelope.py"
    click ER "https://github.com/brightio/penelope/blob/main/extras/exploit_reverse.py"
    click EB "https://github.com/brightio/penelope/blob/main/extras/exploit_bind.py"
    click SU "https://github.com/brightio/penelope/blob/main/extras/tty_upgrade.sh"
    click Config "https://github.com/brightio/penelope/blob/main/pyproject.toml"
```
