AGH2 Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• charts/agh2/templates/captain/captain-deployment.yml
• charts/agh2/templates/core/core-deployment.yml
• charts/agh2/templates/exploit-manager/exploitmgr-deployment.yml
• charts/agh2/templates/ui/ui-deployment.yml
• charts/agh2/values.yaml
• charts/agh2/Chart.yaml
• charts/agh2/templates/db/postgres-init-configmap.yml

AGH2 is a multi-component application deployed via a Helm chart. Its architecture is based on a microservices pattern, comprising several distinct services that communicate with each other and with shared data stores. The core components include a user interface (UI), a central management service (Captain), a core logic service (Core), and an exploit manager (ExploitMgr).

The system relies on several stateful dependencies for data persistence and caching, including PostgreSQL, Minio, and Redis. The Helm chart provides the flexibility to deploy these dependencies internally as part of the release or to connect to external instances. Configuration and secrets are managed through Kubernetes secrets, with values templated by the Helm chart.

Core Components

The AGH2 application is divided into four main services, each running in its own Kubernetes Deployment.

This diagram shows the high-level interaction between the core AGH2 components and the main system dependencies.

Captain

The Captain service acts as the central management and API gateway for the system. It handles incoming requests from the UI and coordinates with other backend services like Core and Exploit Manager.

• Image: leukocyte-lab/argushack2/captain
• Port: 9527
• Responsibilities:
  • Authenticates and manages users (Superadmin password, JWT secret).
  • Communicates with Core and Exploit Manager services via gRPC.
  • Connects to PostgreSQL, Redis, and Minio for its data needs.
  • Retrieves Keygen credentials for licensing or asset fetching.

The Captain deployment includes an init container to wait for the PostgreSQL database to be ready before starting.
Sources: charts/agh2/templates/captain/captain-deployment.yml, charts/agh2/values.yaml:379-438

Core

The Core service appears to handle fundamental business logic for the application.

• Image: leukocyte-lab/argushack2/core
• Responsibilities:
  • Connects to its own PostgreSQL database (core-db).
  • Utilizes Redis for caching or messaging.
  • Interacts with Minio for object storage.
  • Configured with a REGISTRY_URL, suggesting it may interact with a Docker registry.

Sources: charts/agh2/templates/core/core-deployment.yml, charts/agh2/values.yaml:441-499

Exploit Manager (exploitmgr)

This service is responsible for managing exploits within the AGH2 platform.

• Image: leukocyte-lab/argushack2/exploitmgr
• Responsibilities:
  • Connects to its own PostgreSQL database (exploitmgr-db).
  • Uses Redis.

Sources: charts/agh2/templates/exploit-manager/exploitmgr-deployment.yml, charts/agh2/values.yaml:503-541

UI

The UI service provides the web-based frontend for users to interact with the AGH2 platform.

• Image: leukocyte-lab/argushack2/frontend
• Responsibilities:
  • Serves the static assets for the user interface.
  • Communicates with the Captain service's API.

Sources: charts/agh2/templates/ui/ui-deployment.yml, charts/agh2/values.yaml:545-561

System Dependencies

AGH2 relies on several external services for its operation. The Helm chart can deploy these dependencies or be configured to use existing external services.

Sources: charts/agh2/Chart.yaml:26-35, charts/agh2/values.yaml:100-103, 218-221, 368-371

Dependency	Purpose	Internal Chart
PostgreSQL	Primary data store for all core components.	bitnami/postgresql
Minio	S3-compatible object storage.	bitnami/minio
Redis	In-memory data store, likely used for caching and/or as a message broker.	Deployed as a standalone container, not a sub-chart.

Database Initialization

When using the internal PostgreSQL database, a ConfigMap named db-init-scripts is created to run initialization scripts. This process is handled by a Kubernetes Job triggered on Helm install.

The flowchart below illustrates the database initialization process.

This initialization script performs the following actions:

1. Downloads Attack Datasets (Optional): If db.helpers.init.attack.enabled is true, it uses a keygen API token to download and prepare an attack.sql file.
2. Creates Roles and Databases: If db.helpers.init.dbs.enabled is true, it generates an init.sql script that:
   • Creates PostgreSQL roles for each AGH2 service (agh-captain, agh-core, agh-exploit).
   • Creates a dedicated database for each service (captain-db, core-db, exploitmgr-db).
   • Optionally creates the pgroonga extension in each new database for full-text search capabilities.
3. Executes Scripts: The final step runs the generated SQL scripts against the PostgreSQL instance.

Sources: charts/agh2/templates/db/postgres-init-configmap.yml

Configuration and Secrets

Secrets and configuration are managed through values.yaml and injected into pods as environment variables or files.

Component Secrets

Each core component has its own set of secrets for database and Minio connections. These are generated by the chart if secret.enabled is true for that component.

Component	Secret Type	values.yaml Path
Captain	DB Connection	captain.secret.db
	Minio User	captain.secret.minio
	JWT Secret	captain.secret.jwt
	Superadmin Password	captain.secret.superadmin
Core	DB Connection	core.secret.db
	Minio User	core.secret.minio
ExploitMgr	DB Connection	exploitmgr.secret.db

Sources: charts/agh2/values.yaml:394-432, 459-487, 521-535

Shared Configuration

A ConfigMap named system-image is created to hold references to shared Docker images used by various parts of the system, such as workers and report generators. The Captain service mounts this ConfigMap to access these image tags.

Sources: charts/agh2/values.yaml:565-581, charts/agh2/templates/captain/captain-deployment.yml:51-53

Keygen

The system uses Keygen to fetch artifacts. The Keygen Account ID and API Token are configured and stored in a Kubernetes secret. This is used during database initialization to download attack datasets.

Sources: charts/agh2/values.yaml:49-62, charts/agh2/templates/db/postgres-init-configmap.yml:11-13

Networking and Service Communication

Internal communication between services is handled via standard Kubernetes service DNS names.

• The Captain deployment is configured with environment variables pointing to the core and exploitmgr services:
  • CORE_URL: core.$(NAMESPACE).svc.cluster.local:50005
  • EXPMGR_URL: exploitmgr.$(NAMESPACE).svc.cluster.local:50005
• All services that require Redis connect to redis.$(NAMESPACE).svc.cluster.local:6379.

External access is managed via a Kubernetes Ingress resource, which can be enabled through ingress.enabled. If enabled, it routes traffic for the configured ingress.host to the captain service on port 9527. TLS can also be configured for the Ingress host.

Sources: charts/agh2/templates/captain/captain-deployment.yml:62-68, charts/agh2/values.yaml:65-68