Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡

feat(khaos): M7 complete, and the polarity bug the live gate found

CarterPerez-dev050e1fc59a37
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/main.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/main.go
index b49bb375..080c6915 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/main.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/main.go
@@ -13,6 +13,8 @@ import (
"syscall"
"time"
+ "github.com/CarterPerez-dev/khaos/internal/pki"
+ "github.com/CarterPerez-dev/khaos/internal/tlsclient"
"github.com/CarterPerez-dev/khaos/internal/verifier"
)
@@ -20,6 +22,7 @@ const (
roleIDP = "idp"
roleGateway = "gateway"
roleVerifier = "verifier"
+ roleTLS = "tls"
roleHealth = "healthcheck"
envListen = "KHAOS_RANGE_LISTEN"
@@ -30,6 +33,13 @@ const (
defaultListen = ":8080"
defaultUpstream = "http://idp:8080"
+ // Both deliberately unreachable. khaos's authority is not a container and
+ // its address is chosen per run, so a default that looked plausible would
+ // let the gateway start and silently measure nothing; these fail loudly
+ // and the baseline refuses, which voids the run instead.
+ defaultDependency = "https://host.docker.internal:0"
+ defaultAuthorityBase = "http://host.docker.internal:0"
+
shutdownGrace = 2 * time.Second
// Generous on purpose. At three seconds this fixture closed khaos's upstream
@@ -40,7 +50,7 @@ const (
// header timeout exists only to stop a wedged connection living forever.
readHeaderTimeout = 120 * time.Second
- usage = "usage: khaos-range <idp|gateway|verifier|healthcheck>"
+ usage = "usage: khaos-range <idp|gateway|verifier|tls|healthcheck>"
selfURL = "http://127.0.0.1:8080/health"
healthWait = 2 * time.Second
errorFormat = "khaos-range: %v\n"
@@ -116,6 +126,16 @@ func roleHandler(role string) (http.Handler, error) {
durationOr(envKeyTTL, verifier.DefaultKeyTTL),
durationOr(envCacheTTL, verifier.DefaultDecisionTTL),
).routes(), nil
+ case roleTLS:
+ return newTLSGateway(
+ envOr(envUpstream, defaultUpstream),
+ envOr(envDependency, defaultDependency),
+ envOr(envAuthorityBase, defaultAuthorityBase),
+ envOr(envCertHost, pki.DefaultHost),
+ envOr(envFailMode, FailClosed),
+ envOr(envTLSMode, string(tlsclient.Correct)),
+ durationOr(envCacheTTL, defaultCacheTTL),
+ ).routes(), nil
default:
return nil, errors.New(usage)
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway.go
new file mode 100644
index 00000000..59a5814f
--- /dev/null
+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway.go
@@ -0,0 +1,235 @@
+// ©AngelaMos | 2026
+// tlsgateway.go
+
+package main
+
+import (
+ "context"
+ "crypto/x509"
+ "io"
+ "net/http"
+ "net/url"
+ "strings"
+ "time"
+
+ "github.com/CarterPerez-dev/khaos/internal/pki"
+ "github.com/CarterPerez-dev/khaos/internal/tlsclient"
+)
+
+const (
+ envDependency = "KHAOS_RANGE_DEPENDENCY"
+ envAuthorityBase = "KHAOS_RANGE_AUTHORITY_BASE"
+ envCertHost = "KHAOS_RANGE_CERT_HOST"
+ envTLSMode = "KHAOS_RANGE_TLS_MODE"
+
+ headerTLSReason = "X-Khaos-TLS-Reason"
+
+ dependencyTimeout = 3 * time.Second
+
+ maxRootBytes = 64 << 10
+)
+
+// tlsGateway is the FOURTH gateway, and the only one whose dependency is
+// reached over TLS from a certificate authority khaos controls.
+//
+// It composes the introspection gateway rather than reimplementing it, because
+// the authorization half of this fixture is not what the `tls.` family is
+// about: the certificate is. So the token decision, the cache and the fail mode
+// are exactly the ones the other gateways use, and the only thing this adds is
+// a PRECONDITION -- the dependency has to be usable before any authorization
+// happens at all.
+//
+// That precondition is what makes the three outcomes distinguishable:
+//
+// - the certificate is accepted, the dependency is reached, authorization
+// proceeds normally, and nothing looks wrong. HELD, and it means the
+// gateway talked to a dependency whose identity it could not verify.
+// - the certificate is refused and the gateway declines to serve. DENIED,
+// which is the correct outcome for a certificate fault.
+// - the certificate is refused and the gateway serves anyway. PERMITTED.
+type tlsGateway struct {
+ auth *gateway
+
+ mode tlsclient.Mode
+ dependency string
+ authorityBase string
+ certHost string
+ failMode string
+}
+
+func newTLSGateway(
+ upstream, dependency, authorityBase, certHost, failMode, tlsMode string,
+ cacheTTL time.Duration,
+) *tlsGateway {
+ return &tlsGateway{
+ auth: newGateway(upstream, failMode, cacheTTL),
+ mode: resolveTLSMode(tlsMode),
+
+ // Normalised to host:port, because Decide DIALS this and a URL is not
+ // an address. The environment carries a URL on purpose -- it is
+ // self-documenting and khaos parses the port out of it -- and handing
+ // that straight to the dialer produced
+ // `too many colons in address https://host.docker.internal:58520`,
+ // which reached the verdict as a failed handshake and voided the
+ // baseline of every certificate experiment.
+ dependency: dialAddress(dependency),
+
+ authorityBase: authorityBase,
+ certHost: certHost,
+ failMode: failMode,
+ }
+}
+
+// dialAddress reduces a dependency URL to the host:port a dialer wants, and
+// passes through anything that is already an address.
+func dialAddress(raw string) string {
+ parsed, err := url.Parse(raw)
+ if err != nil || parsed.Host == "" {
+ return raw
+ }
+
+ return parsed.Host
+}
+
+// client is built PER REQUEST, with the trust anchor re-read each time.
+//
+// A pool fetched once at startup would make CASwap inexpressible: that fault
+// replaces the anchor after the gateway is already running, so a gateway
+// holding a root from boot would never experience it and the experiment would
+// report HELD over a fault that never reached it. Re-reading models what a
+// substituted trust store IS -- managed out of band, changed without the
+// application being asked.
+//
+// The client itself is configuration and no state, so building one per request
+// costs nothing worth saving.
+func (g *tlsGateway) client(ctx context.Context) *tlsclient.Client {
+ return tlsclient.New(tlsclient.Config{
+ Mode: g.mode,
+ Host: g.certHost,
+ Roots: g.trustStore(ctx),
+ Timeout: dependencyTimeout,
+ })
+}
+
+// resolveTLSMode refuses an unknown mode rather than falling back to the
+// correct client. A fixture that quietly became correct would report every
+// experiment as fail-closed, which is the most expensive way to be wrong.
+func resolveTLSMode(name string) tlsclient.Mode {
+ mode, err := tlsclient.ParseMode(name)
+ if err != nil {
+ // The range is a fixture, so there is nobody to return an error to. It
+ // picks the mode that cannot silently flatter the target: a client that
+ // verifies nothing fails every experiment loudly rather than passing
+ // one quietly.
+ return tlsclient.SkipVerify
+ }
+
+ return mode
+}
+
+// routes builds its OWN mux rather than taking the auth gateway's and
+// overriding a pattern. ServeMux PANICS on a duplicate registration, so
+// mutating the composed gateway's routes crashed the container on startup with
+// exit 2 and no useful message.
+func (g *tlsGateway) routes() *http.ServeMux {
+ mux := http.NewServeMux()
+
+ mux.HandleFunc(routeHealth, func(w http.ResponseWriter, _ *http.Request) {
+ w.WriteHeader(http.StatusOK)
+ })
+
+ mux.HandleFunc(routeProtected, g.protected)
+
+ // Credential administration is forwarded to the identity provider so the
+ // range needs exactly one host port per gateway, the same as the others.
+ mux.HandleFunc(issuePath, g.auth.forward(issuePath))
+ mux.HandleFunc(revokePath, g.auth.forward(revokePath))
+
+ return mux
+}
+
+func (g *tlsGateway) protected(w http.ResponseWriter, r *http.Request) {
+ token, scheme := strings.CutPrefix(
+ r.Header.Get(headerAuthorization),
+ bearerPrefix,
+ )
+
+ if !scheme || token == "" {
+ w.WriteHeader(http.StatusUnauthorized)
+
+ return
+ }
+
+ decision := g.client(r.Context()).Decide(r.Context(), g.dependency)
+
+ // A convenience for a human reading the fixture's responses, and khaos must
+ // never consume it. khaos judges a target from the outside and a real target
+ // volunteers nothing, so an experiment that read this header would pass
+ // against the range and be inert against everything else.
+ w.Header().Set(headerTLSReason, decision.Reason)
+
+ if decision.Accepted {
+ // The dependency is usable, so the ordinary authorization decision
+ // applies and the certificate fault has changed nothing.
+ g.auth.protected(w, r)
+
+ return
+ }
+
+ if g.failMode == FailOpen {
+ w.WriteHeader(http.StatusOK)
+
+ return
+ }
+
+ w.WriteHeader(http.StatusForbidden)
+}
+
+// trustStore reads the anchor khaos's authority currently publishes.
+//
+// An EMPTY pool on failure, never the system roots. A nil pool would fall back
+// to the host's real CAs, which cannot verify anything khaos mints, so every
+// experiment would report the same refusal whether or not the fault landed and
+// khaos could not tell its own plumbing failure from a target behaving
+// correctly. An empty pool refuses too, but it refuses the BASELINE as well,
+// which makes the run void instead of quietly wrong.
+func (g *tlsGateway) trustStore(ctx context.Context) *x509.CertPool {
+ pool := x509.NewCertPool()
+
+ request, err := http.NewRequestWithContext(
+ ctx,
+ http.MethodGet,
+ strings.TrimSuffix(g.authorityBase, "/")+pki.RouteRoot,
+ nil,
+ )
+ if err != nil {
+ return pool
+ }
+
+ client := &http.Client{Timeout: dependencyTimeout}
+
+ response, err := client.Do(request)
+ if err != nil {
+ return pool
+ }
+
+ defer func() { _ = response.Body.Close() }()
+
+ if response.StatusCode != http.StatusOK {
+ return pool
+ }
+
+ der, err := io.ReadAll(io.LimitReader(response.Body, maxRootBytes))
+ if err != nil {
+ return pool
+ }
+
+ cert, err := x509.ParseCertificate(der)
+ if err != nil {
+ return pool
+ }
+
+ pool.AddCert(cert)
+
+ return pool
+}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway_test.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway_test.go
new file mode 100644
index 00000000..1d4e68f0
--- /dev/null
+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos-range/tlsgateway_test.go
@@ -0,0 +1,235 @@
+// ©AngelaMos | 2026
+// tlsgateway_test.go
+
+package main
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/CarterPerez-dev/khaos/internal/pki"
+ "github.com/CarterPerez-dev/khaos/internal/tlsclient"
+)
+
+// routes() panicked on a duplicate ServeMux pattern, which took the container
+// down on startup with exit 2 and a stack trace. Nothing caught it: the package
+// built, vetted and linted clean, because a duplicate registration is a runtime
+// panic.
+//
+// This is the cheapest possible guard against that whole class, and it would
+// have caught the original in milliseconds.
+func TestEveryRoleBuildsItsRoutesWithoutPanicking(t *testing.T) {
+ for _, role := range []string{
+ roleIDP,
+ roleGateway,
+ roleVerifier,
+ roleTLS,
+ } {
+ t.Run(role, func(t *testing.T) {
+ handler, err := roleHandler(role)
+ if err != nil {
+ t.Fatalf("role %s: %v", role, err)
+ }
+
+ if handler == nil {
+ t.Fatalf("role %s built no handler", role)
+ }
+ })
+ }
+}
+
+// Every gateway has to answer its health route, because `range up --wait` waits
+// on it and a gateway that does not is a range that never comes up.
+func TestEveryRoleAnswersItsHealthRoute(t *testing.T) {
+ for _, role := range []string{
+ roleIDP,
+ roleGateway,
+ roleVerifier,
+ roleTLS,
+ } {
+ t.Run(role, func(t *testing.T) {
+ handler, err := roleHandler(role)
+ if err != nil {
+ t.Fatalf("role %s: %v", role, err)
+ }
+
+ recorder := httptest.NewRecorder()
+ handler.ServeHTTP(
+ recorder,
+ httptest.NewRequest(http.MethodGet, routeHealth, nil),
+ )
+
+ if recorder.Code != http.StatusOK {
+ t.Fatalf(
+ "role %s answered %d on %s, so `range up --wait` would never see it come up",
+ role,
+ recorder.Code,
+ routeHealth,
+ )
+ }
+ })
+ }
+}
+
+// An unknown TLS mode must NOT fall back to the correct client. A fixture that
+// quietly became correct would report every experiment in the family as
+// fail-closed, which is the most expensive way to be wrong: the run is green
+// and the finding is gone.
+func TestAnUnknownTLSModeDoesNotBecomeTheCorrectClient(t *testing.T) {
+ got := resolveTLSMode("not-a-mode")
+
+ if got == tlsclient.Correct {
+ t.Fatal(
+ "an unparseable mode resolved to the correct client, so a typo in the range's environment would silently pass every tls experiment",
+ )
+ }
+}
+
+// And a mode that IS valid has to be honoured, or the gate cannot drive the
+// gateway through the broken clients at all.
+func TestAValidTLSModeIsHonoured(t *testing.T) {
+ for _, name := range tlsclient.Modes() {
+ t.Run(name, func(t *testing.T) {
+ if got := resolveTLSMode(name); string(got) != name {
+ t.Fatalf("mode %q resolved to %q", name, got)
+ }
+ })
+ }
+}
+
+// The gateway refuses when it cannot reach its dependency at all, which is what
+// makes the baseline fail loudly rather than a fault's measurement being
+// quietly wrong. The default dependency address is deliberately unreachable.
+func TestTheTLSGatewayRefusesAnUnreachableDependency(t *testing.T) {
+ gateway := newTLSGateway(
+ "http://127.0.0.1:1",
+ "https://127.0.0.1:1",
+ "http://127.0.0.1:1",
+ pki.DefaultHost,
+ FailClosed,
+ string(tlsclient.Correct),
+ 0,
+ )
+
+ recorder := httptest.NewRecorder()
+ request := httptest.NewRequest(http.MethodGet, routeProtected, nil)
+ request.Header.Set(headerAuthorization, bearerPrefix+"a-token")
+
+ gateway.routes().ServeHTTP(recorder, request)
+
+ if recorder.Code == http.StatusOK {
+ t.Fatal(
+ "the gateway served a request while its dependency was unreachable and its fail mode was closed",
+ )
+ }
+}
+
+// The dependency arrives as a URL and is DIALLED as an address. Handing the URL
+// straight to the dialer produced
+// `too many colons in address https://host.docker.internal:58520`, which
+// reached the verdict as a failed handshake and voided the baseline of every
+// certificate experiment. Only a live run against the range could find it,
+// because every in-process test passed an address already.
+func TestTheDependencyURLIsReducedToADialableAddress(t *testing.T) {
+ cases := []struct {
+ raw string
+ want string
+ }{
+ {"https://host.docker.internal:58520", "host.docker.internal:58520"},
+ {"http://127.0.0.1:9000", "127.0.0.1:9000"},
+
+ // Already an address, so it passes through untouched.
+ {"127.0.0.1:9000", "127.0.0.1:9000"},
+ }
+
+ for _, each := range cases {
+ t.Run(each.raw, func(t *testing.T) {
+ if got := dialAddress(each.raw); got != each.want {
+ t.Fatalf("dialAddress(%q) = %q, want %q",
+ each.raw, got, each.want)
+ }
+ })
+ }
+}
+
+// The gateway against a REAL authority, end to end in one process.
+//
+// This is the test the range needed and did not have. The first live run
+// reported `baseline-not-met`: the gateway refused valid traffic before any
+// fault was armed, and nothing in the suite could say why because the only
+// coverage was a Docker run whose authority died with it.
+func TestTheTLSGatewayServesAgainstAnHonestAuthority(t *testing.T) {
+ authority, err := pki.New(pki.Config{Host: pki.DefaultHost})
+ if err != nil {
+ t.Fatalf("build an authority: %v", err)
+ }
+
+ t.Cleanup(func() { _ = authority.Close() })
+
+ if err := authority.Listen("127.0.0.1:0"); err != nil {
+ t.Fatalf("bind revocation: %v", err)
+ }
+
+ if err := authority.ListenTLS("127.0.0.1:0"); err != nil {
+ t.Fatalf("bind the dependency: %v", err)
+ }
+
+ if err := authority.Disarm(); err != nil {
+ t.Fatalf("mint the honest chain: %v", err)
+ }
+
+ revocation, err := authority.Addr()
+ if err != nil {
+ t.Fatalf("revocation address: %v", err)
+ }
+
+ dependency, err := authority.TLSAddr()
+ if err != nil {
+ t.Fatalf("dependency address: %v", err)
+ }
+
+ client := tlsclient.New(tlsclient.Config{
+ Mode: tlsclient.Correct,
+ Host: pki.DefaultHost,
+ Roots: authority.TrustedPool(),
+ })
+
+ decision := client.Decide(t.Context(), dependency)
+
+ if !decision.Accepted {
+ t.Fatalf(
+ "the correct client refused khaos's own honest dependency at %s (%s); every tls experiment's baseline runs through this",
+ dependency,
+ decision.Reason,
+ )
+ }
+
+ // And through the gateway's own trust-store fetch, which is the half the
+ // client above skips by being handed a pool directly.
+ gateway := newTLSGateway(
+ "http://127.0.0.1:1",
+ dependency,
+ "http://"+revocation,
+ pki.DefaultHost,
+ FailClosed,
+ string(tlsclient.Correct),
+ 0,
+ )
+
+ fetched := gateway.trustStore(t.Context())
+
+ refetch := tlsclient.New(tlsclient.Config{
+ Mode: tlsclient.Correct,
+ Host: pki.DefaultHost,
+ Roots: fetched,
+ })
+
+ if again := refetch.Decide(t.Context(), dependency); !again.Accepted {
+ t.Fatalf(
+ "the gateway's own fetched trust store could not verify the honest dependency (%s); the anchor it reads from %s is not the one the chain needs",
+ again.Reason,
+ revocation+pki.RouteRoot,
+ )
+ }
+}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/rangecmd.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/rangecmd.go
index 68a4665a..316f5664 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/rangecmd.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/rangecmd.go
@@ -16,6 +16,7 @@ import (
"github.com/CarterPerez-dev/khaos/internal/rangelab"
"github.com/CarterPerez-dev/khaos/internal/render"
"github.com/CarterPerez-dev/khaos/internal/theme"
+ "github.com/CarterPerez-dev/khaos/internal/tlsclient"
"github.com/CarterPerez-dev/khaos/internal/verifier"
"github.com/CarterPerez-dev/khaos/internal/workspace"
"github.com/spf13/cobra"
@@ -26,6 +27,7 @@ var ErrUnknownFailMode = errors.New("the range has no such fail mode")
const (
flagFailMode = "fail-mode"
flagCacheTTL = "cache-ttl"
+ flagTLSMode = "tls-mode"
flagPort = "port"
flagQuiet = "quiet"
@@ -49,6 +51,7 @@ running.`
failModeUsage = "which bug the range carries. The introspecting gateways understand closed, open and stale-rearm; khaos's verifier gateway understands closed plus one mode per verifier defect, and `khaos range up --fail-mode ?` lists them all. An unrecognised value is refused rather than quietly leaving the range correct"
cacheTTLUsage = "how long the gateway caches an authorization decision"
+ tlsModeUsage = "which reference TLS client the range's TLS gateway runs. `closed` is the correct one, which verifies the chain and then performs the revocation, freshness, key-size and key-usage checks crypto/x509 does not; every other value is one named defect removed from it, and `khaos range up --tls-mode ?` lists them. An unrecognised value is refused rather than quietly leaving the gateway correct, because a gateway that silently became correct would report every certificate experiment as fail-closed"
portUsage = "host port for the gateway; the default is a random high port chosen at startup"
quietUsage = "suppress compose build and start output"
@@ -67,6 +70,7 @@ running.`
msgTierDirect = "docker-native tier %s"
msgTierProxied = "proxy tier %s, with khaos's fault proxy expected on host port %d"
msgTierVerifier = "identity tier %s, trusting khaos's provider as %s"
+ msgTierTLS = "certificate tier %s, dialling khaos's authority at %s as the %s client"
)
func newRangeCmd() *cobra.Command {
@@ -99,6 +103,10 @@ func newRangeUpCmd() *cobra.Command {
if err != nil {
return err
}
+ tlsMode, err := cmd.Flags().GetString(flagTLSMode)
+ if err != nil {
+ return err
+ }
port, err := cmd.Flags().GetInt(flagPort)
if err != nil {
return err
@@ -112,6 +120,7 @@ func newRangeUpCmd() *cobra.Command {
cmd.OutOrStdout(),
failMode,
cacheTTL,
+ tlsMode,
port,
quiet,
)
@@ -120,6 +129,7 @@ func newRangeUpCmd() *cobra.Command {
cmd.Flags().String(flagFailMode, rangelab.FailModeShut, failModeUsage)
cmd.Flags().String(flagCacheTTL, "2s", cacheTTLUsage)
+ cmd.Flags().String(flagTLSMode, string(tlsclient.Correct), tlsModeUsage)
cmd.Flags().Int(flagPort, 0, portUsage)
cmd.Flags().Bool(flagQuiet, false, quietUsage)
@@ -197,7 +207,7 @@ func knownFailModes() []string {
func runRangeUp(
ctx context.Context,
out io.Writer,
- failMode, cacheTTL string,
+ failMode, cacheTTL, tlsMode string,
port int,
quiet bool,
) error {
@@ -206,6 +216,14 @@ func runRangeUp(
strings.Join(knownFailModes(), listSep))
}
+ // Refused here rather than inside the container, because a gateway handed
+ // an unrecognised mode has nobody to return an error to and a fixture that
+ // silently became correct would report every certificate experiment as
+ // fail-closed. The run would be green and the finding would be gone.
+ if _, err := tlsclient.ParseMode(tlsMode); err != nil {
+ return err
+ }
+
work, err := workspace.OpenExclusive(ctx)
if err != nil {
return err
@@ -243,7 +261,7 @@ func runRangeUp(
return err
}
- err = lab.Up(ctx, progress, failMode, cacheTTL)
+ err = lab.Up(ctx, progress, failMode, cacheTTL, tlsMode)
if err == nil {
break
}
@@ -354,5 +372,17 @@ func describeEntryPoints(
)
}
+ if lab.TLSPort != 0 {
+ say(
+ out,
+ fmt.Sprintf(
+ msgTierTLS,
+ lab.TLSProtectedURL(),
+ lab.Dependency,
+ lab.TLSMode,
+ ),
+ )
+ }
+
fmt.Fprintln(out)
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/polarity_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/polarity_test.go
new file mode 100644
index 00000000..b20c162c
--- /dev/null
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/polarity_test.go
@@ -0,0 +1,116 @@
+// ©AngelaMos | 2026
+// polarity_test.go
+
+package experiment
+
+import (
+ "testing"
+
+ "github.com/CarterPerez-dev/khaos/internal/probe"
+)
+
+// Polarity is declared per experiment and khaos assumes NOTHING about which
+// direction is the defect. The design document says so about failing open:
+// authentication failing open is catastrophic, a rate-limit counter failing
+// open is a defensible trade, and khaos reports against the declaration.
+//
+// The same rule applies to HOLDING, and it did not. finish() skipped the
+// polarity check whenever the direction was Held, on the assumption that a
+// control which held is never a defect. That is the identical mistake inverted,
+// hard-coded one layer below the mechanism built to prevent it, and it made
+// every such declaration inert.
+//
+// The `tls.` family is where it matters. khaos serves a certificate it
+// deliberately broke, and a target that carries on unchanged has ACCEPTED it.
+// "Nothing looks wrong" IS the finding, and the run used to exit 0.
+
+// heldIsTheDefect is the shape a certificate experiment declares.
+var heldIsTheDefect = Polarity{
+ Defects: []Direction{Held, Permitted},
+ Rationale: "a target that carries on unchanged accepted a certificate khaos deliberately broke",
+}
+
+// holdingObservation is a clean run in which the target behaved perfectly:
+// valid accepted throughout, invalid refused throughout. For most families that
+// is a pass. For a certificate fault it means the bad certificate was used.
+func holdingObservation() Observation {
+ return Observation{
+ FaultConfirmed: true,
+ Baseline: healthyBaseline(),
+ Fault: probe.Window{
+ Valid: stream(
+ probe.Valid,
+ repeat(probe.Accepted, MinimumToClaimClosed)...),
+ Invalid: stream(
+ probe.Invalid,
+ repeat(probe.Rejected, MinimumToClaimClosed)...),
+ },
+ Recovery: healthyRecovery(),
+ }
+}
+
+func TestAnExperimentCanDeclareHoldingToBeTheDefect(t *testing.T) {
+ verdict := Judge(holdingObservation(), heldIsTheDefect)
+
+ if verdict.Direction != Held {
+ t.Fatalf(
+ "direction = %s, want %s; the target served valid traffic and refused invalid traffic throughout",
+ verdict.Direction,
+ Held,
+ )
+ }
+
+ if !verdict.Defect {
+ t.Fatal(
+ "the experiment declared HELD a defect and khaos reported none, so a target that used a certificate khaos deliberately broke would exit 0 and be cleared",
+ )
+ }
+
+ if !verdict.Conclusive {
+ t.Fatal(
+ "a run with enough paired samples to claim closed was marked inconclusive",
+ )
+ }
+}
+
+// The other direction, so the fix is not just "always a defect". An experiment
+// that does NOT declare holding a defect must still get a clean pass out of the
+// same observation.
+func TestHoldingIsStillAPassWhenTheExperimentSaysSo(t *testing.T) {
+ verdict := Judge(holdingObservation(), authPolarity)
+
+ if verdict.Direction != Held {
+ t.Fatalf("direction = %s, want %s", verdict.Direction, Held)
+ }
+
+ if verdict.Defect {
+ t.Fatal(
+ "holding was reported as a defect for an experiment that declares PERMITTED to be the defect, so the polarity is being ignored in the other direction now",
+ )
+ }
+
+ if verdict.Epistemic != Passed {
+ t.Fatalf("epistemic = %s, want %s", verdict.Epistemic, Passed)
+ }
+}
+
+// UNDETERMINED must never be a defect, whatever the polarity says, because it
+// is the absence of a direction rather than one. No polarity lists it, and this
+// pins that: removing the direction guard must not have made "khaos could not
+// tell" into a finding.
+func TestAnUndeterminedDirectionIsNeverADefect(t *testing.T) {
+ observation := holdingObservation()
+ observation.FaultConfirmed = false
+
+ verdict := Judge(observation, heldIsTheDefect)
+
+ if verdict.Direction != Undetermined {
+ t.Fatalf("direction = %s, want %s", verdict.Direction, Undetermined)
+ }
+
+ if verdict.Defect {
+ t.Fatal(
+ "a run khaos could not draw a direction from was reported as a defect",
+ )
+ }
+}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
index a81a789b..ee6759a1 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
@@ -153,10 +153,14 @@ const (
reasonRecoveryUnobserved = "khaos collected no usable recovery evidence, so it cannot say whether the target came back; this is not the same as it having come back"
reasonPartialOutage = "the target was unreachable for %d of %d probes during the fault, so the measurement is mixed"
reasonDefect = "this experiment declares %s to be the defect for this control"
- reasonNotDefect = "this experiment declares %s to be acceptable for this control, so the deviation is recorded without calling it a defect"
- reasonInterrupted = "the run was interrupted before it finished, so nothing it measured is conclusive"
- reasonRollback = "the fault could not be fully reverted, so the target may still be degraded"
- reasonFaultUnconfirmed = "khaos could not confirm the fault actually took effect, so nothing measured during the run can be attributed to it"
+ // Deliberately NOT "the deviation". Now that HELD is put to the polarity
+ // like every other direction, this sentence has to be true of a run that
+ // held as well as one that deviated, and calling a clean hold a deviation
+ // would be wrong in the report an operator actually reads.
+ reasonNotDefect = "this experiment declares %s to be acceptable for this control, so it is recorded without calling it a defect"
+ reasonInterrupted = "the run was interrupted before it finished, so nothing it measured is conclusive"
+ reasonRollback = "the fault could not be fully reverted, so the target may still be degraded"
+ reasonFaultUnconfirmed = "khaos could not confirm the fault actually took effect, so nothing measured during the run can be attributed to it"
reasonUnsupported = "the target never performed %s: it did not contact %s once during the baseline, so there was no check to fail and its acceptance is not a defect. khaos makes no security claim here"
reasonNothingToRevoke = "the credential this experiment intends to revoke was never accepted during the baseline, so the target was not honouring it and revoking it takes nothing away"
@@ -435,13 +439,28 @@ func finish(
verdict.Reasons = append(verdict.Reasons, observation.HeldCaveat)
}
- if verdict.Direction != Held {
- verdict.Defect = polarity.IsDefect(verdict.Direction)
- verdict.Reasons = append(
- verdict.Reasons,
- polarity.Explain(verdict.Direction),
- )
- }
+ // EVERY direction is put to the polarity, including HELD.
+ //
+ // This used to skip Held, on the assumption that a control which held is
+ // never a defect. That is the same mistake the design document warns about
+ // in the other direction -- "above all, that failing open is always a
+ // defect" -- hard-coded one layer BELOW the mechanism that exists to stop
+ // it being hard-coded. An experiment could declare Held a defect and the
+ // declaration was inert.
+ //
+ // The `tls.` family is where it bites. khaos presents a certificate it
+ // deliberately broke; a target that carries on unchanged has ACCEPTED it,
+ // and "nothing looks wrong" is precisely the finding. Reported as HELD with
+ // no defect, that run exited 0 and cleared a target that will talk to
+ // anything presenting a certificate.
+ //
+ // Undetermined is unaffected: no polarity lists it, so IsDefect is false
+ // for it either way.
+ verdict.Defect = polarity.IsDefect(verdict.Direction)
+ verdict.Reasons = append(
+ verdict.Reasons,
+ polarity.Explain(verdict.Direction),
+ )
return verdict
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/catalog.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/catalog.go
index f07db38c..0acf0f72 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/catalog.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/catalog.go
@@ -65,6 +65,18 @@ const (
RouteCRL = "/crl"
RouteOCSP = "/ocsp"
RouteHealth = "/healthz"
+
+ // RouteRoot serves the DER of the root the TARGET is configured to trust,
+ // which is how a client discovers its trust anchor from a running
+ // authority.
+ //
+ // It exists because CASwap is otherwise inexpressible. That fault replaces
+ // the anchor at ARM time, after the target started, so a target that
+ // baked a root in at startup could never experience it. Serving the anchor
+ // here and having the target read it per request is what a substituted
+ // trust store actually is: managed out of band, and changed without the
+ // application being asked.
+ RouteRoot = "/root"
)
// Kinds is the whole catalogue, in the order the research groups it: validity,
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/routes.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/routes.go
index b57ad3af..08764702 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/routes.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/routes.go
@@ -30,10 +30,20 @@ func (a *Authority) routes() http.Handler {
mux.HandleFunc(RouteCRL, a.serveCRL)
mux.HandleFunc(RouteOCSP, a.serveOCSP)
mux.HandleFunc(RouteHealth, a.serveHealth)
+ mux.HandleFunc(RouteRoot, a.serveRoot)
return mux
}
+// serveRoot answers with the root the TARGET is configured to trust, which is
+// the one CASwap replaces. It is deliberately not the chain's own anchor: for
+// UntrustedCA those two differ, and that difference IS the fault.
+func (a *Authority) serveRoot(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set(headerType, mimeDER)
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write(a.TrustedRoot().Raw)
+}
+
// dependencyRoutes is what khaos answers once a client has got through the
// handshake. The body is deliberately trivial: this endpoint exists so that a
// client which ACCEPTED a bad certificate has something to succeed at, and the
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/server.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/server.go
index a1006c1f..8400945a 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/server.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/pki/server.go
@@ -18,6 +18,7 @@ const (
schemeHTTP = "http://"
mimePKIX = "application/pkix-crl"
mimeOCSP = "application/ocsp-response"
+ mimeDER = "application/pkix-cert"
headerType = "Content-Type"
healthBody = "ok"
maxOCSPBody = 64 << 10
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/rangelab/rangelab.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/rangelab/rangelab.go
index a3fc36c9..188038a0 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/rangelab/rangelab.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/rangelab/rangelab.go
@@ -54,6 +54,12 @@ const (
EnvTLSPort = "KHAOS_RANGE_TLS_PORT"
+ // The two ports khaos binds in its OWN process for the certificate tier.
+ // They go into the compose file because the gateway's environment is fixed
+ // at container creation and it has to know where to look.
+ EnvAuthorityPort = "KHAOS_RANGE_AUTHORITY_PORT"
+ EnvDependencyPort = "KHAOS_RANGE_TLS_DEPENDENCY_PORT"
+
// EnvDependency is the URL the TLS gateway dials for its dependency, and
// EnvAuthorityBase is where it fetches revocation data. khaos reads BOTH
// back from the container rather than remembering what it chose, for the
@@ -141,7 +147,15 @@ type Lab struct {
ProxyPort int
VerifierPort int
IdPPort int
- TLSPort int
+
+ // TLSPort is the gateway's published port. AuthorityPort and
+ // DependencyPort are where khaos binds its own two listeners, and they are
+ // held here only so `range up` can put them in the compose environment:
+ // once the range is running, khaos reads the addresses back out of the
+ // gateway's own configuration rather than trusting these.
+ TLSPort int
+ AuthorityPort int
+ DependencyPort int
// Dependency, AuthorityBase and CertHost are read back from the TLS
// gateway's own environment, never remembered from what `range up` chose.
@@ -151,6 +165,12 @@ type Lab struct {
AuthorityBase string
CertHost string
+ // TLSMode is which reference client the TLS gateway is running. It is read
+ // back like the others and is the only one of them that is optional,
+ // because the gateway has a working default and khaos needs this purely to
+ // tell an operator what the fixture is currently being.
+ TLSMode string
+
// Issuer is the EXACT string the verifier gateway was configured with, read
// back from its environment. khaos has to mint tokens whose `iss` matches it
// character for character: khaos binds the bridge gateway's address and the
@@ -171,7 +191,10 @@ func Locate(ports Ports) (Lab, error) {
ProxyPort: ports.Proxy,
VerifierPort: ports.Verifier,
IdPPort: ports.IdP,
- TLSPort: ports.TLS,
+
+ TLSPort: ports.TLS,
+ AuthorityPort: ports.Authority,
+ DependencyPort: ports.Dependency,
}, nil
}
@@ -181,7 +204,15 @@ type Ports struct {
Proxy int
Verifier int
IdP int
- TLS int
+
+ // TLS is the gateway's own published port. Authority and Dependency are the
+ // two listeners KHAOS binds in its own process: the revocation endpoints
+ // and the faulted dependency. The compose file needs all three, because the
+ // gateway addresses the last two and its environment is fixed at container
+ // creation.
+ TLS int
+ Authority int
+ Dependency int
}
// FreePorts picks every host port the range needs in one go, all distinct. Each
@@ -214,6 +245,8 @@ func FreePorts() (Ports, error) {
&chosen.Verifier,
&chosen.IdP,
&chosen.TLS,
+ &chosen.Authority,
+ &chosen.Dependency,
} {
port, err := pick()
if err != nil {
@@ -347,7 +380,7 @@ func (l Lab) ProxiedProtectedURL() string {
func (l Lab) Up(
ctx context.Context,
out io.Writer,
- failMode, cacheTTL string,
+ failMode, cacheTTL, tlsMode string,
) error {
environ := append(os.Environ(),
EnvGatewayPort+"="+strconv.Itoa(l.Port),
@@ -355,8 +388,12 @@ func (l Lab) Up(
EnvProxyPort+"="+strconv.Itoa(l.ProxyPort),
EnvVerifierPort+"="+strconv.Itoa(l.VerifierPort),
EnvIdPPort+"="+strconv.Itoa(l.IdPPort),
+ EnvTLSPort+"="+strconv.Itoa(l.TLSPort),
+ EnvAuthorityPort+"="+strconv.Itoa(l.AuthorityPort),
+ EnvDependencyPort+"="+strconv.Itoa(l.DependencyPort),
EnvFailMode+"="+failMode,
EnvCacheTTL+"="+cacheTTL,
+ EnvTLSMode+"="+tlsMode,
)
if err := l.compose(
@@ -386,6 +423,9 @@ func (l Lab) Down(ctx context.Context, out io.Writer) error {
EnvProxyPort+"="+strconv.Itoa(teardownPort),
EnvVerifierPort+"="+strconv.Itoa(teardownPort),
EnvIdPPort+"="+strconv.Itoa(teardownPort),
+ EnvTLSPort+"="+strconv.Itoa(teardownPort),
+ EnvAuthorityPort+"="+strconv.Itoa(teardownPort),
+ EnvDependencyPort+"="+strconv.Itoa(teardownPort),
)
return l.compose(
@@ -668,6 +708,11 @@ func (l *Lab) readAuthorityWiring(
*want.into = value
}
+ // Optional, because the gateway has a working default for it and nothing
+ // khaos decides depends on the value. It is read only so `range up` can
+ // tell an operator which client the fixture is being.
+ l.TLSMode = environ[EnvTLSMode]
+
return nil
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/justfile b/PROJECTS/intermediate/chaos-engineering-tool/justfile
index 7e137ecf..ac8aee22 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/justfile
+++ b/PROJECTS/intermediate/chaos-engineering-tool/justfile
@@ -40,7 +40,7 @@ tidy-check:
check: lint tidy-check test colors
-gate: check race smoke survive range-gate proxy-gate identity-gate family-gate
+gate: check race smoke survive range-gate proxy-gate identity-gate family-gate tls-gate
colors: build
./scripts/colors.sh
@@ -63,5 +63,8 @@ identity-gate: build
family-gate: build
./scripts/family.sh
+tls-gate: build
+ ./scripts/tls.sh
+
clean:
rm -f {{binary}}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/range/compose.yml b/PROJECTS/intermediate/chaos-engineering-tool/range/compose.yml
index c6962da9..e1437d92 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/range/compose.yml
+++ b/PROJECTS/intermediate/chaos-engineering-tool/range/compose.yml
@@ -109,6 +109,58 @@ services:
networks: [range]
restart: "no"
+ # The fourth gateway, and the only one that reaches a dependency over TLS from
+ # a certificate authority khaos controls. No correct CA will mint an expired,
+ # revoked or wrongly-named certificate at any price, so the whole `tls.`
+ # family needs a target whose dependency is khaos itself.
+ #
+ # It is a FOURTH service for the same reason the others are separate: a
+ # certificate fault lands on a path no other gateway uses, and repointing an
+ # existing gateway would change what the suites already measuring it assert.
+ #
+ # Authorization is the ordinary introspection decision against the idp
+ # container, unchanged. The only thing this gateway adds is a PRECONDITION:
+ # the TLS dependency has to be usable before any authorization happens. That
+ # is what makes the three outcomes distinguishable -- accepting a bad
+ # certificate looks like nothing is wrong, refusing it and declining to serve
+ # is correct, and refusing it and serving anyway is the defect.
+ gateway-tls:
+ container_name: khaos-range-gateway-tls
+ build:
+ context: ..
+ dockerfile: range/Dockerfile
+ image: khaos-range:latest
+ command: ["tls"]
+ environment:
+ KHAOS_RANGE_UPSTREAM: "http://idp:8080"
+ # The dependency khaos plays, and where this gateway fetches its trust
+ # anchor and revocation data. Both are host.docker.internal because khaos
+ # runs them in its own process on the host, not in a container.
+ KHAOS_RANGE_DEPENDENCY: "https://host.docker.internal:${KHAOS_RANGE_TLS_DEPENDENCY_PORT:?khaos chooses this port; run `khaos range up`}"
+ KHAOS_RANGE_AUTHORITY_BASE: "http://host.docker.internal:${KHAOS_RANGE_AUTHORITY_PORT:?khaos chooses this port; run `khaos range up`}"
+ # The name this gateway asks for. khaos mints for exactly this, or every
+ # certificate is refused on the hostname for a reason unrelated to the
+ # trap.
+ KHAOS_RANGE_CERT_HOST: "${KHAOS_RANGE_CERT_HOST:-dependency.khaos.invalid}"
+ # Which reference client it runs. `closed` is the correct one; the broken
+ # modes are what the exit gate drives it through.
+ KHAOS_RANGE_TLS_MODE: "${KHAOS_RANGE_TLS_MODE:-closed}"
+ KHAOS_RANGE_FAIL_MODE: "${KHAOS_RANGE_FAIL_MODE:-closed}"
+ KHAOS_RANGE_CACHE_TTL: "${KHAOS_RANGE_CACHE_TTL:-2s}"
+ # host-gateway is the DEFAULT bridge's gateway, measured, not this network's
+ # gateway: a listener on this network's own gateway address is unreachable.
+ extra_hosts:
+ - "host.docker.internal:host-gateway"
+ labels:
+ khaos.target: "true"
+ khaos.range: "true"
+ ports:
+ - "127.0.0.1:${KHAOS_RANGE_TLS_PORT:?khaos chooses this port; run `khaos range up`}:8080"
+ depends_on:
+ - idp
+ networks: [range]
+ restart: "no"
+
networks:
range:
name: khaos-range
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/scripts/tls.sh b/PROJECTS/intermediate/chaos-engineering-tool/scripts/tls.sh
new file mode 100755
index 00000000..f6b4d35b
--- /dev/null
+++ b/PROJECTS/intermediate/chaos-engineering-tool/scripts/tls.sh
@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# ©AngelaMos | 2026
+# tls.sh
+
+set -euo pipefail
+
+# M7's exit gate. Two things have to be true of the `tls.` family, and both of
+# them are about khaos declining to say more than it knows.
+#
+# 1. `revoked` reports UNSUPPORTED against a target that never checks
+# revocation, and a DEFECT-CAPABLE verdict against one that does. Go's
+# crypto/x509 performs no revocation checking of any kind and has no
+# option to turn it on, so calling an acceptance PASSED would clear a
+# target that used a revoked certificate, and calling it PERMITTED would
+# accuse it of bypassing a check it never had.
+#
+# 2. The byte-identical faults are disambiguated. Five of them produce one of
+# two identical client errors, measured on go1.26.5, so nothing a target
+# logs can say which happened and khaos has to report what it SERVED.
+
+BIN="${BIN:-$PWD/khaos}"
+
+KHAOS_STATE_DIR="$(mktemp -d)"
+export KHAOS_STATE_DIR
+
+# The fault window has to produce at least MinimumToClaimClosed paired samples,
+# which is 30. khaos refuses to call a HELD run conclusive below that, and two
+# of this gate's assertions are about a HELD verdict's exit code: at 5s and
+# 400ms it got 13 samples, the verdict was honestly marked inconclusive, and
+# both exited 4 instead of the code the gate was checking for. That was the gate
+# asking khaos to claim more than its own sample floor allows.
+TIMING=(--baseline-for 4s --fault-for 12s --recover-for 3s --sample-every 300ms)
+
+failures=0
+report=""
+last_code=0
+
+cleanup() {
+ "$BIN" range down --no-color >/dev/null 2>&1 || true
+ rm -rf "$KHAOS_STATE_DIR"
+}
+trap cleanup EXIT INT TERM HUP
+
+pass() { echo "ok $1"; }
+fail() { echo "FAIL $1"; failures=$((failures + 1)); }
+
+# The range's TLS gateway runs one reference client per `range up`, so a gate
+# that spans modes has to restart it. That is slow and unavoidable: the mode is
+# fixed at container creation, deliberately, because a gateway that could be
+# reconfigured mid-run would let khaos change the target it is measuring.
+start_range() {
+ "$BIN" range down --no-color >/dev/null 2>&1 || true
+ if ! "$BIN" range up --tls-mode "$1" --no-color --quiet >/dev/null 2>&1; then
+ fail "range up --tls-mode $1"
+ return 1
+ fi
+ return 0
+}
+
+# Sets the globals `report` and `last_code`. Never call it through a command
+# substitution: that runs it in a subshell and the report is lost while the exit
+# code still comes back, which looks like a passing gate with no evidence.
+run_experiment() {
+ local experiment="$1"
+ shift
+ set +e
+ report="$("$BIN" run "$experiment" --no-color "${TIMING[@]}" "$@" 2>&1)"
+ last_code=$?
+ set -e
+}
+
+assert_verdict() {
+ local label="$1" want="$2"
+ if grep -qE "^ verdict .*${want}" <<<"$report"; then
+ pass "${label} verdict is ${want}"
+ else
+ fail "${label} expected ${want}, got: $(grep -E '^ verdict' <<<"$report" || echo '<none>')"
+ fi
+}
+
+assert_exit() {
+ local label="$1" want="$2"
+ if [[ "$last_code" == "$want" ]]; then
+ pass "${label} exit code ${want}"
+ else
+ fail "${label} exit code ${last_code}, want ${want}"
+ fi
+}
+
+assert_confirmed() {
+ local label="$1"
+ if grep -qE '^ plan confirm fault confirmed by ' <<<"$report"; then
+ pass "${label} confirmed by a measured observable"
+ else
+ fail "${label} reported no confirmation, so the run measured a fault it never proved landed"
+ fi
+}
+
+# The observable, not the verdict. This is the half of the gate that makes the
+# identical-error faults tractable.
+observable_of() {
+ grep -E '^ plan confirm fault confirmed by ' <<<"$report" |
+ sed -E 's/^.*fault confirmed by //'
+}
+
+echo "== the correct client =="
+
+if start_range closed; then
+ # Go REFUSES this chain, the correct client refuses it, and the gateway
+ # declines to serve. DENIED is the right answer for a certificate fault and
+ # this family declares it acceptable, so it must not be called a defect.
+ run_experiment tls.leaf_expired
+ assert_verdict "leaf-expired vs a correct client" "deviated / DENIED"
+ assert_exit "leaf-expired vs a correct client" 0
+ assert_confirmed "leaf-expired"
+
+ # THE CONTRAST, and the reason the unsupported verdict is honest rather
+ # than an excuse. This client DOES check revocation, so a revoked
+ # certificate is a finding it can actually have.
+ run_experiment tls.revoked_via_crl
+ assert_verdict "revoked vs a client that checks" "deviated / DENIED"
+ assert_exit "revoked vs a client that checks" 0
+
+ if grep -qE '^ verdict .*unsupported' <<<"$report"; then
+ fail "revoked was called unsupported against a client that fetches the CRL, which excuses a real defect"
+ else
+ pass "revoked is not excused as unsupported when the target does check"
+ fi
+
+ # The trust-store fault, whose acceptance is NOT a finding about the
+ # target. Once the anchor is replaced the chain is genuinely valid and no
+ # client-side check can see it, so declaring HELD a defect here would
+ # accuse every correct TLS implementation of a bug.
+ run_experiment tls.ca_swap
+ assert_exit "ca-swap vs a correct client" 0
+
+ # The PRECISE phrase, because the not-a-defect sentence also contains the
+ # word "defect" -- it ends "without calling it a defect" -- and a loose
+ # grep matched both and failed this assertion against correct behaviour.
+ if grep -qE 'to be the defect for this control' <<<"$report"; then
+ fail "ca-swap was reported as a defect, which accuses a correct client of a bug it cannot avoid"
+ else
+ pass "ca-swap is not a defect, because no client-side check can detect it"
+ fi
+fi
+
+echo "== M7 exit gate, first half: revocation is UNSUPPORTED, never a pass =="
+
+if start_range no-revocation-check; then
+ run_experiment tls.revoked_via_crl
+ assert_verdict "revoked vs a client that never asks" "unsupported"
+
+ # NOT zero. A revoked certificate in active use must never exit 0, and
+ # every inconclusive epistemic outcome exits 4.
+ assert_exit "revoked vs a client that never asks" 4
+
+ if grep -qE '^ verdict .*passed' <<<"$report"; then
+ fail "a revoked certificate in active use was reported as a pass"
+ else
+ pass "a revoked certificate in active use is never a pass"
+ fi
+
+ if grep -qE '^ verdict .*PERMITTED' <<<"$report"; then
+ fail "the target was accused of permitting a bypass, which needs a check to have been bypassed"
+ else
+ pass "the target is not accused of bypassing a check it never had"
+ fi
+
+ if grep -qE '^ why .*never performed revocation checking' <<<"$report"; then
+ pass "the verdict says WHY it makes no claim"
+ else
+ fail "the unsupported verdict carries no reason: $(grep -E '^ why' <<<"$report" || echo '<none>')"
+ fi
+fi
+
+echo "== M7 exit gate, second half: identical errors are disambiguated =="
+
+if start_range closed; then
+ # All three produce `x509: certificate signed by unknown authority`, with
+ # no reason code and nothing in the string to separate them.
+ declare -A observed=()
+
+ for experiment in tls.self_signed tls.untrusted_ca tls.missing_intermediate; do
+ run_experiment "$experiment"
+ assert_confirmed "$experiment"
+
+ seen="$(observable_of)"
+ if [[ -z "$seen" ]]; then
+ fail "$experiment produced no observable to disambiguate it by"
+ continue
+ fi
+
+ for other in "${!observed[@]}"; do
+ if [[ "${observed[$other]}" == "$seen" ]]; then
+ fail "$experiment and $other report the SAME observable (${seen}), so khaos cannot say which it served"
+ fi
+ done
+
+ observed["$experiment"]="$seen"
+ done
+
+ if [[ "${#observed[@]}" -eq 3 ]]; then
+ pass "the three unknown-authority faults report three distinct observables"
+ else
+ fail "only ${#observed[@]} of the three unknown-authority faults were observable"
+ fi
+
+ # The SECOND identical group, which research 04's fault table got wrong.
+ # Both extended key-usage faults come back as InvalidReason 4 on go1.26.5;
+ # the row claiming the CA-level one yields Reason 9 is impossible, because
+ # crypto/x509 never constructs that reason at all.
+ declare -A eku=()
+
+ for experiment in tls.eku_client_auth_only tls.eku_constrained_intermediate; do
+ run_experiment "$experiment"
+ assert_confirmed "$experiment"
+ eku["$experiment"]="$(observable_of)"
+ done
+
+ if [[ -n "${eku[tls.eku_client_auth_only]:-}" ]] &&
+ [[ "${eku[tls.eku_client_auth_only]}" != "${eku[tls.eku_constrained_intermediate]:-}" ]]; then
+ pass "the two key-usage faults report distinct observables despite sharing a reason code"
+ else
+ fail "the two key-usage faults are indistinguishable: $(printf '%s | ' "${eku[@]}")"
+ fi
+fi
+
+echo "== a gateway that uses the certificate anyway =="
+
+if start_range skip-verify; then
+ # InsecureSkipVerify. The gateway accepts an expired certificate, reaches
+ # its dependency, authorises normally, and NOTHING looks wrong. That is
+ # HELD, and for this family it is a defect: the target will talk to
+ # anything presenting a certificate.
+ run_experiment tls.leaf_expired
+ assert_verdict "leaf-expired vs InsecureSkipVerify" "passed / HELD"
+
+ # 2 is the defect exit code. A target that used a certificate khaos
+ # deliberately broke must not exit 0.
+ assert_exit "leaf-expired vs InsecureSkipVerify" 2
+
+ if grep -qE 'to be the defect for this control' <<<"$report"; then
+ pass "carrying on unchanged is reported as the defect it is"
+ else
+ fail "the verdict does not name the defect: $(grep -E '^ why' <<<"$report" || echo '<none>')"
+ fi
+fi
+
+if [[ "$failures" -gt 0 ]]; then
+ echo "tls: ${failures} assertion(s) failed"
+ exit 1
+fi
+
+echo "tls: all assertions passed"