the engine

Abstract

Sovereign Engine is a multi-cloud infrastructure platform that provides unified deployment, cost management, and security verification across AWS, Azure, GCP, DigitalOcean, Hetzner, and OVH.Built with Go and Crossplane, Sovereign Engine enables infrastructure-as-code automation with real-time monitoring, automated cleanup policies, and security

The Problem

Operating workloads across AWS, Azure, GCP, DigitalOcean, Hetzner and OVH forces teams to juggle disparate CLIs, IAM policies and cost‑tracking tools. Manual stitching leads to drift, unexpected spend and fragmented security checks.

What This Does

Sovereign Engine supplies a Go‑based control plane that abstracts each cloud into a common set of “providers”. The core CLI lives in cmd/cli/main.go and invokes the managers defined in the internal/ package:

internal/alerts/alerts.go – creates AlertManager (functions NewAlertManager, Start, CreateAlert).
internal/cleanup/cleanup.go – creates CleanupManager (functions NewCleanupManager, Start, processCleanup).
internal/finops/budget.go – provides cost‑estimation helpers (EstimateCost, GetCurrentSpend).
internal/config/secure.go – encrypts/decrypts credential files (Encrypt, Decrypt, LoadSecureEnvFile).

YAML composition files under compositions/ describe concrete resources per provider (e.g. compositions/aws/compute.yaml). Dockerfiles in build/docker/ package the UI, function runtime and reverse‑proxy services.

How It Is Wired

Execution begins at main in cmd/cli/main.go:33. The entry point parses sub‑commands (deploy, list, cost, drift‑check) and routes to handlers such as handleDeploy. From there the flow is:

handleDeploy → ProcessDeployment (internal/function/handler.go:105).
ProcessDeployment calls EstimateCost (internal/finops/budget.go).
EstimateCost reaches the alert system via NewAlertManager.Start (internal/alerts/alerts.go).
Start spawns the cleanup scheduler (NewScheduler in internal/cron/scheduler.go) and the cache (NewCache in internal/cache/cache.go).

The most widely used symbols are:

Stop – invoked from 11 locations.
NewScheduler – invoked from 10 locations.
NewAlertManager – invoked from 9 locations.

These hubs sit in internal/alerts/alerts.go and internal/cron/scheduler.go; changes to them have the largest blast radius because many downstream functions depend on them. The import graph shows 8 internal modules with 17 edges and no circular dependencies, so the codebase is structurally flat, reducing the risk of hidden coupling.

External interactions are limited: the only filesystem write observed is updateSecureFile (called from main), and network calls are confined to monitoring back‑ends (e.g. Prometheus, Datadog) configured via environment variables but not hard‑wired in the static call graph.

How To Use It

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

# Build the CLI (Makefile provides a default target)
make build        # produces ./engine binary

# Generate a master key (first‑run script in README)
export ENGINE_MASTER_KEY=$(./engine generate-key)

# Encrypt cloud credentials
./engine-encrypt -key AWS_ACCESS_KEY_ID \
    -value 'AKIA…' -file ~/.engine/secure.env
./engine-encrypt -key AWS_SECRET_ACCESS_KEY \
    -value 'wJalrXU…' -file ~/.engine/secure.env

# Deploy a micro tier to AWS us‑east‑1
./engine deploy --provider aws --tier micro --region us-east-1

Configuration files live under compositions/ (one folder per cloud) and are referenced automatically by the CLI. Optional monitoring and CI/CD integrations are selected with environment variables such as MONITORING_SYSTEM=prometheus or CICD_SYSTEM=github as documented in the README.

Real‑World Use

A SaaS team runs the binary in a CI job that provisions a temporary test environment for each pull request. The CleanupManager automatically shuts down idle dev stacks after 8 h and nukes them after 24 h, while the AlertManager posts cost warnings to a Slack webhook when spend exceeds 80 % of the configured budget. This prevents runaway resources and gives developers immediate feedback.

Code Health & Issues

HIGH – GitHub Actions pinned to mutable tags (aquasecurity/trivy-action@master, etc.).
HIGH – No LICENSE file; redistribution rights are undefined.
MEDIUM – Base image golang:1.26-alpine not pinned by digest.
MEDIUM – Generated build output (build/) committed to VCS.
MEDIUM – Checkout step keeps token (persist-credentials not disabled).
MEDIUM – Container runs as root; no non‑root USER defined.
LOW – Workflow jobs lack timeout-minutes.
LOW – Repository missing convention files (.editorconfig, formatter config).

Static analysis also flagged deep nesting (max depth 9) in internal/docs/swagger.go and internal/cleanup/*, duplicated cleanup code across several provider‑specific files, and high branching density in internal/cleanup/rules.go. These patterns increase cognitive load and maintenance cost.

The Bottom Line

Sovereign Engine delivers a concrete multi‑cloud provisioning CLI with built‑in cost alerts and automated cleanup, backed by a clear Go module structure. It is usable out‑of‑the‑box but requires hygiene work (license, pinned actions, non‑root containers) and some refactoring to reduce complexity in the cleanup subsystem. Teams comfortable with Go and Kubernetes will find it a solid foundation for controlled, cost‑aware cloud deployments.

What the analyser found

Deployment readiness

6/7

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

Composition

178 files

Go83
YAML65
Markdown8
TypeScript7
Shell3
HTML1

DockerKubernetes

Module dependencies

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

graph LR n0_src_types["types"] n1_src_config["config"] n2_src_http_client["http-client"] n3_src_subscribers["subscribers"] n4_src_websocket["websocket"] n5_src_telecom_sdk["telecom-sdk"] n6_src_index["index"] n7_web_script["script"] n2_src_http_client --> n0_src_types n2_src_http_client --> n1_src_config n6_src_index --> n5_src_telecom_sdk n6_src_index --> n1_src_config n6_src_index --> n2_src_http_client n6_src_index --> n3_src_subscribers n6_src_index --> n4_src_websocket n6_src_index --> n0_src_types n3_src_subscribers --> n2_src_http_client n3_src_subscribers --> n0_src_types n5_src_telecom_sdk --> n1_src_config n5_src_telecom_sdk --> n2_src_http_client n5_src_telecom_sdk --> n3_src_subscribers n5_src_telecom_sdk --> n4_src_websocket n5_src_telecom_sdk --> n0_src_types n4_src_websocket --> n1_src_config n4_src_websocket --> n0_src_types

Findings

MediumNo LICENSE file - unclear usage/redistribution rights root

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.

high2

medium4

low2

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

aquasecurity/trivy-action@master, azure/setup-kubectl@v4, goreleaser/goreleaser-action@v7

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.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Pin the container base image by digestmedium

build/Dockerfile.function

golang:1.26-alpine

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.

Remove generated build output from version controlmedium7 occurrences

build

7 generated files committed

The reviewer reads src, production runs dist, and a stale bundle means the fix that was reviewed is not the code that executes.

Fix: Gitignore the output directory and build in CI.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

build/Dockerfile.function

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 jobslow3 occurrences

.github/workflows/ci.yml

3 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.