octelium - Moses Yebei

Abstract

A next-gen FOSS self-hosted unified zero trust secure access platform that can operate as a remote access VPN, a ZTNA platform, API/AI/MCP gateway, a PaaS, an ngrok-alternative and a homelab infrastructure.

The Problem

Enterprises that need a self‑hosted, zero‑trust gateway often stitch together separate VPN, API‑gateway, and PaaS components. That creates divergent configs, multiple credential stores, and a larger attack surface. Octelium aims to collapse those pieces into a single, extensible platform that can be run on‑prem or in a cloud VM.

What This Does

Octelium ships six loosely coupled sub‑projects:

cluster – the full control‑plane (auth server, portal, data‑plane gateways) – 707 files.
client – CLI tools (octelium, octeliumctl) and the “connect” server implementation – 230 files.
apis – protobuf‑generated gRPC stubs and type definitions – 28 files.
pkg, octelium‑go, unsorted – shared utilities and a single example script.

The CLI (client/octelium/main.go) parses sub‑commands and ultimately launches a tunnel server (client/octelium/commands/connect/controller/esshmain/server.go). The control‑plane exposes gRPC services defined in apis/main/*.pb.go (e.g. authv1.pb.go, corev1.pb.go) and uses the same protobufs for client‑side stubs.

How It Is Wired

Execution start – client/octelium/main.go:31 (func main). It creates a root command, loads config, then calls Execute.

Key flow – Execute → connect → Run (see client/octelium/commands/connect/controller/esshmain/server.go:104). Run reaches ~400 internal functions and performs three external actions:

Subprocess – doCmd → cmd.Run starts the WireGuard/QUIC tunnel binary.
Database – client/common/authc/authc.go → NewClient builds a Redis client (redis.NewClient).
Crypto/Secrets – kubeInformerFactory.Core().V1().Secrets watches Kubernetes secret objects for TLS material.

The most widely referenced internal helpers are:

CoreC (called from 216 places) – central configuration loader.
Cleanup (211 calls) – deferred resource release.
Initialize (210 calls) – bootstraps logging, metrics, and global state.

These three have the largest blast radius; any change propagates through >200 call sites. The import graph shows no circular dependencies, but several UI router packages (cluster/authserver/.../router) have instability = 1, meaning they import many others without being imported themselves – a potential hot‑spot for future refactor.

Side‑effects – 67 functions read/write files, 2 make outbound network calls, 7 exec external commands, 13 perform cryptographic ops, and 14 touch a Redis store. The shortest documented outbound path is:

main → Execute → connect → Run → NewClient → redis.NewClient

How To Use It

# Clone the repo
git clone https://github.com/moses-y/octelium
cd octelium

# Build the CLI container (Dockerfile in client/octelium)
docker build -t octelium-cli -f client/octelium/Dockerfile .

# Or build locally with the Makefile (default target builds all binaries)
make          # uses go modules in client/*/go.mod

# Create a runtime config – copy the example and fill values
cp cluster/authserver/authserver/web/package/.env.example \
   cluster/authserver/authserver/web/package/.env.development
# (rotate any secrets after copying)

# Start a control‑plane component, e.g. the auth server
docker run -d --name auth \
  -v $(pwd)/cluster/authserver/authserver/web/package/.env.development:/app/.env \
  octelium-authimage   # image name defined in the Dockerfile

# Launch the client tunnel
./bin/octelium connect --profile mycluster

If you prefer the native binaries, the entry points are:

client/octelium/main.go – CLI driver.
client/octeliumctl/main.go – admin utilities.

Both are compiled by the Makefile targets octelium and octeliumctl.

Real‑World Use

A SaaS provider can deploy the authserver and portal pods in a private VPC, expose octeliumctl to ops, and give developers a single octelium connect command. The tunnel terminates on the client, authenticates via the gRPC Authenticate service (apis/main/authv1/authv1_grpc.pb.go), and forwards L7 requests to internal services without ever exposing raw IPs.

Code Health & Issues

High – tracked .env files – cluster/authserver/authserver/web/package/.env.development (and two similar files) are committed despite .gitignore. Remove with git rm --cached and rotate credentials.
High – unpinned GitHub Actions – workflow files reference actions by tag (@v4). Replace with commit SHA to avoid supply‑chain drift.
High – committed secrets – same .env files contain live keys; treat as a breach and rotate.
Medium – no Dependabot – 26 manifest files lack automated updates. Add .github/dependabot.yml.
Medium – base images not pinned – Dockerfiles use golang:1.26.5 and alpine:3.23 tags; switch to digests.
Medium – no vulnerability gate – CI lacks a dependency‑review or osv‑scanner step.
Medium – missing non‑root USER – containers run as root; add an unprivileged user.
Low – missing job timeouts – workflow client-components.yaml lacks timeout-minutes.
Low – missing repo conventions – no .editorconfig, .gitattributes, or formatter config.

The static analysis also reports 91 high‑severity cognitive‑load issues (deep nesting) in test files such as client/octelium/commands/connect/controller/service_cfg_test.go. Refactoring with early returns will improve maintainability.

The Bottom Line

Octelium provides a concrete, single‑repo implementation of a zero‑trust gateway with a clear Go‑centric core and React UI front‑ends. The codebase is large, modular, and well‑instrumented, but it ships with committed secrets, unpinned CI actions, and deep nesting that will hinder rapid onboarding. It is suitable for teams comfortable managing Go services and willing to address the immediate security hygiene gaps before production use.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,043 files

Go779
TSX51
TypeScript25
JSON20
YAML17
Shell8

ReactTailwindDocker

Module dependencies

The 10 most depended-upon modules of 85, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_Authenticator_Register_index["index"] n1_enticator_Authenticate_index["index"] n2__web_package_src_utils_index["index"] n3__web_package_src_utils_index["index"] n4_c_pages_Authenticator_router["router"] n5_ges_Authenticator_List_index["index"] n6__src_pages_Namespaces_router["router"] n7_ge_src_pages_Services_router["router"] n8_w_wrdpgw_web_package_src_App["App"] n9_ge_src_pages_Approval_router["router"] n1_enticator_Authenticate_index --> n0_Authenticator_Register_index n5_ges_Authenticator_List_index --> n1_enticator_Authenticate_index n5_ges_Authenticator_List_index --> n0_Authenticator_Register_index n4_c_pages_Authenticator_router --> n1_enticator_Authenticate_index n4_c_pages_Authenticator_router --> n5_ges_Authenticator_List_index n4_c_pages_Authenticator_router --> n0_Authenticator_Register_index

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them cluster/authserver/authserver/web/package/.env.development, cluster/portal/portal/web/package/.env.development, cluster/wrdpgw/wrdpgw/web/package/.env.development

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low2

Untrack the file your own .gitignore says to ignorehigh

cluster/authserver/authserver/web/package/.env.development

tracked although .gitignore excludes it

The author already decided this file must never be committed, so its presence is an accident nobody noticed, which means the credentials in it are the ones actually in use.

Fix: git rm --cached the path and rotate; the ignore rule is already correct.

Pin third-party GitHub Actions to a commit SHAhigh6 occurrences

.github/workflows

rlespinasse/github-slug-action@v4, docker/metadata-action@v4, docker/setup-buildx-action@v3, docker/login-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Remove the committed .env and rotate what it holdshigh3 occurrences

cluster/authserver/authserver/web/package/.env.development

cluster/authserver/authserver/web/package/.env.development, cluster/portal/portal/web/package/.env.development, cluster/wrdpgw/wrdpgw/web/package/.env.development

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Enable Dependabot or Renovatemedium

26 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

client/octelium/Dockerfile

golang:1.26.5, alpine:3.23

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Add a non-root USER to the imagemedium

client/octelium/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/client-components.yaml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.