DEV Community

Alex Voste
Alex Voste

Posted on

ForgeZero 3.1 “AEGIS”: Hardening a CLI Toolchain into a Secure Engineering Platform

#tooling #go #zig #c

We’ve just released ForgeZero v3.1.0 “AEGIS” — the largest architectural update since the project began.

This release is not primarily about new features.

It’s about trust.

How do you make a build toolchain safer?
How do you prevent corrupted state?
How do you eliminate filesystem race conditions?
How do you support Windows natively without falling back to WSL?

AEGIS was our answer.

The Goal: Harden Everything

ForgeZero started as a sovereign build toolchain.

With AEGIS, the goal was to harden every critical path:

  • file access
  • process execution
  • path validation
  • manifest generation
  • checksum verification
  • supply-chain integrity
  • platform consistency

The result is a significantly more resilient engineering platform.

1. Native Windows Support (Without WSL)

One of the biggest milestones in this release:

ForgeZero now runs natively on Windows without requiring WSL.

That meant much more than “it builds on Windows.”

It required platform-aware security guarantees.

Implemented:

  • Native Windows Virtual FileSystem backend
  • Drive-letter normalization (C:\)
  • UNC path validation and unsafe network path rejection
  • .exe / .bat executable resolution
  • Retry-safe close-then-rename semantics
  • Reparse-point and symlink safety checks

Windows is now a first-class platform.

2. A Dedicated Virtual FileSystem Layer

We moved all filesystem operations behind a hardened abstraction:

internal/fs
Enter fullscreen mode Exit fullscreen mode

This is more than an interface wrapper.

It provides:

  • verified file access
  • symlink rejection before open
  • TOCTOU race protection 
Lstat → open → SameFile verification
Enter fullscreen mode Exit fullscreen mode
  • atomic writes
  • fail-closed behavior
  • root-boundary enforcement
  • injectable mock filesystem for deterministic testing

If something looks unsafe, ForgeZero stops.

That’s intentional.

3. Hardened Command Execution

Every external process now goes through a unified execution pipeline:

RunCommand()
RunCommandOutput()
LookExecutable()
Enter fullscreen mode Exit fullscreen mode

Security improvements:

  • no shell invocation
  • exec.CommandContext
  • deterministic environment
  • secure executable discovery
  • CLI path validation
  • traversal rejection (../)
  • constant-time checksum verification

This removed multiple raw execution paths across the codebase.

Before:

pkgman → raw git exec
linker → raw nm/objdump/readelf
builder → raw ar
Enter fullscreen mode Exit fullscreen mode

After:

all external commands → hardened execution layer
Enter fullscreen mode Exit fullscreen mode

4. Verified File Access & TOCTOU Protection

Race conditions in filesystem operations are easy to ignore.

They shouldn’t be.

AEGIS introduces verified reads:

OpenVerified()
OpenVerifiedRead()
Enter fullscreen mode Exit fullscreen mode

The sequence:

1. Lstat()
2. Reject symlinks
3. Open file
4. SameFile() check
Enter fullscreen mode Exit fullscreen mode

This prevents classic time-of-check/time-of-use attacks.

5. Atomic Everything

Interrupted writes can corrupt manifests, cache entries, or build artifacts.

Now all critical writes are atomic:

SecureWriteFile()
atomicWrite()
Enter fullscreen mode Exit fullscreen mode

Pattern:

temp file → fsync → rename
Enter fullscreen mode Exit fullscreen mode

On Windows, rename includes retry-safe logic to handle file locking behavior.

6. Supply Chain Hardening

We expanded integrity guarantees for:

  • verify
  • sbom
  • vendor scanning

Improvements:

  • secure manifest reads
  • atomic manifest generation
  • constant-time hash comparison
  • fail-closed symlink handling
  • explicit warnings for external vendor symlinks
  • degraded hashing instead of silent bypass

Supply-chain security should not be optional.

7. New: fz doctor

A new diagnostics command:

fz doctor
Enter fullscreen mode Exit fullscreen mode

Checks:

  • zig
  • fasm
  • wasm-ld
  • root accessibility
  • filesystem permissions
  • recursive verified reads
  • active VFS backend
  • runtime environment

JSON mode:

fz doctor --json
Enter fullscreen mode Exit fullscreen mode

This is especially useful in CI environments.

Testing & Reliability

Everything was validated through:

go test ./...
go test -race ./...
GOOS=windows go build ./...
Enter fullscreen mode Exit fullscreen mode

All green.

Coverage highlights:

pkgman   91.5%
fs       91.7%
doctor   90.8%
config   91.7%
watcher  91.1%
verify   84.0%
utils    83.1%
Enter fullscreen mode Exit fullscreen mode

We also added:

  • branch coverage suites
  • fault-injection testing
  • mock subprocess execution
  • mock HTTP flows
  • VFS failure-path testing

Why This Matters

Most CLI tools focus on functionality.

Fewer focus on resilience.

Even fewer guarantee:

  • predictable behavior
  • secure execution
  • cross-platform parity
  • race-condition resistance
  • fail-closed integrity

That’s what AEGIS is about.

Not just new capabilities.

A stronger foundation.

ForgeZero v3.1.0 “AEGIS” is live.

GitHub: https://github.com/forgezero-cli/forgezero
Author: https://github.com/alexvoste

I’d love feedback from anyone building:

  • developer tools
  • compilers
  • CI/CD systems
  • package managers
  • secure build pipelines

Top comments (0)