atlas1

Technical Briefing – atlas1 Clone: git clone https://github.com/moses-y/atlas1

The Problem

Atlas addresses the need for a lightweight, containerised tool that can discover, scan, and visualise heterogeneous network infrastructure—Docker containers, local subnets, and remote hosts—through a single dashboard. Organisations that must audit or map dynamic environments often lack a unified view that combines low‑level host data with a reactive UI.

What This Does

Atlas is a full‑stack application composed of three layers:

Go backend (config/atlas_go/main.go, config/atlas_go/internal/scan/) performs Docker‑host scanning, extracting IP/MAC addresses, open ports, OS fingerprints, and network interface details. Scanning logic lives in docker_scan.go, fastscan.go, and deep_scan.go, which iterate container interfaces and emit structured data written to a SQLite database via config/scripts/app.py.
Python FastAPI backend (config/scripts/app.py) exposes REST endpoints, handles CORS, database writes, and scheduler logic. It currently uses a wildcard CORS origin (allow_origins=["*"]) with credentials enabled, and builds SQL queries through string interpolation (config/scripts/app.py).
React frontend (data/react-ui/src/) consumes the API through hooks (useNetworkStats.js, useScanStatus.js, etc.) and renders a network graph via NetworkMap.jsx, a hosts table (HostsTable.jsx), and various modal/components. The entry point is data/react-ui/src/App.jsx, which imports 11 other modules, giving it an instability of 0.92.

The import graph contains 26 internal modules and 23 edges with no circular dependencies; 35 of 35 code files were analysed (Go 7, Python 2, Shell 2, JavaScript 24).

How It Is Wired

Entry point – config/atlas_go/main.go starts the Go HTTP server and triggers the scan scheduler.
Scan execution – config/atlas_go/internal/scan/docker_scan.go lists running containers; fastscan.go and deep_scan.go enrich the data (port scan, OS detection). Results are persisted by config/scripts/app.py (db_setup.go → SQLite).
API exposure – config/scripts/app.py FastAPI app (app.py) listens on 0.0.0.0:8000; endpoints /scan, /hosts, /logs return JSON that the React hooks poll.
Frontend consumption – data/react-ui/src/hooks/useNetworkStats.js fetches /hosts, maps the data to the NetworkMap component, and updates state via SelectionContext.jsx.
Side effects – The Go process writes to data/html/build-info.json; the Python script writes to the SQLite DB under config/atlas_go/internal/db/. No external message queue or caching layer is present.

How To Use It

Step	Command / Action	Evidence
Clone	`git clone https://github.com/moses-y/atlas1`	Verbatim URL
Build Docker image	`docker build -t atlas .`	`Dockerfile` at repo root
Run container	`docker run -d -p 80:80 -p 8000:8000 atlas`	Exposes UI on `:80` and API on `:8000`
Initial configuration	The app loads `data/react-ui/.env` (currently tracked – see security note). Copy `data/react-ui/.env.example` (if present) and set `VITE_API_URL=http://localhost:8000`.	`.env` file; `.gitignore` excludes it but it remains committed
First scan	Trigger via UI “Start Scan” button or `curl http://localhost:8000/scan`	`config/scripts/app.py` endpoint

Note: The tracked .env contains live credentials; see the Code Health & Issues section for remediation.

Real‑World Use

A DevOps lead wants a real‑time map of all Docker containers and local subnet devices after a cloud‑burst event. They launch the container, navigate to http://<host>/, and click Start Scan. The Go scanner discovers 27 containers, records each interface’s IP, MAC, and open ports, and the React dashboard instantly displays a force‑directed graph. The lead can filter by OS, export the host table, and receive logs through the UI—all without leaving the browser.

Code Health & Issues

Measured analysis (static, 11 findings):

2 HIGH: deep nesting (max indent 8) in data/react-ui/src/components/HostsTable.jsx, config/atlas_go/internal/scan/docker_scan.go, data/react-ui/src/components/ScriptsPanel.jsx; high branching density (51 branches over 152 lines) in data/react-ui/src/api.js, data/react-ui/src/hooks/useNetworkStats.js, data/react-ui/src/theme/themeUtils.js.
9 MEDIUM: duplicated 6‑line blocks in config/atlas_go/internal/scan/deep_scan.go, config/atlas_go/internal/scan/fastscan.go, data/react-ui/src/App.jsx, data/react-ui/src/components/MobileHeader.jsx.
0 LOW.

Code‑health audit (14 findings, ranked):

HIGH – Untrack the file your .gitignore says to ignore: data/react-ui/.env (tracked though excluded).
HIGH – Pin third‑party GitHub Actions to commit SHAs: .github/workflows uses @v3 tags for docker/setup-qemu-action, docker/setup-buildx-action, docker/login-action, docker/metadata-action.
HIGH – Add a test suite; repository has 33 source files, no test files.
HIGH – Remove the committed .env and rotate its credentials: data/react-ui/.env.
HIGH – Replace wildcard CORS origin with explicit allow list: config/scripts/app.py (allow_origins=["*"] with credentials enabled).
HIGH – Use bound parameters instead of building SQL strings: config/scripts/app.py interpolated query.
MEDIUM – Enable Dependabot or Renovate: 2 manifests, no update bot configured.
MEDIUM – Pin container base image by digest: Dockerfile uses golang:1.25.3, python:3.11-slim.
MEDIUM – Gate pull requests on a dependency vulnerability scan: no dependency scan in CI.
MEDIUM – Add a pre‑commit secret gate: a secret‑shaped file is tracked, no repo‑level gate visible.
LOW – (4 additional findings) – see full audit for details.

The Bottom Line

Atlas provides a functional, containerised network‑visualisation stack with a Go scanner and a React UI, but it carries several high‑severity maintenance and security debts: a committed .env with live keys, unbounded CORS, SQL‑injection‑prone query building, and untagged Docker base images. The codebase also suffers from deep nesting and duplicated logic that raise cognitive load for contributors. It is suitable for internal or lab environments where the above risks can be mitigated, but production deployment should address the highlighted issues first.