How We Build

Why This Matters

Networking and security infrastructure does not get the luxury of a graceful degradation. A NAT bug is an outage. A wrong firewall verdict is a breach. A single over-broad IAM grant is a standing liability in your account. The blast radius of a defect is the whole data plane.

That is the standard Cloud Spectra is held to, so it is the standard we engineer to. This page is our open notebook -- not a badge wall, but a concrete account of the practices that keep the product correct as it grows. Where we cite a number, it is measured from the codebase, not rounded up for effect. Where something is still on the roadmap, we say so.

Engineering Principles

Six rules govern how every change to Cloud Spectra is made. They are enforced in the build, not posted on a wall.

The Testing Pyramid

Cloud Spectra is tested at three tiers, each trading speed for fidelity. Thousands of fast unit tests form the base; a smaller number of high-fidelity tests run against real AWS at the top. A change has to clear all three before it can ship.

graph TD
    U["UNIT -- 10,500+ Go and 2,300+ Angular tests
pure functions, run in milliseconds on every commit"]
    E["EMULATED INTEGRATION -- moto AWS-API emulation
deterministic ordering and dependency coverage, no live infra"]
    I["LIVE-AWS INTEGRATION -- 520+ scenarios on real stacks
NAT, firewall/IDS, transit mesh, EIP failover, TLS"]
    U --> E --> I
    style U fill:#d1fae5,stroke:#10b981,color:#065f46
    style E fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style I fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6

Three tiers: a broad base of fast unit tests, escalating to high-fidelity tests against live AWS accounts

Test-Driven Development

TDD is not a preference here -- it is a hard rule for both the Go backend and the Angular dashboard. Every new function or branch gets explicit coverage of its happy path, its error and edge cases, and its boundary conditions. New code does not land without it.

To make that possible, logic that does not call AWS or perform I/O is pulled out into pure functions that are trivially testable. Anything that does touch an external system is hidden behind an injectable function seam, so tests drive the real decision logic without spinning up real infrastructure. The result is that correctness lives in code we can test exhaustively in milliseconds, not in a boundary we have to mock and hope about.

Regression-Driven Analysis

This is the practice we are most disciplined about, and the one that compounds. When a bug surfaces -- in an integration test, a live run, or manual debugging -- we do not just patch it. Every fix runs the same loop:

graph LR
    A["Bug found
(integration test, live run, report)"] --> B["Explain WHY unit tests missed it
stubbed seam? mocked-away boundary?"]
    B --> C["Write a test that FAILS
on the old code"]
    C --> D["Apply the fix
the test now PASSES"]
    D --> E["Sweep the whole codebase
for the same class of bug"]
    E --> F["Fix every instance in one change
add tests at each site"]
    F --> A
    style A fill:#fecaca,stroke:#ef4444,color:#991b1b
    style B fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style C fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style D fill:#d1fae5,stroke:#10b981,color:#065f46
    style E fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style F fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6

Every bug is converted into a permanent test -- and we fix the whole class, not just the one instance that bit us

1. Explain why the tests missed it. We identify the structural reason -- a decision delegated to a mocked-away boundary, a missing adversarial fixture, a failure that only emerges across layers. The gap is the real defect.
2. Make the bug catchable. We add a test that fails on the old code and passes on the fix, usually by pulling the decision out of the mocked boundary into a pure function and feeding it the exact input that should have been rejected.
3. Sweep for the whole class. We hunt the entire codebase for the same anti-pattern -- other over-broad filters, other first-match selections, other invariants that were mocked away -- and fix them all at once, with tests covering each.

A concrete example: a real example of this is our IAM condition-key work. A single over-broad permission once evaluated as null at runtime and silently 403'd. The fix was not one line -- it was a reference-driven invariant test that now validates every condition key against AWS's published rules and has caught more than a dozen latent traps of the same class across the cross-account policies.

By the Numbers

Counts are a floor, not the whole story -- a green suite proves the tests we wrote pass, not that we wrote every test that matters. We publish them anyway, because the shape is telling: there is more test code than production code.

Verified Test Results

We would rather show than tell. The two pages below are generated automatically by the build pipeline -- and only when the suite is green -- then published here. They are carefully sanitized by design: aggregate counts, coverage percentages, and human-written capability labels only. An automated guard fails the build if any source, file path, or internal identifier tries to slip through, so the transparency never comes at the cost of exposing how the product is built.

Dual-Lane Deploy Parity

Cloud Spectra can be deployed two ways -- a CloudFormation stack or a native Terraform module -- and customers rely on both. The danger is obvious: two definitions of the same infrastructure drift apart, and one lane silently 403s or misbehaves while the other works fine. We engineer that risk out.

graph TD
    SRC["Single source of truth
policy & resource generators (Go)"]
    CF["CloudFormation lane
cloudspectra_gateway templates"]
    TF["Terraform lane
native module + provider"]
    GUARD{"Guard tests:
do both lanes match?
(parity + minimization)"}
    SHIP["Ship"]
    BREAK["Build fails"]
    SRC --> CF
    SRC --> TF
    CF --> GUARD
    TF --> GUARD
    GUARD -->|"in lockstep"| SHIP
    GUARD -->|"drift detected"| BREAK
    style SRC fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style CF fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style TF fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style GUARD fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style SHIP fill:#d1fae5,stroke:#10b981,color:#065f46
    style BREAK fill:#fecaca,stroke:#ef4444,color:#991b1b

Two ways to deploy, one definition of correct. Guard tests fail the build if the CloudFormation and Terraform lanes diverge.

Shared policy is generated from a single source and consumed by both lanes. Dedicated guard tests then assert the two stay aligned, and a minimization test forces every new permission to be justified and triaged rather than quietly accumulating. If the lanes drift, the build breaks before a release can.

Least-Privilege, Verified

An IAM policy that looks correct can still be wrong in a way AWS never warns you about: if a condition key is not valid for a given action and resource type, AWS evaluates it as null, skips the Allow, and the call 403s at runtime. The reverse failure is worse -- a grant broader than it needs to be sits in your account as a permanent liability.

So every permission Cloud Spectra requests is checked, in the build, against AWS's own published reference of which condition keys are valid for each action and resource. We scope to the maximum AWS actually supports -- and a permission that cannot be proven valid simply does not ship.

graph LR
    P["Proposed IAM grant
action + resource + condition"] --> R{"Condition key valid for
this action + resource?
(AWS reference)"}
    R -->|"Yes"| OK["Allowed -- scoped to the
maximum AWS supports"]
    R -->|"No"| FAIL["Build fails
avoids null-eval silent 403"]
    style P fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style R fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style OK fill:#d1fae5,stroke:#10b981,color:#065f46
    style FAIL fill:#fecaca,stroke:#ef4444,color:#991b1b

Every condition key is validated against AWS's reference for the specific action and resource. Unverifiable permissions never ship.

For the full picture of how Cloud Spectra handles your account, data, and permissions, see the Trust Center.

Every Change, Every Path

None of the above is optional or run by hand. Every change runs the full gate -- the same way, every time -- before it can become a release.

graph LR
    C["Commit"] --> G["Go unit tests
(in build container)"]
    G --> A["Angular specs
(headless Chrome)"]
    A --> B["Build
.deb + CF templates + provider"]
    B --> M["Emulated integration
(moto)"]
    M --> L["Live-AWS integration
(real stacks)"]
    L --> S["Release"]
    style C fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style B fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style S fill:#d1fae5,stroke:#10b981,color:#065f46

Unit, build, emulated, and live-AWS stages all gate a release -- and the package, templates, and provider are always built together from one commit.

Measured Behavior

Correctness is the floor; for an appliance in the data path, behavior under failure is what actually matters. These are the operational targets Cloud Spectra is built and tested to, and what our integration suite exercises against live infrastructure.

Runs in Your Account

The most important reliability and trust property is structural: Cloud Spectra runs entirely inside your AWS account. No traffic leaves your network, no telemetry phones home, and there are no third-party agents on your instances. Every security guarantee is enforced by AWS infrastructure you already own and control -- not by trusting us.

That means the engineering rigor on this page is something you can verify, not just take our word for: the IAM policies are visible in your account, the resources are tagged and inspectable, and the data plane is yours to audit. The full account-handling and compliance posture lives in the Trust Center.

What's Next

We would rather be honest about what is in flight than overstate where we are. Engineering transparency is a direction, not a finished destination. On the roadmap:

• Live integration-test status. Now live -- a continuously updated, carefully sanitized live-AWS integration report and automated test report, so the green is verifiable rather than asserted. Historical trends and per-run timelines are the next step.
• SOC 2 Type II. The independent attestation enterprise teams rely on, on top of the controls already in place.
• Third-party penetration test summary. An outside-in assessment, published in summary form.
• Public status & incident history. Uptime and honest post-incident write-ups -- because how a vendor handles the bad day is the real signal.