🌐 Atlas - Network Infrastructure Visualizer (Go-powered)

February 19, 2026 · View on GitHub

Atlas is a full-stack containerized tool to scan, analyze, and visualize network infrastructure dynamically. Built with Go, FastAPI, NGINX, and a custom React frontend, it provides automated scanning, storage, and rich dashboards for insight into your infrastructure.

🌍 Live Demo

🔗 URL: https://atlasdemo.vnerd.nl/
👤 Username: admin
🔑 Password: change-me

🚀 What It Does

Atlas performs three key functions:

  1. Scans Docker Containers running on the host to extract:

    • IP addresses (supports multiple IPs per container)
    • MAC addresses (supports multiple MACs per container)
    • Open ports
    • Network names
    • OS type (from image metadata)
    • Each network interface is tracked separately

  2. Scans Local & Neighboring Hosts on the subnet to:

    • Detect reachable devices
    • Retrieve OS fingerprints, MACs, and open ports
    • Populate a full map of the infrastructure

  3. Visualizes Data in Real-Time:

    • Serves an interactive HTML dashboard via Nginx
    • Hosts a FastAPI backend for data access and control
    • Uses a React frontend to render dynamic network graphs

🖼️ Screenshots

🖥️ Desktop View

Dashboard - Collapsed Layout

Dashboard - Circular Layout

 		Dashboard - Horizontal Layout

Dashboard - Hierarchical Layout
Hosts Table View

Hosts Table View

 		Logs Panel

Logs Panel

📱 Mobile View

Mobile Dashboard - Collapsed

Dashboard - Collapsed

 		Mobile Dashboard - Horizontal

Dashboard - Horizontal

 		Mobile Hosts Table

Hosts Table

 		Mobile Logs Panel

Logs Panel

💡 Tip: Click on any screenshot to view the full-size image

🚀 Deployment (Docker)

Run Atlas with optional port configuration:

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:

  • ATLAS_UI_PORT – Sets the port for the Atlas UI (Nginx). Default: 8888.
  • ATLAS_API_PORT – Sets the port for the FastAPI backend. Default: 8889.
  • ATLAS_ADMIN_USER – Admin username for login (single user). Default: admin.
  • ATLAS_ADMIN_PASSWORD – Enables UI/API authentication when set (required password for login). Default: disabled.
  • ATLAS_AUTH_TTL_SECONDS – Session lifetime in seconds. Default: 86400 (24h).
  • FASTSCAN_INTERVAL – Interval in seconds between fast scans. Default: 3600 (1 hour).
  • DOCKERSCAN_INTERVAL – Interval in seconds between Docker scans. Default: 3600 (1 hour).
  • DEEPSCAN_INTERVAL – Interval in seconds between deep scans. Default: 7200 (2 hours).
  • SCAN_SUBNETS – Comma-separated list of subnets to scan (e.g., "192.168.1.0/24,10.0.0.0/24"). If not set, Atlas will auto-detect the local subnet. This allows scanning multiple networks including LAN and remote servers.

If not set, defaults are used (UI: 8888, API: 8889, scan intervals as shown above).

Example endpoints:

  • UI: http://localhost:ATLAS_UI_PORT
  • API (from exposed API port): http://localhost:ATLAS_API_PORT/api/docs
  • API (based on nginx conf): http://localhost:ATLAS_UI_PORT/api/docs

🔐 Authentication

Atlas authentication is optional and disabled by default.

  • Enable auth: set ATLAS_ADMIN_PASSWORD (and optionally ATLAS_ADMIN_USER).
  • UI behavior: when auth is enabled, the UI shows a login gate before any data is rendered.
  • API behavior: when auth is enabled, core endpoints (hosts, external, scripts, logs, scheduler, containers) require a token.

Relevant auth endpoints:

  • GET /api/auth/enabled – returns whether auth is enabled
  • POST /api/auth/login – returns a bearer token
  • GET /api/auth/me – validates current token
  • POST /api/auth/logout – invalidates the current token

Scan Scheduling: Atlas automatically runs scans at the configured intervals. You can:

  • Set initial intervals via environment variables (see above)
  • Change intervals dynamically through the Scripts Panel in the UI
  • Manually trigger scans via the UI or API at any time

The scheduler starts automatically when the container starts and runs scans in the background.

⚙️ How it Works

🔹 Backend Architecture

  • Go CLI (atlas)

    • Built using Go 1.22
    • Handles:
      • initdb: Creates SQLite DB with required schema
      • fastscan: Fast host scan using ARP/Nmap
      • dockerscan: Gathers Docker container info from docker inspect
      • deepscan: Enriches data with port scans, OS info, etc.

  • FastAPI Backend

    • Runs on port 8889
    • Serves:
      • /api/hosts – all discovered hosts (regular + Docker)
      • /api/external – external IP and metadata

  • NGINX

    • Serves frontend (React static build) on port 8888
    • Proxies API requests (/api/) to FastAPI (localhost:8889)

📂 Project Structure

Source Code (Host Filesystem)

atlas/
├── config/
│   ├── atlas_go/        # Go source code (main.go, scan, db)
│   ├── bin/             # Compiled Go binary (atlas)
│   ├── db/              # SQLite file created on runtime
│   ├── logs/            # Uvicorn logs
│   ├── nginx/           # default.conf for port 8888
│   └── scripts/         # startup shell scripts
├── data/
│   ├── html/            # Static files served by Nginx
│   └── react-ui/        # Frontend source (React)
├── Dockerfile
├── LICENSE
└── README.md

Inside Container (/config)

/config/
├── bin/atlas             # Go binary entrypoint
├── db/atlas.db           # Persistent SQLite3 DB
├── logs/                 # Logs for FastAPI
├── nginx/default.conf    # Nginx config
└── scripts/atlas_check.sh # Entrypoint shell script

🧪 React Frontend (Dev Instructions)

This is a new React-based UI.

🛠️ Setup and Build

cd /swarm/data/atlas/react-ui
npm install
npm run build

The built output will be in:

/swarm/data/atlas/react-ui/dist/

For development CI/CD (for UI and backend and build a new docker version):

/swarm/github-repos/atlas/deploy.sh

🚀 CI/CD: Build and Publish a New Atlas Docker Image

To deploy a new version and upload it to Docker Hub, use the provided CI/CD script:

  1. Build and publish a new image:

    /swarm/github-repos/atlas/deploy.sh
    • The script will prompt you for a version tag (e.g. v3.2).
    • It will build the React frontend, copy to NGINX, build the Docker image, and push both keinstien/atlas:$VERSION and keinstien/atlas:latest to Docker Hub.

  2. Why push both tags?

    • Version tag: Allows you to pin deployments to a specific release (e.g. keinstien/atlas:v3.2).
    • Latest tag: Users can always pull the most recent stable build via docker pull keinstien/atlas:latest.

  3. The script will also redeploy the running container with the new version.

Example output:

🔄 Tagging Docker image as latest
📤 Pushing Docker image to Docker Hub...
✅ Deployment complete for version: v3.2

Note: Make sure you are logged in to Docker Hub (docker login) before running the script.

🌍 URLs

  • Swagger API docs:

    • 🌍 http://localhost:8888/api/docs (Host Data API endpoint)

  • Frontend UI:

    • 🖥️ UI http://localhost:8888/ (main dashboard)
    • 📊 http://localhost:8888/hosts.html (Hosts Table)
    • 🧪 http://localhost:8888/visuals/vis.js_node_legends.html (legacy test UI)

Default exposed port is: 8888

📡 Scheduler API Endpoints

New scheduler management endpoints:

  • GET /api/scheduler/intervals - Get current scan intervals for all scan types
  • PUT /api/scheduler/intervals/{scan_type} - Update interval for a specific scan type (fastscan, dockerscan, or deepscan)
  • GET /api/scheduler/status - Get scheduler status and current intervals

Example:

# Get current intervals
curl http://localhost:8888/api/scheduler/intervals

# Update fastscan interval to 30 minutes (1800 seconds)
curl -X PUT http://localhost:8888/api/scheduler/intervals/fastscan \
  -H "Content-Type: application/json" \
  -d '{"interval": 1800}'

# Check scheduler status
curl http://localhost:8888/api/scheduler/status

✅ Features

  • Multi-interface scanning - Automatically detects and scans all physical network interfaces on the host
  • Fast network scans (ping/ARP)
  • Multiple subnet scanning - Scan your LAN, remote servers, and multiple networks simultaneously via SCAN_SUBNETS environment variable
  • Docker container inspection with multi-network support
  • Multiple IPs and MACs per container - Containers on multiple networks show all interfaces
  • Interface-aware host tracking - Same host on multiple interfaces appears separately with interface labels
  • External IP discovery
  • Deep port scans with OS enrichment
  • React-based dynamic frontend
  • NGINX + FastAPI routing
  • SQLite persistence
  • Scheduled auto scans with configurable intervals - Configure via environment variables or UI
  • Dynamic interval management - Change scan intervals without restarting the container

📌 Dev Tips

To edit Go logic:

  • Main binary: internal/scan/
  • Commands exposed via: main.go

To edit API:

  • Python FastAPI app: scripts/app.py

To edit UI:

  • Modify React app under /react-ui
  • Rebuild and copy static files to /html
  • automated deplolyment and publish to dockerhub using the script deploy.sh

⚙️ Automation Notes

  • Atlas runs automatically on container start.

  • All Go scan tasks run sequentially:

    • initdb → fastscan → deepscan → dockerscan

  • Scheduled scans are run every 30 minutes via Go timers.

  • No cron dependency required inside the container.

  • Scans can also be manually triggered via the UI using API post request.

👨‍💻 Author

Karam Ajaj
Infrastructure & Automation Engineer
https://github.com/karam-ajaj

📝 License

MIT License — free for personal or commercial use.

📚 Documentation

🤝 Contributing

Suggestions, bug reports, and pull requests are welcome!

Star History

Star History Chart