# n1nj4sec/pupy architecture

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

- Interactive diagram: https://gitdiagram.com/n1nj4sec/pupy
- Repository: https://github.com/n1nj4sec/pupy

## Overview

Pupy is a cross-platform command-and-control and post-exploitation system. Its main workflow runs from an operator using the shell, through server-side session and command handling, across configurable network transports, to an agent that executes remote modules and returns results. Separate branches cover payload generation and in-memory loading, plus the broad platform-specific capabilities documented in the README. The graph reflects documented behavior and sampled excerpts; several internal server-to-agent links are therefore shown only at subsystem level.

Main entry points: [`pupy/agent/__main__.py`](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/__main__.py) (Remote agent), [`pupy/cli/pupygen.py`](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupygen.py) (Payload generation), [`pupy/cli/pupysh.py`](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupysh.py) (Pupy shell), [`pupy/commands`](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/commands) (Shell commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator"]
  node_shell["Pupy shell<br/>[pupysh.py]"]
  node_commands["Shell commands"]
  node_server["C2 server<br/>[PupyServer.py]"]
  node_client_session["Client sessions<br/>[PupyClient.py]"]
end

subgraph group_communications["Communications"]
  node_listener["Network listeners<br/>[servers.py]"]
  node_launchers["Connection launchers"]
  node_transports["Transport stack"]
  node_rpc["RPC channel"]
  node_proxy_service["Proxy service<br/>[main.go]"]
end

subgraph group_agent["Agent runtime"]
  node_agent["Remote agent<br/>[__main__.py]"]
  node_agent_handlers["Agent handlers<br/>[handlers.py]"]
  node_task_manager["Task manager<br/>[manager.py]"]
  node_task_store["Task state<br/>[pstore.py]"]
  node_remote_import["Remote imports"]
end

subgraph group_capabilities["Payloads and modules"]
  node_module_catalog["Remote modules"]
  node_platform_packages["Platform packages"]
  node_payload_generation["Payload generation<br/>[pupygen.py]"]
  node_payload_formats["Payload formats"]
  node_native_loaders["Native loaders<br/>[main_exe.c]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_shell
node_shell -->|"connects to"| node_server
node_shell -->|"invokes"| node_commands
node_commands -->|"issues commands"| node_server
node_server -->|"manages sessions"| node_client_session
node_client_session -->|"uses remote calls"| node_rpc
node_listener -->|"accepts connections"| node_launchers
node_launchers -->|"selects transport"| node_transports
node_transports -->|"carries RPC"| node_rpc
node_proxy_service -.->|"forwards traffic"| node_listener
node_rpc -->|"dispatches requests"| node_agent
node_agent -->|"dispatches events"| node_agent_handlers
node_agent -->|"manages tasks"| node_task_manager
node_task_manager -->|"stores results"| node_task_store
node_agent -->|"loads code"| node_remote_import
node_commands -->|"selects modules"| node_module_catalog
node_module_catalog -->|"uses packages"| node_platform_packages
node_payload_generation -->|"generates formats"| node_payload_formats
node_payload_generation -->|"uses loaders"| node_native_loaders
node_payload_generation -->|"delivers payload"| node_operator

click node_shell "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupysh.py"
click node_commands "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/commands"
click node_server "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/pupylib/PupyServer.py"
click node_client_session "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/pupylib/PupyClient.py"
click node_listener "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/network/lib/servers.py"
click node_launchers "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/launchers"
click node_transports "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/transports"
click node_rpc "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/rpc"
click node_proxy_service "https://github.com/n1nj4sec/pupy/blob/nextgen/services/proxy/main.go"
click node_agent "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/__main__.py"
click node_agent_handlers "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/handlers.py"
click node_task_manager "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/manager.py"
click node_task_store "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/pstore.py"
click node_remote_import "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/agent/memimporter"
click node_module_catalog "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/modules"
click node_platform_packages "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/packages"
click node_payload_generation "https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupygen.py"
click node_payload_formats "https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/pupylib/payloads"
click node_native_loaders "https://github.com/n1nj4sec/pupy/blob/nextgen/client/sources-linux-py3/main_exe.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_shell,node_commands,node_server,node_client_session toneBlue
class node_listener,node_launchers,node_transports,node_rpc,node_proxy_service toneAmber
class node_agent,node_agent_handlers,node_task_manager,node_task_store,node_remote_import toneMint
class node_module_catalog,node_platform_packages,node_payload_generation,node_payload_formats,node_native_loaders toneRose
class node_operator toneIndigo
```

## Components

### Operator

- [Pupy shell](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupysh.py): `pupy/cli/pupysh.py`
- [Shell commands](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/commands): `pupy/commands`
- [C2 server](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/pupylib/PupyServer.py): `pupy/pupylib/PupyServer.py`
- [Client sessions](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/pupylib/PupyClient.py): `pupy/pupylib/PupyClient.py`

### Communications

- [Network listeners](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/network/lib/servers.py): `pupy/network/lib/servers.py`
- [Connection launchers](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/launchers): `pupy/network/lib/launchers`
- [Transport stack](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/transports): `pupy/network/lib/transports`
- [RPC channel](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/network/lib/rpc): `pupy/network/lib/rpc`
- [Proxy service](https://github.com/n1nj4sec/pupy/blob/nextgen/services/proxy/main.go): `services/proxy/main.go`

### Agent runtime

- [Remote agent](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/__main__.py): `pupy/agent/__main__.py`
- [Agent handlers](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/handlers.py): `pupy/agent/handlers.py`
- [Task manager](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/manager.py): `pupy/agent/manager.py`
- [Task state](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/agent/pstore.py): `pupy/agent/pstore.py`
- [Remote imports](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/agent/memimporter): `pupy/agent/memimporter`

### Payloads and modules

- [Remote modules](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/modules): `pupy/modules`
- [Platform packages](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/packages): `pupy/packages`
- [Payload generation](https://github.com/n1nj4sec/pupy/blob/nextgen/pupy/cli/pupygen.py): `pupy/cli/pupygen.py`
- [Payload formats](https://github.com/n1nj4sec/pupy/tree/nextgen/pupy/pupylib/payloads): `pupy/pupylib/payloads`
- [Native loaders](https://github.com/n1nj4sec/pupy/blob/nextgen/client/sources-linux-py3/main_exe.c): `client/sources-linux-py3/main_exe.c`

### Other components

- **Operator**

## Connections

- Operator → Pupy shell: runs
- Pupy shell → C2 server: connects to
- Pupy shell → Shell commands: invokes
- Shell commands → C2 server: issues commands
- C2 server → Client sessions: manages sessions
- Client sessions → RPC channel: uses remote calls
- Network listeners → Connection launchers: accepts connections
- Connection launchers → Transport stack: selects transport
- Transport stack → RPC channel: carries RPC
- Proxy service → Network listeners: forwards traffic
- RPC channel → Remote agent: dispatches requests
- Remote agent → Agent handlers: dispatches events
- Remote agent → Task manager: manages tasks
- Task manager → Task state: stores results
- Remote agent → Remote imports: loads code
- Shell commands → Remote modules: selects modules
- Remote modules → Platform packages: uses packages
- Payload generation → Payload formats: generates formats
- Payload generation → Native loaders: uses loaders
- Payload generation → Operator: delivers payload