Forem: Bala Paranj

One Test File That Prevents All Architecture Regressions

Bala Paranj — Thu, 09 Apr 2026 12:00:37 +0000

Every team talks about hexagonal architecture. Almost no team enforces it.

You draw the dependency diagram: core/ never imports adapters/. adapters/ never imports cmd/. Everyone nods. Then a developer in a hurry adds import "internal/adapters/output" inside a core package because they need a JSON helper. The code review approves it because the reviewer is focused on the feature logic, not the import list.

Six months later, core/ imports from 4 adapter packages and nobody remembers when it started.

I wrote one test file that makes this impossible.

The Test

func TestCoreNeverImportsAdapters(t *testing.T) {
    forbidden := []string{
        "github.com/myapp/internal/adapters/",
        "github.com/myapp/internal/cli/",
        "github.com/myapp/cmd/",
        "os/exec",
    }

    corePackages := discoverPackages(t, "internal/core/")

    for _, pkg := range corePackages {
        for _, imp := range pkg.Imports {
            for _, banned := range forbidden {
                if strings.HasPrefix(imp, banned) {
                    t.Errorf("core package %s imports forbidden %s", 
                        pkg.Name, imp)
                }
            }
        }
    }
}

It walks every Go file in internal/core/, extracts the import list, and fails if any import matches a forbidden prefix. That's it.

What It Catches

Real violation: os/exec in core

When I added an E2E test runner to internal/core/enginetest/, the test immediately caught it:

core test isolation violation: internal/core/enginetest/e2e_test.go: imports os/exec

os/exec is an infrastructure dependency — it invokes external processes. It doesn't belong in core, even in test files. The E2E runner was moved to e2e/ at the repo root.

Without this test, the import would have stayed. It compiled fine. No reviewer would have caught it because os/exec in a test file looks reasonable.

Real violation: adapter type in port interface

A port interface in app/contracts/ accepted an adapter type as a parameter:

// BEFORE: Port contaminated with adapter type
type EvaluationLoader interface {
    Load(ctx context.Context, path string) (*adapters.Evaluation, error)
}

The test caught the import of adapters/ from the app/ layer. The fix: the port returns a domain type, and the adapter converts at the boundary.

// AFTER: Port uses only domain types
type EvaluationLoader interface {
    Load(ctx context.Context, path string) (*report.Assessment, error)
}

Why Code Reviews Aren't Enough

Code reviews catch architecture violations about 80% of the time. The other 20%:

The reviewer is focused on the feature logic, not import lists
The PR has 40 files and the violation is in file 37
The import looks reasonable in context ("I just need this one helper")
The reviewer doesn't know the architecture rules because they're in a wiki nobody reads

A test catches violations 100% of the time. It runs in CI on every push. It doesn't get tired, distracted, or rushed.

How to Build It

Step 1: Define your layers

internal/
  core/       → NEVER imports adapters, app, cmd, os/exec
  app/        → NEVER imports adapters, cmd
  adapters/   → May import core, app
  cli/        → May import anything
cmd/          → May import anything

Step 2: Discover packages programmatically

func discoverPackages(t *testing.T, root string) []PackageInfo {
    var packages []PackageInfo
    filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if !d.IsDir() && strings.HasSuffix(path, ".go") {
            imports := extractImports(path)
            packages = append(packages, PackageInfo{
                Path:    path,
                Imports: imports,
            })
        }
        return nil
    })
    return packages
}

Step 3: Check every import against the forbidden list

for _, pkg := range corePackages {
    for _, imp := range pkg.Imports {
        for _, banned := range forbidden {
            if strings.HasPrefix(imp, banned) {
                t.Errorf("%s imports forbidden %s", pkg.Path, imp)
            }
        }
    }
}

Step 4: Run it in CI

- name: Architecture check
  run: go test ./internal/app/ -run TestCoreNeverImportsAdapters

The ROI

This test is the most leveraged single commit in the codebase.

Over 4 months and 60 refactorings, every structural change had to pass this test. When we merged internal/infra/ into internal/adapters/, the test verified no core packages imported the old path. When we moved types between layers, the test verified the dependency direction.

Without it, the hexagonal boundaries would have eroded under the pressure of daily development. With it, the architecture is mechanically guaranteed.

The test took 30 minutes to write. It has prevented more regressions than any refactoring in the catalog.

What It Doesn't Catch

Logic violations: A function in core/ that formats CLI output text. The import is legal (fmt), but the responsibility is wrong. This still needs code review.
Interface design: A port with 10 methods (ISP violation). The import direction is correct but the interface is too fat. This needs design review.
Naming: A core package named utils instead of a domain concept. The architecture is fine but discoverability suffers.

The fitness function enforces the structural rules. Design and naming still need human judgment. But by automating the structural check, you free up code review time to focus on the things that require judgment.

Checkout the code in my open source project Stave. The architecture fitness function has been running in CI since January 2026 and has caught 4 violations that would have been missed in code review.

Accept Interfaces, Return Structs: 5 Patterns From a Go CLI

Bala Paranj — Wed, 08 Apr 2026 14:36:36 +0000

"Accept interfaces, return structs" is the most quoted Go proverb and the least applied. Most Go codebases do the opposite: they define interfaces at the implementation site, accept concrete types, and return interfaces.

Over 60 refactorings, I applied this proverb in 5 distinct ways. Each one solved a different coupling problem, but they all followed the same rule: the consumer defines the interface, the producer returns the concrete type.

Pattern 1: Decouple a Component from Its Container

The Problem

Evaluation strategies had a back-pointer to the concrete Runner:

// BEFORE: Strategy depends on the concrete Runner type
type unsafeStateStrategy struct {
    runner *Runner               // ← concrete dependency
    ctl    *policy.ControlDefinition
}

func (s *unsafeStateStrategy) Evaluate(t *asset.Timeline, now time.Time) (Row, []*Finding) {
    maxUnsafe := s.runner.getMaxUnsafeDurationForControl(s.ctl)
    logger := s.runner.Logger
    parser := s.runner.PredicateParser
    // ...
}

The strategy needed 4 things from the Runner: a max-unsafe duration, a logger, a gap threshold, and a predicate parser. But it depended on the entire Runner type — all 12 fields, all methods, the full dependency graph.

Testing a strategy meant constructing a full Runner with all its dependencies, even though the strategy only used 4 of them.

The Fix

Define a narrow interface at the consumer (the strategy), not at the producer (the Runner):

// AFTER: Strategy depends on a 4-method interface it defines
type strategyDeps interface {
    slaThresholdFor(ctl *policy.ControlDefinition) time.Duration
    continuityLimit() time.Duration
    logger() *slog.Logger
    predicateParser() policy.PredicateParser
}

type unsafeStateStrategy struct {
    deps strategyDeps            // ← interface, not concrete type
    ctl  *policy.ControlDefinition
}

func (s *unsafeStateStrategy) Evaluate(t *asset.ExposureLifecycle, now time.Time) (ResourceCheck, []*Finding) {
    maxUnsafe := s.deps.slaThresholdFor(s.ctl)
    // ...
}

The Runner (now Assessor) satisfies the interface implicitly — no implements keyword:

// Runner/Assessor satisfies strategyDeps without declaring it
func (a *Assessor) slaThresholdFor(ctl *policy.ControlDefinition) time.Duration {
    return ctl.EffectiveMaxUnsafeDuration(a.SLAThreshold)
}
func (a *Assessor) continuityLimit() time.Duration { return a.ContinuityLimit }
func (a *Assessor) logger() *slog.Logger           { return a.Logger }
func (a *Assessor) predicateParser() policy.PredicateParser { return a.PredicateParser }

Testing a strategy now requires a 4-method mock, not a 12-field constructor:

// Test: mock only what the strategy needs
type mockDeps struct{}
func (m mockDeps) slaThresholdFor(_ *policy.ControlDefinition) time.Duration { return 24 * time.Hour }
func (m mockDeps) continuityLimit() time.Duration { return 12 * time.Hour }
func (m mockDeps) logger() *slog.Logger { return slog.Default() }
func (m mockDeps) predicateParser() policy.PredicateParser { return nil }

After the refactor, strategies went from untestable (coupled to Runner) to independently testable.

Pattern 2: Slim a Fat Interface

The Problem

The Control interface had 8 methods:

// BEFORE: Fat interface — every implementor must provide 8 methods
type Control interface {
    ID() kernel.ControlID
    Description() string
    Severity() Severity
    ComplianceProfiles() []string
    ComplianceRefs() map[string]string
    ProfileRationale(profile string) string
    ProfileSeverityOverride(profile string) Severity
    Evaluate(snap asset.Snapshot) Result
}

Every control implementation had to provide 7 getter methods that all did the same thing: return a field from a Definition struct. The getters were boilerplate — 14 lines per control, identical across all 14 controls.

The Fix

Slim to 2 methods. Return a struct for the metadata:

// AFTER: 2-method interface — return struct for metadata
type Control interface {
    Def() Definition    // ← returns struct, not 7 methods
    Evaluate(snap asset.Snapshot) Result
}

The Definition struct carries all the metadata:

type Definition struct {
    id                kernel.ControlID
    description       string
    severity          Severity
    complianceProfiles []string
    complianceRefs    map[string]string
    // ...
}

func (d Definition) ID() kernel.ControlID { return d.id }
func (d Definition) Severity() Severity   { return d.severity }
// ... accessor methods on the struct, not the interface

Callers changed from ctrl.ID() to ctrl.Def().ID():

// BEFORE
controlID := ctrl.ID()
severity := ctrl.Severity()
refs := ctrl.ComplianceRefs()

// AFTER
controlID := ctrl.Def().ID()
severity := ctrl.Def().Severity()
refs := ctrl.Def().ComplianceRefs()

One extra .Def() call. But the interface dropped from 8 methods to 2. New controls only implement Evaluate — the metadata comes from the Definition struct built with functional options:

// Construction with functional options — no method boilerplate
type accessBlockPublic struct {
    Definition
}

func init() {
    ControlRegistry.MustRegister(&accessBlockPublic{
        Definition: NewDefinition(
            WithID("CTL.S3.CONTROLS.001"),
            WithSeverity(Critical),
            WithComplianceRef("hipaa", "§164.312(a)(1)"),
        ),
    })
}

func (ctl *accessBlockPublic) Evaluate(snap asset.Snapshot) Result {
    // Only the evaluation logic — no getter boilerplate
}

After the refactor — 14 controls lost 7 boilerplate methods each.

Pattern 3: Port Interfaces with Domain-Only Types

The Problem

A port interface in app/contracts imported a type from internal/core/evaluation/remediation:

// BEFORE: Port contaminated with business logic package
package contracts

import "github.com/sufield/stave/internal/core/evaluation/remediation"

type EnrichedResult struct {
    Findings []remediation.Finding  // ← port imports domain implementation
}

The port (in the app layer) depended on a specific domain package. Adapters that implemented the port had to import remediation even if they only needed the finding's ID and severity. The dependency arrow pointed inward (correct direction) but the coupling was too tight.

The Fix

Define a boundary type in the port package using only types the port already imports:

// AFTER: Port uses its own boundary type
package contracts

import (
    "github.com/sufield/stave/internal/core/evaluation"
    policy "github.com/sufield/stave/internal/core/controldef"
)

type EnrichedFinding struct {
    Finding     evaluation.Finding
    Remediation policy.RemediationSpec
}

type EnrichedResult struct {
    Findings []EnrichedFinding  // ← uses only types already in contracts
}

The enrichment pipeline maps at the boundary:

// Boundary conversion in the app layer
func enrich(findings []remediation.Finding) []contracts.EnrichedFinding {
    result := make([]contracts.EnrichedFinding, len(findings))
    for i, f := range findings {
        result[i] = contracts.EnrichedFinding{
            Finding:     f.Finding,
            Remediation: f.RemediationSpec,
        }
    }
    return result
}

Adapters convert back to remediation.Finding only when they need the full type — via local toRemediationFindings helpers.

After the refactor — port boundary no longer imports business logic packages.

Pattern 4: One-Method Interfaces at the Boundary

The Problem

Infrastructure capabilities were injected as concrete function types or large interfaces:

// BEFORE: Bare function type mixed with other concerns
type Runner struct {
    Logger      *slog.Logger
    Clock       func() time.Time      // ← bare function, no testability signal
    Hasher      func([]byte) string   // ← bare function
    Controls    []ControlDefinition
    MaxUnsafe   time.Duration
}

func() time.Time is technically an interface with one method — but it has no name, no documentation, and no discoverable implementations.

The Fix

Named one-method interfaces in a ports package:

// AFTER: Named interfaces with concrete implementations
package ports

type Clock interface {
    Now() time.Time
}

type RealClock struct{}
func (RealClock) Now() time.Time { return time.Now().UTC() }

type FixedClock time.Time
func (f FixedClock) Now() time.Time { return time.Time(f) }

type Digester interface {
    Digest(components []string, sep byte) kernel.Digest
}

type Verifier interface {
    Verify(data []byte, sig kernel.Signature) error
}

The consumer declares the dependency as a named interface:

type Assessor struct {
    Clock  ports.Clock     // ← named interface, not func() time.Time
    Hasher ports.Digester  // ← named interface, not func([]byte) string
}

Testing uses the provided implementations — no mocking framework needed:

// Test: deterministic time
assessor := &Assessor{
    Clock: ports.FixedClock(time.Date(2026, 1, 15, 0, 0, 0, 0, time.UTC)),
}

Each interface has exactly one method. Go's implicit interface satisfaction means any type with a Now() time.Time method satisfies Clock — including FixedClock, RealClock, or any test stub.

Pattern 5: Remove Unnecessary Interface Threading

The Problem

An IdentityGenerator interface was threaded through 4 levels of the call stack:

// BEFORE: Interface threaded through entire chain
func NewPlanner(idGen ports.IdentityGenerator) *Planner { ... }
func NewMapper(idGen ports.IdentityGenerator) *Mapper { ... }

type publicExposurePlanner struct {
    idGen ports.IdentityGenerator  // ← carried but used once at the end
}

func (p *publicExposurePlanner) Plan(findings []Finding) []RemediationPlan {
    for _, f := range findings {
        plan := RemediationPlan{
            ID: p.idGen.GenerateID("plan", string(f.ControlID), string(f.AssetID)),
            // ...
        }
    }
}

The ID generator was injected into the Planner, carried through the Mapper, and used at one point: generating plan IDs. Four constructors accepted it. Four structs stored it. One call site used it.

The Fix

Generate IDs at the boundary, not inside the domain:

// AFTER: Domain logic is pure — IDs assigned at boundary
func (p *publicExposurePlanner) Plan(findings []Finding) []RemediationPlan {
    for _, f := range findings {
        plan := RemediationPlan{
            ID: "",  // ← empty, assigned later at boundary
            // ...
        }
    }
}

// Boundary function assigns IDs after domain logic completes
func AssignPlanIDs(gen ports.IdentityGenerator, plans []RemediationPlan) {
    for i := range plans {
        plans[i].ID = gen.GenerateID("plan", ...)
    }
}

The Planner and Mapper are now pure domain types with no infrastructure dependencies. AssignPlanIDs is called once at the boundary after enrichment. The interface is accepted at the boundary, not threaded through the domain.

After the refactor — removed IdentityGenerator from 4 constructors and 4 struct fields.

The Rules

Rule	Before	After
Consumer defines the interface	Strategy imports `*Runner`	Strategy defines `strategyDeps` (4 methods)
Return structs, not interfaces	`Control` interface with 8 methods	`Def()` returns `Definition` struct
Ports use only domain types	Port imports `remediation.Finding`	Port defines `EnrichedFinding` boundary type
Name your one-method interfaces	`func() time.Time`	`ports.Clock` with `Now() time.Time`
Don't thread interfaces through domain	`IdentityGenerator` in 4 constructors	`AssignPlanIDs` at boundary

How to Find Violations

# Fat interfaces (more than 3 methods)
grep -rn 'type.*interface {' --include='*.go' -A 10 | grep -c 'func\b' | sort -rn

# Concrete type dependencies that should be interfaces
grep -rn '\*Runner\|\*Engine\|\*Service' --include='*.go' | grep 'struct {' | grep -v '_test.go'

# Interface threading (same interface in multiple constructors)
grep -rn 'ports\.' --include='*.go' | grep 'func New' | sort

# Port contamination (ports importing implementation packages)
grep -rn 'import' internal/app/contracts/ --include='*.go' | grep -v 'core/\|kernel\|asset'

The last command finds port packages importing implementation packages — the signal for Pattern 3.

The Payoff

Before these refactorings, testing the evaluation engine required constructing the full Runner with 12 fields. After, testing a strategy requires a 4-method mock. Testing the Planner requires no mocks at all — it's a pure function.

The interface count went down, not up. Fat interfaces were slimmed. Unnecessary interfaces were removed. The remaining interfaces are small (1-4 methods), defined at the consumer, and satisfied implicitly.

That's the Go way: interfaces should be discovered, not designed.

These 5 patterns were applied across 60 refactorings in Stave, an offline configuration safety evaluator.

Designing Errors Out of Your Go CLI

Bala Paranj — Tue, 07 Apr 2026 13:29:34 +0000

Most Go CLIs have too many error checks. Not because error handling is wrong — because the errors themselves are wrong.

I read the Power of Go Tools by John Arundel. Based on his book, I audited a 50,000-line Go CLI for functions that return errors unnecessarily. The result: 10 functions refactored, 50+ if err != nil checks eliminated, and the remaining error checks now mean something.

This is John Ousterhout's philosophy from A Philosophy of Software Design: don't handle errors better — design them out of existence.

The Four Patterns

I searched for four specific anti-patterns:

Idempotent No-ops — returning an error for a state that already matches the desired outcome
Empty-Set Errors — returning an error when a slice is empty instead of treating it as "no work to do"
Recoverable Internals — returning an error when the function could make a sensible default decision
Crash-Only Candidates — returning an error from initialization code where failure is truly fatal

Here's what I found and how I fixed each one.

Pattern 1: Idempotent No-ops

The temp file cleanup

// BEFORE: returns error if temp file is already gone
func IsDirectoryWritable(dir string) error {
    f, err := os.CreateTemp(dir, ".stave-write-check-*")
    if err != nil {
        return err
    }
    path := f.Name()
    _ = f.Close()
    return os.Remove(path) // ← why does this error matter?
}

The function's job is to check if a directory is writable. If os.Remove fails because the temp file is already gone, the check already passed. The post-condition is met.

// AFTER: cleanup errors are irrelevant
func IsDirectoryWritable(dir string) error {
    f, err := os.CreateTemp(dir, ".stave-write-check-*")
    if err != nil {
        return err
    }
    path := f.Name()
    _ = f.Close()
    _ = os.Remove(path)
    return nil
}

Rule: If the post-condition is satisfied, the function succeeds. Period.

Pattern 2: Empty-Set Safety

The empty registry

// BEFORE: empty registry is treated as an error
func NewIndex(data []byte) (*Index, error) {
    var idx registryIndex
    if err := yaml.Unmarshal(data, &idx); err != nil {
        return nil, err
    }
    if len(idx.Packs) == 0 {
        return nil, ErrEmptyRegistry // ← is zero packs really an error?
    }
    // ...
}

An empty registry means "no packs enabled." That's a valid state — the caller already checks len(packs) before iterating. The error just forces every caller to handle a case that isn't exceptional.

// AFTER: empty registry is a valid zero-work state
func NewIndex(data []byte) (*Index, error) {
    var idx registryIndex
    if err := yaml.Unmarshal(data, &idx); err != nil {
        return nil, err
    }
    // Zero packs is valid — the registry simply has nothing enabled.
    r := &Index{
        version: strings.TrimSpace(idx.Version),
        // ...
    }
    // ...
}

Rule: If an empty input means "nothing to do," the function should succeed with a zero-value result, not fail.

The empty predicate

// BEFORE: empty expression is an error
if expr == "" {
    return CompiledPredicate{}, fmt.Errorf("predicate produced empty expression")
}

// AFTER: empty predicate = always-pass (no rules = compliant)
if expr == "" {
    expr = "true"
}

An empty predicate in a security tool means "no rules defined for this control." That's not an error — it's compliance by default.

Pattern 3: Recoverable Internals

The nil dependency

// BEFORE: nil loader is a fatal error
func ListSnapshotFilesFlat(ctx context.Context, dir string, opts ScannerOptions) ([]SnapshotFile, error) {
    if opts.MetadataLoader == nil {
        return nil, errMetadataLoaderRequired
    }
    // ...
}

The MetadataLoader extracts timestamps from snapshot files. If it's nil, there's a perfectly good fallback: use the file's modification time.

// AFTER: nil loader falls back to filesystem metadata
if opts.MetadataLoader == nil {
    opts.MetadataLoader = func(filePath, _ string) (time.Time, error) {
        fi, err := os.Stat(filePath)
        if err != nil {
            return time.Time{}, err
        }
        return fi.ModTime(), nil
    }
}

Rule: If a sensible default exists, use it instead of forcing the caller to provide a value they probably don't care about.

The zero time

// BEFORE: zero time is rejected
func NewActiveWindow(openedAt time.Time) (ExposureWindow, error) {
    if openedAt.IsZero() {
        return ExposureWindow{}, fmt.Errorf("opened_at is required")
    }
    return ExposureWindow{openedAt: openedAt, active: true}, nil
}

A zero time means "not specified." The window should still be created — the caller can check w.OpenedAt().IsZero() if they care. Most don't.

// AFTER: zero time is accepted — callers check if they care
func NewActiveWindow(openedAt time.Time) ExposureWindow {
    return ExposureWindow{openedAt: openedAt, active: true}
}

This one removed error checks from 30+ call sites. Most were already using tl, _ := NewActiveWindow(...) — the Go equivalent of saying "I know this error doesn't matter."

Pattern 4: Crash-Only Candidates

The programming error

// BEFORE: returns error that no caller can recover from
func NewExposureLifecycle(a Asset) (*ExposureLifecycle, error) {
    if a.ID.IsEmpty() {
        return nil, fmt.Errorf("asset ID must not be empty")
    }
    return &ExposureLifecycle{ID: a.ID, asset: a}, nil
}

An empty asset ID is a programming error at the call site — the caller constructed the asset. If the ID is empty, there's a bug upstream. No caller can meaningfully recover from this. They all either t.Fatal(err) in tests or propagate it up the stack until someone logs it and exits.

// AFTER: panic on contract violation
func NewExposureLifecycle(a Asset) *ExposureLifecycle {
    if a.ID.IsEmpty() {
        panic("contract violated: NewExposureLifecycle requires non-empty asset ID")
    }
    return &ExposureLifecycle{ID: a.ID, asset: a}
}

This matches the checkContracts() pattern already used in the same file for internal state validation. It eliminated error-check boilerplate from 40+ call sites.

Rule: If the error means "you have a bug," use panic. If the error means "the user gave bad input," return an error. Don't conflate programming errors with operational errors.

The Impact

Before:

10 functions returning errors
50+ if err != nil checks across the codebase
Many callers using tl, _ := ... (ignoring the error anyway)

After:

10 functions with clear contracts
50+ fewer error checks
Every remaining if err != nil represents a truly exceptional event

How to Find These in Your CLI

Search for these patterns:

# Functions where callers ignore the error
grep -rn ', _ :=' --include='*.go' | grep -v vendor/ | sort | uniq -c | sort -rn

# Empty-set errors
grep -rn 'len(.*) == 0' --include='*.go' | grep 'Errorf\|errors.New'

# Existing panic patterns (your team already uses crash-only where appropriate)
grep -rn 'panic(' --include='*.go' | grep -v vendor/ | grep -v _test.go

The first command is the most revealing. If you see 40 call sites ignoring an error, the error shouldn't exist.

When NOT to Do This

User input boundaries: Always validate and return errors for user-supplied data
Network/IO operations: These fail for real external reasons
Cross-package contracts: If the caller is in a different package, errors are the right contract
Data integrity: Schema validation, hash mismatches, malformed input — these are real errors

The goal isn't to eliminate error handling. It's to make every if err != nil mean something. When a developer sees an error check, they should know it represents a truly exceptional event — not a no-op, not an empty set, not a sensible default, and not a programming bug.

These refactorings were applied to Stave, an offline configuration safety evaluator.

Why the Capital One Breach Wasn't About One Misconfiguration

Bala Paranj — Mon, 06 Apr 2026 12:26:51 +0000

In 2019, a former AWS employee exploited a server-side request forgery (SSRF) vulnerability in Capital One's web application firewall. The breach exposed over 100 million customer records.

But here's the thing security scanners missed: no single misconfiguration caused the breach.

It was the correlation of three weak signals that produced a critical finding:

An SSRF vulnerability in the WAF configuration
An overly permissive IAM role attached to the compromised instance
Unencrypted S3 buckets containing sensitive customer data

Each finding alone? Low to medium severity. Together? A $190 million breach.

The Problem with Flat Scanners

Most cloud security tools evaluate configurations in isolation. They produce a flat list of findings:

WARN  S3 bucket has public access enabled
WARN  IAM role has overly broad permissions
INFO  Server-side encryption not enabled

Three warnings. No critical alert. The tool did its job — it found each misconfiguration. But it missed the compound risk because it never correlated the signals.

This is the fundamental gap: a scanner that evaluates one configuration at a time cannot reason about the interaction between configurations.

Introducing Stave

Stave is an offline configuration safety evaluator. It takes two inputs — security controls written in YAML and observation snapshots of your cloud infrastructure — and produces a deterministic security assessment. No agents, no API keys, no network access required. It runs entirely on local data, which makes it suitable for air-gapped environments and audit-sensitive workflows.

The examples below use Stave's control language to illustrate how compound predicate evaluation closes the signal correlation gap.

Signal Correlation: The Missing Primitive

What security teams actually need is a way to express compound conditions — predicates that fire only when multiple weak signals appear together on the same asset:

id: CTL.S3.EXPOSURE.COMPOUND.001
name: Unencrypted Public Bucket with Broad IAM Access
description: >
  S3 bucket is publicly accessible, lacks encryption, and is
  accessible by an overly permissive IAM role. This combination
  creates a high-severity data exfiltration risk.
severity: critical

unsafe_predicate:
  all:
    - field: public_access
      op: eq
      value: true
    - field: server_side_encryption
      op: eq
      value: false
    - field: iam_role_scope
      op: eq
      value: "overly_permissive"

The all combinator is the key. This control only fires when every condition is true simultaneously. Three medium-severity signals become one critical finding because the predicate explicitly models the compound risk.

How Compound Predicates Work

The evaluation model supports two combinators:

all — Every condition must be true (logical AND). Use this for compound risk scenarios where the danger comes from the intersection of weak signals.

any — At least one condition must be true (logical OR). Use this for detection breadth where multiple indicators point to the same root cause.

These nest arbitrarily:

unsafe_predicate:
  all:
    - field: public_access
      op: eq
      value: true
    - any:
        - field: server_side_encryption
          op: eq
          value: false
        - field: kms_key_id
          op: missing

This reads: "The bucket is publicly accessible AND (encryption is disabled OR no KMS key is configured)." Two different paths to the same compound risk.

Adding Time as a Correlation Axis

Here's where it gets interesting. A misconfiguration that appeared 2 hours ago is different from one that's been open for 90 days.

If your evaluation engine tracks when a configuration became unsafe — not just whether it's unsafe — you gain a temporal correlation axis:

Finding: CTL.S3.PUBLIC.001
  Asset: patient-records-bucket
  First unsafe: 2026-01-01T00:00:00Z
  Duration: 2160 hours (90 days)
  SLA threshold: 168 hours (7 days)
  Status: NON_COMPLIANT

The same public_access: true finding has radically different severity depending on duration. A bucket that went public 2 hours ago during a deploy is an incident. A bucket that's been public for 90 days is a governance failure.

This requires observation snapshots — point-in-time captures of configuration state. With at least two snapshots, you can compute:

When the unsafe state first appeared
How long it has persisted
Whether it's a new regression or a chronic drift
Whether it exceeds the team's SLA threshold

The Three Correlation Dimensions

Putting it together, configuration risk is a function of three dimensions:

Dimension	Question	Signal
Predicate	What combination of fields is unsafe?	Compound `all`/`any` conditions
Temporal	How long has it been unsafe?	Duration vs SLA threshold
Contextual	What else is true about this asset?	Cross-field correlation

A flat scanner only covers the first dimension — and only one field at a time. Adding predicate composition catches Capital One-style compound risks. Adding temporal tracking catches chronic drift that compliance teams care about.

What This Looks Like in Practice

Given two observation snapshots of an S3 bucket captured a week apart, and a set of controls with compound predicates, the evaluation produces:

{
  "kind": "ASSESSMENT",
  "summary": {
    "total_assets": 1,
    "violations": 3
  },
  "status": "NON_COMPLIANT",
  "findings": [
    {
      "control_id": "CTL.S3.PUBLIC.001",
      "asset_id": "patient-records-bucket",
      "evidence": {
        "first_unsafe_at": "2026-01-01T00:00:00Z",
        "unsafe_duration_hours": 336,
        "threshold_hours": 168,
        "temporal_risk": "SLA_EXCEEDED"
      }
    }
  ]
}

The output is machine-readable JSON. Teams pipe it into their SIEM, Splunk, or ticketing system. The evidence block provides the temporal proof that auditors need — not just "this is misconfigured" but "this has been misconfigured for 336 hours, exceeding your 168-hour SLA."

The Remediation Attestation

After fixing the findings, teams need proof that the fix worked. A before/after comparison produces an attestation:

{
  "kind": "ATTESTATION",
  "summary": {
    "previous_violations": 3,
    "current_violations": 0,
    "remediated": 3,
    "open": 0,
    "regressions": 0
  }
}

Zero regressions. Three remediated. This is the artifact that goes into the compliance record — formal proof that the compound risk was identified and resolved.

Building This Into Your Security Pipeline

The design decisions:

Controls are data, not code. Express compound predicates in YAML/JSON, not in Go/Python functions. This lets security teams author and review controls without touching the evaluation engine.
Observations are snapshots, not streams. Capture configuration state at discrete points in time. Two snapshots a week is enough for SLA tracking. This works offline and doesn't require agent installation.
The evaluation engine is deterministic. Given the same controls, observations, and timestamp, the output is byte-identical. This matters for audit reproducibility.
Separate the assessment from the remediation. The engine produces findings. A separate step verifies the fix. These are different artifacts with different schemas because they answer different questions.

Conclusion

The Capital One breach wasn't caused by one misconfiguration. It was caused by the correlation of three. Most security tools would have flagged each one individually. None would have flagged the compound risk.

If your configuration evaluation can express all/any predicate composition, track temporal duration against SLA thresholds, and produce machine-readable evidence — you're not just scanning. You're doing security assessment.

The difference matters when the auditor asks: "How long was this configuration unsafe, and what else was true at the same time?"

This article describes the evaluation model behind Stave, an offline configuration safety evaluator that uses compound predicate composition and temporal tracking to produce security assessments and remediation attestations.