SkillAgentSearch skills...

Atlas

Open-source tool for network discovery, visualization, and monitoring. Built with Go, FastAPI, and React, supports Docker host scanning.

GenerateConvertImprove

Install / Use

/learn @karam-ajaj/Atlas
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

🌐 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

<table> <tr> <td width="50%"> <a href="screenshots/dashboard_big_c.png" target="_blank"> <img src="screenshots/dashboard_big_c.png" alt="Dashboard - Collapsed Layout" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" /> <p align="center"><em>Dashboard - Circular Layout</em></p> </a> </td> <td width="50%"> <a href="screenshots/dashboard_big_h.png" target="_blank"> <img src="screenshots/dashboard_big_h.png" alt="Dashboard - Horizontal Layout" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" /> <p align="center"><em>Dashboard - Hierarchical Layout</em></p> </a> </td> </tr> <tr> <td width="50%"> <a href="screenshots/table_big.png" target="_blank"> <img src="screenshots/table_big.png" alt="Hosts Table View" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" /> <p align="center"><em>Hosts Table View</em></p> </a> </td> <td width="50%"> <a href="screenshots/logs_big.png" target="_blank"> <img src="screenshots/logs_big.png" alt="Logs Panel" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" /> <p align="center"><em>Logs Panel</em></p> </a> </td> </tr> </table>

📱 Mobile View

<table> <tr> <td width="25%" align="center"> <a href="screenshots/dashboard_small_c.png" target="_blank"> <img src="screenshots/dashboard_small_c.png" alt="Mobile Dashboard - Collapsed" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); max-width: 250px;" /> <p align="center"><em>Dashboard - Collapsed</em></p> </a> </td> <td width="25%" align="center"> <a href="screenshots/dashboard_small_h.png" target="_blank"> <img src="screenshots/dashboard_small_h.png" alt="Mobile Dashboard - Horizontal" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); max-width: 250px;" /> <p align="center"><em>Dashboard - Horizontal</em></p> </a> </td> <td width="25%" align="center"> <a href="screenshots/table_small.png" target="_blank"> <img src="screenshots/table_small.png" alt="Mobile Hosts Table" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); max-width: 250px;" /> <p align="center"><em>Hosts Table</em></p> </a> </td> <td width="25%" align="center"> <a href="screenshots/logs_small.png" target="_blank"> <img src="screenshots/logs_small.png" alt="Mobile Logs Panel" style="border: 2px solid #ddd; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); max-width: 250px;" /> <p align="center"><em>Logs Panel</em></p> </a> </td> </tr> </table>

💡 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://

karam-ajaj

View profile

View on GitHub
GitHub Stars1.0k
CategoryDevelopment
Updated1d ago
Forks40
karam-ajaj/atlas

Languages

JavaScript

Security Score

100/100

Audited on Mar 21, 2026

No findings