The Looking-Glass: A Modular Network Analysis Tool

The Looking-Glass is a web-based network analysis tool that provides real-time streaming output for common networking commands like ping and traceroute. It's built as a secure, multi-container application orchestrated with Docker Compose, serving as a powerful example of modern full-stack and DevOps principles.

Features

Real-Time Streaming: Command output is streamed to the user's browser in real-time using WebSockets and Redis Pub/Sub.

Secure by Design: Includes API key authentication and input sanitization to prevent abuse and command injection.

Modular Architecture: Built as a set of interacting microservices, following the Principle of Least Privilege.

Containerized: The entire application stack is defined and managed with Docker Compose for easy, consistent deployment.

Architecture

The application is composed of six distinct services working in concert:

nginx: A lightweight web server that serves the static frontend (HTML, CSS, JS) and acts as a reverse proxy, directing API and WebSocket traffic to the backend.

api-gateway: A FastAPI application that serves as the primary backend. It handles user authentication, manages WebSocket connections, and delegates jobs to the worker via a message queue.

rabbitmq: A robust message broker that decouples the API gateway from the worker. The gateway publishes jobs to a queue, ensuring that tasks are not lost even if the worker is temporarily down.

redis: A high-performance in-memory database used for two purposes:

As a Pub/Sub broker to stream real-time command output.

To store the final results of completed jobs.

worker: An unprivileged Python service that consumes jobs from RabbitMQ. It handles the safe execution of the ping command and delegates traceroute jobs to the specialized net-tools service.

net-tools: A minimalist, privileged Flask microservice. Its only purpose is to run the traceroute command, which requires elevated network permissions (NET_RAW, NET_ADMIN). This isolates dangerous capabilities from the rest of the application, enhancing security.

Prerequisites

Docker: Install Docker

Docker Compose: Install Docker Compose (often included with Docker Desktop)

How to Run

Clone the Repository

git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>

Configure Secrets (Optional)

For local development, the application will use the default secrets in the docker-compose.yml file. For a more secure setup, you can create a .env file in the project root and populate it with your own secrets.

Example .env file:

Code snippet

RABBITMQ_DEFAULT_USER=myuser
RABBITMQ_DEFAULT_PASS=mysupersecretpassword
API_KEY=my-private-api-key-xyz

The docker-compose.yml file is pre-configured to automatically use these variables if the .env file is present.

Build and Run the Application

From the root of the project directory, run the following command:

docker-compose up --build

To run the application in the background, use the -d flag:

docker-compose up --build -d

Access the Application

Open your web browser and navigate to: http://localhost or the IP address of the hosting device

Technical Details & Known Limitations

The traceroute Anomaly on Docker Desktop When running this application using Docker Desktop on macOS or Windows, the traceroute command may only show two hops (the Docker gateway and the final destination). This is not a bug in the application but a known limitation of Docker Desktop's networking layer, which has difficulty routing the specific ICMP error packets that traceroute relies on.

For full, multi-hop traceroute functionality, it is recommended to deploy this application on a native Linux host, such as a DigitalOcean Droplet (VPS) or a Raspberry Pi. On these platforms, the container networking behaves as expected, and the traceroute command will provide complete results.