atlas

🌐 Atlas - Network Infrastructure Visualizer (Go-powered)

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 - Circular Layout	Dashboard - Hierarchical Layout
Hosts Table View	Logs Panel

📱 Mobile View

Dashboard - Collapsed

Dashboard - Horizontal

Hosts Table

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

• Multi-Interface Support - Detailed guide on the multi-interface scanning feature
• Migration Guide - Guide for migrating from bash scripts to Go implementation

🤝 Contributing

Suggestions, bug reports, and pull requests are welcome!

Star History