py_c2

A tiny Python socket-based client/server command channel for local lab / educational use.

Important

Authorized use only. This repo demonstrates a basic remote command channel where the client executes safe built-in commands from the server and returns output.

It is intentionally minimal and not secure (no authentication, no encryption, no hardening). Run only in a controlled environment (e.g., localhost, lab VM network).

✨ What’s in this repo

• py_server_c2.py — simple TCP server that accepts a client and sends operator-entered commands
• py_client.py — simple TCP client that connects and executes received commands
• py_https_banner.py — small helper that fetches an HTTPS banner via TLS + a basic HTTP request

🧭 Architecture (high level)

flowchart LR
  op["Operator\n(terminal)"] -->|"types command"| srv["py_server_c2.py\nTCP server"]
  srv -->|"command"| cli["py_client.py\nTCP client"]
  cli -->|"stdout/stderr"| srv
  srv -->|"prints result"| op

Loading

🚀 Quickstart (lab only)

Prerequisites

• Python 3.x
• Optional shared token via PY_C2_TOKEN

Run the server

# Optional: set a shared token (recommended)
export PY_C2_TOKEN=change-me

python py_server_c2.py --host 127.0.0.1 --port 4444 --token "$PY_C2_TOKEN"

Run the client

In a second terminal:

python py_client.py --server-host 127.0.0.1 --server-port 4444 --token "$PY_C2_TOKEN"

Interaction

Type client-safe commands in the server prompt:

• help
• ping
• time
• sysinfo
• echo <text>
• exit

🧰 HTTPS banner tool

Fetch a simple HTTPS banner for a host/port:

python py_https_banner.py example.com 443

🔐 Security notes

This project is a minimal demo and omits common safety/security controls, including:

• Authentication and authorization
• Transport encryption
• Input validation / command restrictions
• Auditing, logging, and tamper resistance

If you extend this for legitimate internal tooling, consider adding mutual authentication (e.g., mTLS), strict allowlists, and limiting the command surface.

📄 License

See LICENSE.