feat(testing/fipsscan): extend the fipsscan package to improve FIPS auto-audit

[macdewee]

TL;DR

Unifying the way we test binaries/modules for FIPS compliance. Aim was to just import this module, prepare list of known violations and Voilà. Example usages:

• feat(fips): add per-module FIPS compliance gate and update elastic-agent-libs fleet-server#7395
• Add FIPS 140-3 compliance test for beat binaries beats#52036
• Add FIPS x/crypto compliance test for EDOT binary elastic-agent#15600

vibe-coded. This PR is bigger than I expected and mostly resonate about resolving the dependencies between binary, component and library which violates the FIPS

Iterated few times to give satisfying results and minimal usage in fleet-server, elastic-agent and beats repo

Summary

Extend testing/fipsscan package — a shared Go testing helper for auditing FIPS 140-3 compliance of Go modules. It scans dependency trees for imports of known non-FIPS crypto libraries and reports violations via the standard testing.T interface.

The package is guarded by //go:build requirefips so it compiles and incurs zero overhead outside FIPS-focused test runs (go test -tags requirefips).

Motivation

FIPS compliance needs to be enforced across multiple Elastic repositories (elastic-agent, otel-collector-components, beats, …). Without a shared helper, each repo would reimplement violation detection independently and inconsistently. This package provides a single place to maintain the list of known non-FIPS libraries and a stable API for documenting accepted violations per component.

API

CheckModule — the main entry point

fipsscan.CheckModule(t,
    []string{"./..."},   // patterns passed to go list
    skipBinaries,        // non-shipped binaries to exclude
    nil,                 // extra forbidden prefixes beyond the baseline
    map[string]map[string][]fipsscan.KnownViolation{
        // outer key: binary import path or module-root prefix; "" = all binaries
        "github.com/elastic/elastic-agent": {
            // inner key: component — package path or module-root prefix in the chain
            "github.com/elastic/gokrb5/v8": {
                {Imported: "github.com/jcmturner/gofork", Reason: "Elastic gokrb5 fork depends on jcmturner gofork"},
                {Imported: "golang.org/x/crypto/md4",     Reason: "Kerberos RC4-HMAC requires MD4"},
            },
            "github.com/foxboron/go-tpm-keyfiles": {
                {Imported: "golang.org/x/crypto/chacha20poly1305", Reason: "TPM key parsing uses ChaCha20"},
            },
        },
    },
)

CheckModule reports undocumented violations via t.Errorf and flags stale entries (violations that no longer exist) so the map stays current.

Key design points

• Component-oriented config. The two-level map (binary → component → violations) lets you document which part of the binary owns each violation. The component key is any package path or module-root prefix appearing in the import chain from the binary down to the direct importer — use a broad prefix like "github.com/twmb/franz-go" to cover all violations from that library in one entry, or an exact package for precision.
• Prefix matching. Both the outer binary key and KnownViolation.Imported support module-root prefixes. {Imported: "github.com/jcmturner/gokrb5/v8"} matches any gokrb5/v8/… sub-package. Binary key "github.com/elastic/elastic-agent" matches any binary under that module root.
• Stale detection. Entries whose violation no longer exists are flagged stale. Entries whose component was removed from the dependency tree entirely are silently skipped (not a stale error — the problem went away).
• Library module support. Falls back to flat violation detection (no binary attribution) when the scanned module has no package main entries.
• skipBinaries. Dev tools, test helpers, and non-shipped binaries can be excluded from the scan and from stale detection.
• Single go list pass. All patterns are resolved in one subprocess invocation regardless of how many binaries match.

Lower-level functions

// Per-binary scan with BFS attribution; Violation.Binary is set.
violations, importGraph := fipsscan.ScanBinaries(t, []string{"./cmd/..."}, skipBinaries, nil)

// Flat scan; Violation.Binary is empty.
violations, importGraph := fipsscan.Scan(t, "./...", nil)

// Display helpers.
chain := fipsscan.ShortestChain(v.Binary, v.Importer, importGraph)
fmt.Println(fipsscan.FormatChain(append(chain, v.Imported)))

Baseline forbidden-package list

Ten third-party crypto libraries are checked by default (all exported as constants):

Constant	Module prefix
XCrypto	golang.org/x/crypto/
JcmturnerGokrb5	github.com/jcmturner/gokrb5/
JcmturnerAescts	github.com/jcmturner/aescts/
JcmturnerGofork	github.com/jcmturner/gofork/
XdgGoPbkdf2	github.com/xdg-go/pbkdf2
ProtonMailGoCrypto	github.com/ProtonMail/go-crypto/
CloudflareCircl	github.com/cloudflare/circl/
AzureGoNtlmssp	github.com/Azure/go-ntlmssp
YoumarkPkcs8	github.com/youmark/pkcs8
FilippioIO	filippo.io/

Usage convention

The recommended filename is fips_compliance_test.go and function name TestFIPSCompliance in every adopting module. This makes ecosystem-wide auditing trivial:

grep -rl 'TestFIPSCompliance' .          # find all modules with a FIPS test
go test -tags requirefips -run TestFIPSCompliance ./...  # run them all

Test plan

• go build -tags requirefips ./testing/fipsscan/ passes
• go test -tags requirefips ./testing/fipsscan/ passes (unit tests for ShortestChain, FormatChain, matchesBinaryKey, isForbidden, moduleRoot)
• Validate against real usage: drosiek-fips branch in elastic-agent uses this package for elastic-agent and edot binaries

[kruskall]

FIPS compliance needs to be enforced across multiple Elastic repositories (elastic-agent, otel-collector-components, beats, …). Without a shared helper, each repo would reimplement violation detection independently and inconsistently.

I'm not convinced this is enough to justify this. Downstream components have different dependencies and they need to constantly audit their dependency graph (ideally even without fips). It would be more surprising if they all share the same forbidden packages.

elastic-agent-libs is a library, we shouldn't leak (more) implementation details of downstream consumers in here (despite how bad it already is). Trying to maintain a centralized list will add noise a maintenance burden to everyone.

[kruskall]

This is excluding a whole namespace which looks too broad :(

[kruskall]

consumers of this library use different tags so this needs to be configurable to work reliably

[belimawr]

+1

[belimawr]

So far I mostly vibe-reviewed it, my clanker found one issue:

  • High: CheckModule can suppress a violation for a component that is not reachable from the scanned binary. markKnown only checks that the component can reach the importer (componentCanReach), but never verifies that
    the component is reachable from v.Binary:
    • testing/fipsscan/fipsscan.go:462-468
    • testing/fipsscan/fipsscan.go:540-552

  Because component reachability is computed across the entire merged import graph, an unrelated component elsewhere in the module can document/suppress a violation from another binary whenever both eventually reach the
  same importer. This silently weakens the FIPS audit and contradicts the API documentation requiring both directions of reachability.

  markKnown should additionally verify that the component key matches a package reachable from the violation’s binary (except library-mode scans where Binary == ""). Add a regression test covering two binaries sharing an
  importer, with the known component reachable only from the other binary.

  The tagged package tests and PR CI pass, but they do not exercise this cross-binary attribution case.

Could you take a look at it? It seems legit. After that I'll do a more in-depth review.

[belimawr]

+1

[infra-vault-gh-plugin-prod]

💚 Build Succeeded

• Buildkite Build
• Commit: 7a78883

History

• 💚 Build #1148 succeeded cef9e07
• 💚 Build #1147 succeeded 54519f1
• 💚 Build #1146 succeeded f4b911d
• 💚 Build #1145 succeeded d3385ba
• 💚 Build #1144 succeeded 14cf279
• 💚 Build #1143 succeeded 9a8b95b

[macdewee]

@kruskall @belimawr I changed the approach to be fully stateless across projects and move the responsibility of providing the list of dependencies and tags on the caller's side