# macho25/sps-jokes architecture

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

- Interactive diagram: https://gitdiagram.com/macho25/sps-jokes
- Repository: https://github.com/macho25/sps-jokes

## Overview

sps-jokes is a command-line tool for discovering SSH-accessible hosts and applying GNOME pranks over SSH, with additional reverse-shell deployment and SSH persistence commands. The main workflow is scan or load hosts, select a discovered target, choose and configure a prank, then execute it remotely. The graph separates host discovery, prank orchestration, SSH transport, and reverse-shell operations. README documentation is minimal; prank details are based on partial source excerpts, so uncertain internal wiring is omitted.

Main entry points: [`main.py`](https://github.com/macho25/sps-jokes/blob/main/main.py) (Command interface), [`ssh_connection.py`](https://github.com/macho25/sps-jokes/blob/main/ssh_connection.py) (SSH transport), [`scanner.py`](https://github.com/macho25/sps-jokes/blob/main/scanner.py) (SSH scanner), [`jokes.py`](https://github.com/macho25/sps-jokes/blob/main/jokes.py) (Prank manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["Command interface<br/>[main.py]"]
end

subgraph group_discovery["Host discovery"]
  node_scanner["SSH scanner<br/>[scanner.py]"]
  node_hostmap[("Host mapping<br/>[scanner.py]")]
end

subgraph group_pranks["Prank execution"]
  node_prankmanager["Prank manager<br/>[jokes.py]"]
  node_pranktypes["Prank implementations<br/>[pranks.py]"]
end

subgraph group_remote["Remote access"]
  node_ssh["SSH transport<br/>[ssh_connection.py]"]
  node_shell["Reverse-shell manager<br/>[reverse_shell.py]"]
end

node_operator(("Operator"))
node_nmap["Nmap"]
node_sshhost["SSH hosts"]
node_netcat["Netcat"]

node_operator -->|"enters commands"| node_cli
node_cli -->|"runs scan"| node_scanner
node_scanner -->|"scans subnet"| node_nmap
node_scanner -->|"queries hostname"| node_sshhost
node_scanner -->|"loads or saves"| node_hostmap
node_cli -->|"lists hosts"| node_hostmap
node_cli -->|"selects target or prank"| node_prankmanager
node_prankmanager -->|"resolves target"| node_hostmap
node_prankmanager -->|"configures and runs"| node_pranktypes
node_prankmanager -->|"executes remote commands"| node_ssh
node_pranktypes -->|"transfers files"| node_ssh
node_ssh -->|"executes commands or copies files"| node_sshhost
node_cli -->|"starts listener and deploys"| node_shell
node_shell -->|"deploys or cleans up"| node_ssh
node_shell -->|"checks or listens"| node_netcat
node_cli -->|"enables persistence"| node_ssh

click node_cli "https://github.com/macho25/sps-jokes/blob/main/main.py"
click node_scanner "https://github.com/macho25/sps-jokes/blob/main/scanner.py"
click node_hostmap "https://github.com/macho25/sps-jokes/blob/main/scanner.py"
click node_prankmanager "https://github.com/macho25/sps-jokes/blob/main/jokes.py"
click node_pranktypes "https://github.com/macho25/sps-jokes/blob/main/pranks.py"
click node_ssh "https://github.com/macho25/sps-jokes/blob/main/ssh_connection.py"
click node_shell "https://github.com/macho25/sps-jokes/blob/main/reverse_shell.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_cli toneBlue
class node_scanner,node_hostmap toneAmber
class node_prankmanager,node_pranktypes toneMint
class node_ssh,node_shell toneRose
class node_operator,node_nmap,node_sshhost,node_netcat toneIndigo
```

## Components

### CLI workflow

- [Command interface](https://github.com/macho25/sps-jokes/blob/main/main.py): `main.py`

### Host discovery

- [SSH scanner](https://github.com/macho25/sps-jokes/blob/main/scanner.py): `scanner.py`
- [Host mapping](https://github.com/macho25/sps-jokes/blob/main/scanner.py): `scanner.py`

### Prank execution

- [Prank manager](https://github.com/macho25/sps-jokes/blob/main/jokes.py): `jokes.py`
- [Prank implementations](https://github.com/macho25/sps-jokes/blob/main/pranks.py): `pranks.py`

### Remote access

- [SSH transport](https://github.com/macho25/sps-jokes/blob/main/ssh_connection.py): `ssh_connection.py`
- [Reverse-shell manager](https://github.com/macho25/sps-jokes/blob/main/reverse_shell.py): `reverse_shell.py`

### Other components

- **Operator**
- **Nmap**
- **SSH hosts**
- **Netcat**

## Connections

- Operator → Command interface: enters commands
- Command interface → SSH scanner: runs scan
- SSH scanner → Nmap: scans subnet
- SSH scanner → SSH hosts: queries hostname
- SSH scanner → Host mapping: loads or saves
- Command interface → Host mapping: lists hosts
- Command interface → Prank manager: selects target or prank
- Prank manager → Host mapping: resolves target
- Prank manager → Prank implementations: configures and runs
- Prank manager → SSH transport: executes remote commands
- Prank implementations → SSH transport: transfers files
- SSH transport → SSH hosts: executes commands or copies files
- Command interface → Reverse-shell manager: starts listener and deploys
- Reverse-shell manager → SSH transport: deploys or cleans up
- Reverse-shell manager → Netcat: checks or listens
- Command interface → SSH transport: enables persistence