How n1nj4sec/pupy works
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: __main__.py Remote agent · pupygen.py Payload generation · pupysh.py Pupy shell · commands Shell commands
Components 20
Operator
- Pupy shell
pupy/cli/pupysh.py - Shell commands
pupy/commands - C2 server
pupy/pupylib/PupyServer.py - Client sessions
pupy/pupylib/PupyClient.py
Communications
- Network listeners
pupy/network/lib/servers.py - Connection launchers
pupy/network/lib/launchers - Transport stack
pupy/network/lib/transports - RPC channel
pupy/network/lib/rpc - Proxy service
services/proxy/main.go
Agent runtime
- Remote agent
pupy/agent/__main__.py - Agent handlers
pupy/agent/handlers.py - Task manager
pupy/agent/manager.py - Task state
pupy/agent/pstore.py - Remote imports
pupy/agent/memimporter
Payloads and modules
- Remote modules
pupy/modules - Platform packages
pupy/packages - Payload generation
pupy/cli/pupygen.py - Payload formats
pupy/pupylib/payloads - Native loaders
client/sources-linux-py3/main_exe.c
Other components
- Operator
Connections 20
- 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