importguard

Documentation

Overview

Package importguard provides test helpers for enforcing import boundaries.

Import guards are AST-based tests that enforce security boundaries by detecting forbidden imports or risky function calls at test time.

Example usage:

func TestNoForbiddenImports(t *testing.T) {
    importguard.AssertNoImport(t, "internal/catalog",
        "Catalog data is for discovery only")
}

Index

• func AssertNoImport(t *testing.T, forbiddenImport, reason string)
• func AssertNoImportRepoWide(t *testing.T, forbiddenImport string, opts RepoWideOptions, reason string)
• func AssertNoImports(t *testing.T, forbiddenImports []string, reason string)
• func AssertNoImportsInPackages(t *testing.T, packages []string, forbiddenImports []string, ...)
• func AssertNoRiskyCalls(t *testing.T, riskyCalls []RiskyCall)
• func AssertNoRiskyCallsInPackages(t *testing.T, packages []string, riskyCalls []RiskyCall, ...)
• func AssertRequiresImport(t *testing.T, triggerImport, requiredImport, reason string)
• func RepoRoot(t *testing.T) string
• type PackageScanOptions
• type RepoWideOptions
• type RiskyCall

Functions

func AssertNoImport

func AssertNoImport(t *testing.T, forbiddenImport, reason string)

AssertNoImport fails the test if any non-test Go file in the current package imports a path containing the forbidden string.

Use this to enforce security boundaries where a package must not depend on another package (e.g., execution packages must not import catalog).

func AssertNoImportRepoWide

func AssertNoImportRepoWide(t *testing.T, forbiddenImport string, opts RepoWideOptions, reason string)

AssertNoImportRepoWide scans the entire repository for a forbidden import.

Use this for repo-wide security boundaries like "only safeyaml can import yaml.v3".

func AssertNoImports

func AssertNoImports(t *testing.T, forbiddenImports []string, reason string)

AssertNoImports fails the test if any non-test Go file in the current package imports a path containing any of the forbidden strings.

Use this when multiple import boundaries need to be enforced.

func AssertNoImportsInPackages

func AssertNoImportsInPackages(t *testing.T, packages []string, forbiddenImports []string, opts PackageScanOptions, reason string)

AssertNoImportsInPackages scans specific packages for forbidden imports.

Use this for execution-boundary checks like "dispatch must not import catalog".

func AssertNoRiskyCalls

func AssertNoRiskyCalls(t *testing.T, riskyCalls []RiskyCall)

AssertNoRiskyCalls fails the test if any non-test Go file in the current package calls any of the specified risky functions.

Use this to enforce that security-sensitive packages use safe wrappers instead of raw stdlib functions.

func AssertNoRiskyCallsInPackages

func AssertNoRiskyCallsInPackages(t *testing.T, packages []string, riskyCalls []RiskyCall, opts PackageScanOptions)

AssertNoRiskyCallsInPackages scans specific packages for risky function calls.

Use this for security-sensitive operations like "component/* must use safefile".

func AssertRequiresImport

func AssertRequiresImport(t *testing.T, triggerImport, requiredImport, reason string)

AssertRequiresImport fails if a package uses a given import but not a required companion import.

Use this to ensure packages that use raw exec also import execsafe, or similar security wrapper requirements.

func RepoRoot

func RepoRoot(t *testing.T) string

RepoRoot finds the repository root by looking for go.mod. Returns empty string if not found.

Types

type PackageScanOptions

type PackageScanOptions struct {
	// Recursive walks subdirectories (default: false).
	Recursive bool

	// ExemptFiles lists specific files to skip (relative to repo root).
	ExemptFiles []string

	// ExemptPackages lists packages to skip entirely.
	ExemptPackages []string
}

PackageScanOptions configures package-specific scanning.

type RepoWideOptions

type RepoWideOptions struct {
	// AllowedPackages lists packages exempt from the check (relative to repo root).
	AllowedPackages []string

	// IncludeTests also scans _test.go files (default: false).
	IncludeTests bool

	// WarnOnly logs violations but doesn't fail the test (default: false).
	WarnOnly bool

	// ExactMatch requires exact import path match (default: false - uses Contains).
	ExactMatch bool

	// OnlyPackages limits scanning to these packages (for focused audits).
	// If empty, scans entire repo.
	OnlyPackages []string
}

RepoWideOptions configures repo-wide import scanning.

type RiskyCall

type RiskyCall struct {
	Package   string   // Package identifier (e.g., "os")
	Functions []string // Function names to flag (e.g., "Create", "WriteFile")
	Reason    string   // Why this is risky
}

RiskyCall defines a package and set of function names that are risky to use.