How greenbone/gsa works
Project type and purpose
• This is a full-client React single-page application (SPA) called Greenbone Security Assistant (GSA).
• It bundles a GMP client library (src/gmp) and a React UI (src/web) that calls a back-end API (gsad) speaking the GMP protocol.
File structure
• Top-level
• .github/workflows → CI/CD pipelines (lint, test, build, container, release)
• .docker/ → local Docker Compose and production Dockerfile
• package.json, vite.config.ts, tsconfig.json → Node/Vite build configuration
• public/ → static assets (index.html, locales, robots.txt, config.js template)
• src/gmp
• GMP client: HTTP layer, XML/JSON transforms, command- & model definitions, settings, i18n support
• src/web
• React app:
– pages/ → route components
– components/ → reusable UI elements
– store/ → Redux state, actions, reducers, selectors
– hooks/, utils/, wizard/ → custom hooks, helper modules
• Tests scattered alongside implementations
• Build output (build/) is a static bundle served by any web server (e.g. gsad, nginx)
Architecture overview
A. Developer & CI environment
– Code in GitHub → triggers GitHub Actions → runs ESLint, Jest/vitest, builds JS, builds Docker image, publishes release/SBOM.
– Local dev:
• Vite development server serves SPA at http://127.0.0.1:8080
• gsad (external) must run with CORS to accept calls from the SPA
– Docker Compose (in .docker/compose.yml) can spin up containers for the SPA and optionally gsad for full integration.
B. Build & release
– npm install + npm run build (Vite) → build/ folder with HTML/CSS/JS/assets
– Production Dockerfile copies build/ into a minimal web-server container
C. Runtime / Production
– Browser loads index.html + JS bundle + CSS + locales + config.js
– React app initializes:
• Loads config.js into GmpSettings
• Sets up Redux store and i18next (translations from public/locales)
• Starts React Router (Routes.jsx)
– User actions dispatch Redux actions → UI components subscribe to store
– GMP library (src/gmp) handles all API calls to apiProtocol + apiServer via HTTP, parses XML/JSON, returns JS objects
– Back-end API (gsad) implements GMP, communicates with Greenbone scan engine
Relationships & data flows
• Developer → commits → GitHub → CI → build/test → container image → registry
• Developer (local) → runs Vite → edits code → HMR reload
• Browser ↔ HTTP(S) ↔ Static server (serves SPA assets)
• Browser ↔ HTTP(S) ↔ gsad API
• React components → dispatch Redux actions → GMP library → HTTP calls → backend → responses → reducers → UI updates
• i18next loads JSON translation files from public/locales
Architectural patterns & design principles
• Flux/Redux for unidirectional data flow
• Module separation:
• src/gmp for protocol abstraction
• src/web for presentation & state
• Component hierarchy: pages at top level, UI components below
• Build vs runtime separation: Vite in dev, static build in prod
• Configuration via external config.js (runtime override) and environment variables in Docker
Including technologies & frameworks
• React, React Router, Redux, i18next
• GMP protocol client (XML/HTTP) in TypeScript/JavaScript
• Vite for bundling, ESLint, Prettier for lint/format
• Docker & Docker Compose for containerization
• GitHub Actions for CI/CD
• Jest & Vitest for testing
Don’t over-complicate
• Break the front end into logical components:
• Static asset serving
• Bootstrapping (config + i18n + store)
• GMP communication layer
• UI layer (pages & components)
• Separately show CI/CD and container orchestration