Noureddine RAMDI / Atlas: containerized multi-layer network scanner and visualizer with Go, FastAPI, and React

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
939 Words
github-stars networking docker go fastapi react visualization

karam-ajaj/atlas

Network scanning tools are often fragmented: heavy CLI utilities for scanning, separate backends to collect data, and distinct frontends to visualize results. Atlas takes a different approach by packaging all these layers in a single Docker container that runs a Go-based scanner, a FastAPI backend, and a React dashboard behind NGINX. This architecture delivers a multi-layered, real-time network discovery and visualization experience focused on both Docker networks and local subnets.

what atlas does: multi-layer network discovery and visualization

Atlas is a comprehensive network infrastructure scanner built as a single Docker container. Under the hood, it uses a Go CLI to perform multi-layered network discovery:

  • ARP and Nmap fast scans for subnet host discovery
  • Docker container introspection to map container networks
  • Deep OS fingerprinting to gather detailed system metadata

The scanning engine tracks devices by their network interfaces, maintaining multiple IPs, MAC addresses, open ports, and OS metadata per device. This granularity helps handle complex environments where devices have multiple network identities.

The backend is a FastAPI server written in Python, handling orchestration, scan scheduling, and serving APIs. A React dashboard provides a real-time visualization of the discovered infrastructure, rendered as network graphs that update dynamically. NGINX acts as a reverse proxy, serving the React UI and proxying API requests to FastAPI.

All of this runs inside a Docker container configured with host networking and access to the Docker socket, enabling deep inspection of the host and Docker networks. Scan intervals are configurable, and authentication is optional but supported via environment variables.

architecture and design tradeoffs: hybrid stack in a single container

Atlas’s architecture is interesting for its hybrid use of Go, Python, and React working together inside one Docker container.

The Go CLI is responsible for the “heavy lifting” of network discovery. Go’s concurrency model and native networking libraries make it a solid choice for fast and efficient scanning. This avoids the overhead of Python for low-level network operations.

FastAPI is chosen for the backend API layer due to its speed, ease of use, and automatic interactive API docs. It orchestrates scans, stores metadata (likely in SQLite given the embedded nature), and exposes APIs for the frontend and external integrations.

The React dashboard is a modern SPA that visualizes the network topology with real-time updates, giving operators an interactive view of their network assets.

NGINX stitches the frontend and backend together inside the container, handling routing and serving static assets.

The tradeoff here is the requirement for privileged Docker container execution: host networking and Docker socket access introduce security considerations. This is necessary for the level of introspection Atlas provides, but it means it must be run carefully in trusted environments.

Another tradeoff is packaging everything in one container. While it simplifies deployment, it means the container image is larger and mixes different runtimes, which could complicate updates or debugging.

The code quality appears solid with a clear separation of concerns: the Go binary is standalone, FastAPI handles business logic, and React manages the UI. Scan intervals are configurable, allowing tuning based on network size and desired freshness.

quick start with docker

Atlas can be deployed easily via Docker with a single command. The container requires host networking, Linux capabilities for raw network access, and the Docker socket mounted for container introspection.

Here is the exact command from the project README:

docker run -d \
  --name atlas \
  --network=host \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e ATLAS_UI_PORT='8884' \
  -e ATLAS_API_PORT='8885' \
  -e ATLAS_ADMIN_USER='admin' \
  -e ATLAS_ADMIN_PASSWORD='change-me' \
  -e ATLAS_AUTH_TTL_SECONDS='86400' \
  -e FASTSCAN_INTERVAL='3600' \
  -e DOCKERSCAN_INTERVAL='3600' \
  -e DEEPSCAN_INTERVAL='7200' \
  -e SCAN_SUBNETS="192.168.1.0/24,10.0.0.0/24" \
  keinstien/atlas:{tag}

Environment variables allow customization of UI and API ports, admin credentials, authentication TTL, and scanning schedules. If SCAN_SUBNETS is unset, Atlas auto-detects the local subnet.

Authentication is optional and disabled by default, but can be enabled by setting ATLAS_ADMIN_PASSWORD.

The UI is accessible at http://localhost:ATLAS_UI_PORT and the API docs at the corresponding API port.

verdict

Atlas is a solid choice if you need a self-contained, network-aware scanner that understands both Docker and traditional subnets. Its hybrid Go/Python/React architecture packaged in a single container simplifies deployment and gives you detailed, multi-layered insights.

The tradeoff is the privileged container requirements—host networking and Docker socket access mean you must trust the container and run it in secure environments.

For network operators and developers who want an integrated scanning and visualization tool without managing multiple components, Atlas strikes a good balance. The code quality and clear separation of roles make it approachable for customization or extension.

If you need a lightweight or agentless scanner without elevated privileges, this might not be the right fit. But if deep Docker network introspection combined with subnet scanning is your use case, Atlas is worth trying out.

→ GitHub Repo: karam-ajaj/atlas ⭐ 1,103 · JavaScript