AGH2 Component: Captain

Relevant source files

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

• charts/agh2/templates/captain/captain-deployment.yml
• charts/agh3/templates/captain/captain-deployment.yml
• charts/agh2/values.yaml
• charts/agh3/values.yaml
• charts/agh2/templates/captain/captain-service.yml
• charts/agh3/templates/captain/captain-service.yml
• charts/agh2/README.md
• charts/agh3/README.md
• charts/agh2/templates/captain/captain-db-secret.yml
• charts/agh3/templates/captain/captain-db-secret.yml
• charts/agh2/templates/captain/captain-superadmin-secret.yml
• charts/agh3/templates/captain/captain-clusterrole.yml
• charts/agh2/templates/db/postgres-init-configmap.yml

The Captain module is a central backend service within the ArgusHack (AGH) platform, present in both AGH2 and AGH3 versions. It functions as a core orchestrator, managing various resources and interacting with multiple backend services. Its responsibilities are configured through a rich set of environment variables and it relies on several external dependencies, including a PostgreSQL database for persistence, Redis for caching, and Minio for object storage.

In the AGH2 architecture, Captain communicates with other key modules like core and exploitmgr. The AGH3 version of Captain expands on this, introducing integrations with RabbitMQ for message queuing, optional OIDC for authentication, and enhanced observability features. This document details the architecture, configuration, and deployment of the Captain component as defined by the Helm charts.

Architecture and Dependencies

The Captain component is designed as a Kubernetes Deployment that relies on several other services to function correctly. The pod specification includes init containers to ensure that critical dependencies like PostgreSQL and Redis are available before the main Captain application starts.

The following diagram illustrates the primary dependencies of the Captain service in both AGH2 and AGH3.

This diagram shows the dependencies for Captain in AGH2 and its expanded dependencies in AGH3.
Sources: charts/agh2/templates/captain/captain-deployment.yml:10-29,49-105, charts/agh3/templates/captain/captain-deployment.yml:10-73,103-200

Startup Sequence

To ensure system stability, the Captain pod uses init containers to check for the availability of its dependencies before launching the main application container.

The startup sequence is as follows:

1. AGH2 & AGH3: An init container waits for the Redis service to become available by pinging it.
2. AGH3 Only: An init container waits for the Minio service to be accessible.
3. AGH3 Only: An init container waits for the RabbitMQ service to be healthy.
4. AGH2 & AGH3: An init container waits for the PostgreSQL database to be ready by running pg_isready.
5. Once all init containers complete successfully, the main captain container is started.

Sources: charts/agh2/templates/captain/captain-deployment.yml:15-38, charts/agh3/templates/captain/captain-deployment.yml:15-73

Configuration

The Captain module is configured via the captain section in the values.yaml file of the Helm chart. These values control everything from the container image used to the generation of secrets and connection details for its dependencies.

AGH2 Captain Configuration Parameters

The table below summarizes the key configuration options available for the Captain module in the agh2/values.yaml file.

Parameter	Description	Default Value
captain.enabled	Enable or disable the Captain module.	true
captain.image.repository	The container image repository for Captain.	leukocyte-lab/argushack2/captain
captain.image.tag	The container image tag.	v0.26.0
captain.secret.db.enabled	Enable secret generation for the database.	true
captain.secret.db.name	The name of the Captain database.	captain-db
captain.secret.db.user	The database user for Captain.	agh-captain
captain.secret.minio.enabled	Enable secret generation for Minio.	true
captain.secret.minio.user	The Minio user for Captain.	capt-minio-user
captain.secret.jwt.enabled	Enable secret generation for JWT.	true
captain.secret.jwt.secretName	The name of the Kubernetes secret for JWT.	capt-jwt-secret
captain.secret.superadmin.enabled	Enable secret generation for the superadmin user.	true
captain.secret.superadmin.secretName	The name of the Kubernetes secret for the superadmin password.	capt-superadmin-password
captain.service.redis.enabled	Enable Redis as a service dependency.	true
captain.extraEnv	A map of additional environment variables to inject.	{}

Sources: charts/agh2/values.yaml:263-332, charts/agh2/README.md:210-244

Environment Variables

The Captain container is configured at runtime using environment variables. These are populated from values.yaml, ConfigMaps, and Secrets.

AGH2 Environment Variables

Variable	Description	Source
NAMESPACE	The Kubernetes namespace the pod is running in.	fieldRef: metadata.namespace
ENV_REDIS_CONN	The connection string for Redis.	Constructed value
CORE_URL	The internal service URL for the AGH2 Core module.	Constructed value
EXPMGR_URL	The internal service URL for the AGH2 Exploit-Manager.	Constructed value
SUPERADMIN_PASSWORD	The password for the superadmin account.	secretKeyRef: capt-superadmin-secret
DB_Conn	The connection string for the PostgreSQL database.	secretKeyRef: capt-db-secret
Addr	The address and port the service listens on.	:9527
SECRET_JWT	The secret key for signing JWTs.	secretKeyRef: capt-jwt-secret
KEYGEN_ACCOUNT_ID	The Keygen account ID for licensing.	secretKeyRef: keygen-secret
KEYGEN_API_TOKEN	The Keygen API token for licensing.	secretKeyRef: keygen-secret
MINIO_URL	The URL for the Minio service.	secretKeyRef: minio-secret
MINIO_USER	The username for Minio access.	secretKeyRef: capt-minio-secret
MINIO_PASSWORD	The password for Minio access.	secretKeyRef: capt-minio-secret
AGH_APP_VERSION	The application version from the Chart.	.Chart.AppVersion

Sources: charts/agh2/templates/captain/captain-deployment.yml:51-105

Networking

The Captain service is exposed within the Kubernetes cluster via a Service resource. This allows other components in the same namespace to communicate with it using a stable DNS name (captain).

AGH2 Service

• Port: 9527
• Target Port: http (which maps to container port 9527)

Sources: charts/agh2/templates/captain/captain-service.yml:1-11

AGH3 Service

• Port: 8080
• Target Port: http (which maps to container port 8080)

Sources: charts/agh3/templates/captain/captain-service.yml:1-11

In AGH3, the Captain deployment also includes a liveness probe that checks the /api/healthz endpoint on port 8080 to ensure the application is healthy.

Sources: charts/agh3/templates/captain/captain-deployment.yml:202-208

Security and Secrets

Security for the Captain module is managed through Kubernetes Secrets and Role-Based Access Control (RBAC). Secrets are used to store sensitive information like passwords and API tokens, which are then injected into the Captain pod as environment variables.

The following diagram shows how secrets are generated and consumed by the Captain deployment.

This diagram shows the flow of configuration from values.yaml to Kubernetes Secrets and finally into the Captain container as environment variables.
Sources: charts/agh2/templates/captain/captain-db-secret.yml, charts/agh2/templates/captain/captain-superadmin-secret.yml, charts/agh2/templates/captain/captain-deployment.yml:68-74, 80-86

Database Initialization

In AGH2, the postgres-init-configmap.yml is responsible for creating the necessary databases and roles during the initialization of the internal PostgreSQL instance. It creates the captain-db database and the agh-captain role, assigning ownership to that role.

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

RBAC (AGH3)

In the AGH3 chart, a ClusterRole is created for Captain if RBAC is enabled. This role grants Captain extensive permissions to manage various Kubernetes resources across the cluster, including:

• Custom Resources: Full control over agh.lkc-lab.com/actions.
• Core Resources: Read access to pods, pods/log, and pods/status. Full control over secrets.
• Batch Resources: Full control over jobs.
• Apps Resources: Read access to deployments.

These permissions indicate that the AGH3 Captain has a much broader scope, acting as a controller for custom actions and other Kubernetes objects.

Sources: charts/agh3/templates/captain/captain-clusterrole.yml:1-70

Comparison: AGH2 vs AGH3 Captain

The Captain module evolved significantly between AGH2 and AGH3, adding new features, dependencies, and operational improvements.

Feature	AGH2	AGH3
Container Port	9527	8080
Dependencies	PostgreSQL, Redis, Minio, Core, ExploitMgr	PostgreSQL, Redis, Minio, RabbitMQ
Init Containers	redis, postgresql	redis, minio, rabbitmq, postgresql
Health Probes	None	Liveness probe on /api/healthz
Observability	None	Optional Vector sidecar for logging
Authentication	Superadmin password	Superadmin password, optional OIDC integration
RBAC	No dedicated ClusterRole	Dedicated ClusterRole for managing K8s resources
Service Acct	Default	Dedicated ServiceAccount (captain-sa)
Configuration	ENV_REDIS_CONN	REDIS_URL, REDIS_PASSWORD

Sources: charts/agh2/templates/captain/captain-deployment.yml, charts/agh3/templates/captain/captain-deployment.yml, charts/agh3/values.yaml:533-540