A Full-Stack Implementation of a Command & Control Architecture
Project Goals • Architecture • Features Implemented • Getting Started
This is an academic portfolio project developed to explore and implement the concepts behind Command & Control (C2) architectures used in cybersecurity and network administration.
The goal was to build a distributed system from scratch, handling real-time communication between a central server and multiple remote agents. It demonstrates full-stack development skills, including backend API design, frontend state management, and cross-platform agent implementation.
- Full-Stack Architecture: Integrating Laravel (Backend) with Vue 3 (Frontend) via Inertia.js.
- Real-Time Communication: Implementing efficient polling mechanisms to track agent status without WebSockets (initially).
- Cross-Platform Development: Creating a Python-based agent that runs on Windows and Linux.
- Security Concepts: Handling basic authentication and command execution in a controlled environment.
- Reactive UI: Built a Single Page Application (SPA) to manage state without page reloads.
- Live Status Tracking: Agents automatically report status (Active, Offline, Lost) based on heartbeat intervals.
- Terminal Interface: A custom-built web terminal to send commands and view output in real-time.
- Internationalization (i18n): Full support for English and Spanish to demonstrate localization skills.
- RESTful API: Endpoints for agent registration, heartbeats, and command retrieval.
- Queue System: Commands are queued and picked up by agents asynchronously.
- Database Design: Normalized schema to track agents, commands, and outputs efficiently.
- Lightweight Client: A standalone Python script acting as the "implant".
- System Interaction: Executes shell commands and returns stdout/stderr to the server.
- Resilience: Auto-reconnection logic and error handling.
The project follows a standard client-server model:
- Agent (Python): Periodically polls the server for new commands (Beaconing).
- Server (Laravel): Queues commands and stores results in a database (MySQL/PostgreSQL).
- Frontend (Vue): Polls the internal API to update the UI with the latest agent status and command outputs.
- Backend: Laravel 12.x (PHP 8.2+)
- Frontend: Vue 3 (Composition API) + Inertia.js
- Styling: Tailwind CSS
- Database: MySQL / PostgreSQL
- Agent: Python 3.7+ (Requests lib)
Project Structure:
cmd-ctl/
├── agent/ # Python client (The "Bot")
│ ├── c2_agent.py # Main execution loop
│ └── config.py # Configuration logic
│
└── backend/ # C2 Server
├── app/Http/Controllers # API & Web Controllers
├── resources/js # Vue Pages & Components
└── routes/ # API & Web Routes
To run this project locally for testing or evaluation:
- PHP >= 8.2 & Composer
- Node.js >= 18.x & NPM
- Python >= 3.7
- Database (MySQL or SQLite)
git clone <repository-url>
cd cmd-ctl/backend
# Install dependencies
composer install
npm install
# Setup environment
cp .env.example .env
php artisan key:generate
# (Configure your DB in .env)
# Run migrations (create tables)
php artisan migrate
# Start Development Server
npm run dev # Terminal 1 (Vite)
php artisan serve # Terminal 2 (Laravel)Open a new terminal to simulate a remote computer:
cd ../agent
pip install -r requirements.txt
# Start the agent (points to localhost by default)
python c2_agent.pyVisit http://localhost:8000 to see the agent pop up in the dashboard!
Since this is a learning project, there are several areas I plan to improve:
- WebSockets: Replace polling with Pusher/Reverb for true real-time events.
- Encryption: Implement E2E encryption for command payloads.
- File Transfer: Add ability to upload/download files to agents.
This tool is for educational purposes only. It is designed to demonstrate programming concepts and system architecture. It effectively acts as a remote administration tool (RAT) and should never be used on systems without explicit permission.
Developed by Gerijacki