fix(test): scan aliased and dot-imported os environment reads (#3505)

Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Alassane
2026-09-14 09:45:14 -04:00
committed by GitHub
parent cc6077fd7f
commit 4fde4f7cb4
5 changed files with 378 additions and 176 deletions
@@ -1,14 +1,10 @@
package github
import (
"go/ast"
"go/parser"
"go/token"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
"github.com/kandev/kandev/internal/testutil"
)
// ambientGitHubEnvVars lists every environment variable this package reads in
@@ -55,165 +51,5 @@ func TestAmbientGitHubEnvIsClearedForTests(t *testing.T) {
// a new os.Getenv/os.LookupEnv call that ambientGitHubEnvVars does not cover,
// so the scrub cannot silently fall behind the code it protects.
func TestAmbientGitHubEnvCoversEveryPackageEnvRead(t *testing.T) {
fileSet := token.NewFileSet()
files := parseNonTestSources(t, fileSet)
constants := stringConstants(files)
covered := make(map[string]bool, len(ambientGitHubEnvVars))
for _, name := range ambientGitHubEnvVars {
covered[name] = true
}
for _, file := range files {
for _, call := range envReadCalls(file) {
name, resolved := resolveEnvName(call, constants)
if !resolved {
t.Errorf("%s: environment variable name is not a string literal or a constant of this "+
"package; a constant imported from elsewhere needs resolveEnvName taught about it",
fileSet.Position(call.Pos()))
continue
}
if !covered[name] {
t.Errorf("%s: %s is read in non-test code but missing from ambientGitHubEnvVars",
fileSet.Position(call.Pos()), name)
}
}
}
}
func TestEnvReadCallsResolvesOSImportAlias(t *testing.T) {
fileSet := token.NewFileSet()
file, err := parser.ParseFile(fileSet, "aliased.go", `package github
import stdos "os"
func readToken() string {
return stdos.Getenv("GH_TOKEN")
}
`, 0)
if err != nil {
t.Fatalf("parse aliased source: %v", err)
}
if got := len(envReadCalls(file)); got != 1 {
t.Fatalf("envReadCalls() found %d calls, want 1", got)
}
}
// parseNonTestSources parses every production file of the package, which is
// the code whose environment reads the scrub has to keep up with.
func parseNonTestSources(t *testing.T, fileSet *token.FileSet) []*ast.File {
t.Helper()
paths, err := filepath.Glob("*.go")
if err != nil {
t.Fatalf("list sources: %v", err)
}
var files []*ast.File
for _, path := range paths {
if strings.HasSuffix(path, "_test.go") {
continue
}
file, parseErr := parser.ParseFile(fileSet, path, nil, 0)
if parseErr != nil {
t.Fatalf("parse %s: %v", path, parseErr)
}
files = append(files, file)
}
if len(files) == 0 {
t.Fatal("no non-test sources found in the package directory")
}
return files
}
// stringConstants maps package-level string constant names to their values so
// env reads written as os.Getenv(envSomeConst) resolve to the variable name.
func stringConstants(files []*ast.File) map[string]string {
constants := make(map[string]string)
for _, file := range files {
for _, decl := range file.Decls {
genDecl, ok := decl.(*ast.GenDecl)
if !ok || genDecl.Tok != token.CONST {
continue
}
for _, spec := range genDecl.Specs {
valueSpec, ok := spec.(*ast.ValueSpec)
if !ok {
continue
}
for i, name := range valueSpec.Names {
if i >= len(valueSpec.Values) {
continue
}
if value, ok := literalString(valueSpec.Values[i]); ok {
constants[name.Name] = value
}
}
}
}
}
return constants
}
func osPackageName(file *ast.File) (string, bool) {
for _, spec := range file.Imports {
path, err := strconv.Unquote(spec.Path.Value)
if err != nil || path != "os" {
continue
}
if spec.Name != nil {
return spec.Name.Name, spec.Name.Name != "_" && spec.Name.Name != "."
}
return "os", true
}
return "", false
}
// envReadCalls collects every os.Getenv / os.LookupEnv call in a file.
func envReadCalls(file *ast.File) []*ast.CallExpr {
osName, ok := osPackageName(file)
if !ok {
return nil
}
var calls []*ast.CallExpr
ast.Inspect(file, func(node ast.Node) bool {
call, ok := node.(*ast.CallExpr)
if !ok || len(call.Args) != 1 {
return true
}
selector, ok := call.Fun.(*ast.SelectorExpr)
if !ok {
return true
}
pkgIdent, ok := selector.X.(*ast.Ident)
if !ok || pkgIdent.Name != osName {
return true
}
if selector.Sel.Name == "Getenv" || selector.Sel.Name == "LookupEnv" {
calls = append(calls, call)
}
return true
})
return calls
}
func resolveEnvName(call *ast.CallExpr, constants map[string]string) (string, bool) {
if value, ok := literalString(call.Args[0]); ok {
return value, true
}
ident, ok := call.Args[0].(*ast.Ident)
if !ok {
return "", false
}
value, ok := constants[ident.Name]
return value, ok
}
func literalString(expr ast.Expr) (string, bool) {
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
return "", false
}
value, err := strconv.Unquote(lit.Value)
if err != nil {
return "", false
}
return value, true
testutil.AssertEnvReadsCovered(t, ambientGitHubEnvVars, nil)
}
+54 -9
View File
@@ -3,8 +3,10 @@ package testutil
import (
"fmt"
"go/ast"
"go/importer"
"go/parser"
"go/token"
"go/types"
"path/filepath"
"strconv"
"strings"
@@ -19,9 +21,9 @@ import (
// scrub against silently falling behind new environment reads.
//
// os.Getenv and os.LookupEnv are always treated as environment reads. They are
// matched on the literal identifier os, so a file that imports os under an
// alias or through a dot import is not scanned; no file in this repository
// does either, and a review of one that did would be the place to catch it.
// matched by the file-local import name bound to the os package. Dot imports
// are matched by bare Getenv and LookupEnv calls. Blank imports are not scanned
// because they name no package.
// Names are likewise resolved against package-level constants with no scope
// analysis, so a local variable shadowing one of those constants resolves to
// the constant's value rather than its own.
@@ -193,7 +195,7 @@ func callsExtraReader(files []*ast.File, name string) bool {
func uncoveredEnvReadsInFile(fileSet *token.FileSet, file *ast.File, scan envScan) []string {
var messages []string
for _, call := range envReadCalls(file, scan.extraReaders) {
for _, call := range envReadCalls(fileSet, file, scan.extraReaders) {
name, resolved := resolveEnvName(call, scan.constants)
pos := fileSet.Position(call.Pos())
if !resolved {
@@ -295,14 +297,16 @@ func recordConstSpecs(constants packageConstants, specs []ast.Spec) {
// first: pinning this to exactly one argument meant that adding a fallback
// parameter to an accessor dropped all of its call sites from the scan without
// failing a single test.
func envReadCalls(file *ast.File, extraReaders map[string]bool) []*ast.CallExpr {
func envReadCalls(fileSet *token.FileSet, file *ast.File, extraReaders map[string]bool) []*ast.CallExpr {
uses := typeUses(fileSet, file)
dotImportedOS := hasOSDotImport(file)
var calls []*ast.CallExpr
ast.Inspect(file, func(node ast.Node) bool {
call, ok := node.(*ast.CallExpr)
if !ok || len(call.Args) == 0 {
return true
}
if isEnvRead(call.Fun, extraReaders) {
if isEnvRead(call.Fun, uses, dotImportedOS, extraReaders) {
calls = append(calls, call)
}
return true
@@ -310,27 +314,68 @@ func envReadCalls(file *ast.File, extraReaders map[string]bool) []*ast.CallExpr
return calls
}
// hasOSDotImport reports whether bare identifiers from the standard os package
// can be used in this file. The type checker receives the file's package name
// as its path, so a package named os would otherwise make local Getenv and
// LookupEnv functions indistinguishable from the imported functions.
func hasOSDotImport(file *ast.File) bool {
for _, importSpec := range file.Imports {
if importSpec.Name == nil || importSpec.Name.Name != "." {
continue
}
path, ok := literalString(importSpec.Path)
if ok && path == "os" {
return true
}
}
return false
}
// typeUses resolves identifier bindings within one file. A scanner only needs
// import bindings here, so type errors in unrelated package code do not stop
// it from distinguishing an os import from a local declaration with the same
// spelling.
func typeUses(fileSet *token.FileSet, file *ast.File) map[*ast.Ident]types.Object {
uses := make(map[*ast.Ident]types.Object)
config := types.Config{
Importer: importer.Default(),
Error: func(error) {},
}
_, _ = config.Check(file.Name.Name, fileSet, []*ast.File{file}, &types.Info{Uses: uses})
return uses
}
// isEnvRead reports whether fun names os.Getenv, os.LookupEnv, or one of the
// extraReaders. An extraReader matches on the trailing name alone, so both
// receiver.environmentValue(x) and a bare environmentValue(x) count.
func isEnvRead(fun ast.Expr, extraReaders map[string]bool) bool {
func isEnvRead(fun ast.Expr, uses map[*ast.Ident]types.Object, dotImportedOS bool, extraReaders map[string]bool) bool {
switch target := fun.(type) {
case *ast.SelectorExpr:
if extraReaders[target.Sel.Name] {
return true
}
pkgIdent, ok := target.X.(*ast.Ident)
if !ok || pkgIdent.Name != "os" {
if !ok || !isOSPackageName(uses[pkgIdent]) {
return false
}
return target.Sel.Name == "Getenv" || target.Sel.Name == "LookupEnv"
case *ast.Ident:
return extraReaders[target.Name]
return extraReaders[target.Name] || (dotImportedOS && isOSReader(uses[target]) && (target.Name == "Getenv" || target.Name == "LookupEnv"))
default:
return false
}
}
func isOSPackageName(object types.Object) bool {
pkgName, ok := object.(*types.PkgName)
return ok && pkgName.Imported().Path() == "os"
}
func isOSReader(object types.Object) bool {
function, ok := object.(*types.Func)
return ok && function.Pkg() != nil && function.Pkg().Path() == "os"
}
func resolveEnvName(call *ast.CallExpr, constants packageConstants) (string, bool) {
if value, ok := literalString(call.Args[0]); ok {
return value, true
@@ -87,6 +87,131 @@ func read() (string, bool) { return os.LookupEnv("BAR") }
}
}
// TestUncoveredEnvReadsUncoveredAliasedOSImport ensures a local import name
// cannot hide an environment read from the hermetic-environment guard.
func TestUncoveredEnvReadsUncoveredAliasedOSImport(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import stdos "os"
func read() string { return stdos.Getenv("BAR") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil)
if len(messages) != 1 {
t.Fatalf("expected exactly one uncovered-name message, got %v", messages)
}
if !strings.Contains(messages[0], "BAR") {
t.Fatalf("message %q does not name the uncovered variable", messages[0])
}
}
// TestUncoveredEnvReadsCoveredAliasedOSImport documents that alias resolution
// uses the same scrub/exempt classification as the ordinary os import path.
func TestUncoveredEnvReadsCoveredAliasedOSImport(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import stdos "os"
func read() string { return stdos.Getenv("FOO") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, []string{"FOO"}, nil)
if len(messages) != 0 {
t.Fatalf("covered aliased read reported as uncovered: %v", messages)
}
}
// TestUncoveredEnvReadsIgnoresShadowedAliasedOSImport ensures a local binding
// with the import's spelling does not turn an unrelated Getenv method into an
// environment read.
func TestUncoveredEnvReadsIgnoresShadowedAliasedOSImport(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import stdos "os"
type reader struct{}
func (reader) Getenv(string) string { return "" }
func read(stdos reader) string { return stdos.Getenv("BAR") }
func genuineRead() string { return stdos.Getenv("REAL") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil)
if len(messages) != 1 || !strings.Contains(messages[0], "REAL") {
t.Fatalf("expected only the genuine aliased os read, got %v", messages)
}
}
func TestUncoveredEnvReadsUncoveredDotImportedOS(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import . "os"
func getenv() string { return Getenv("BAR") }
func lookupenv() (string, bool) { return LookupEnv("BAZ") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil)
if len(messages) != 2 {
t.Fatalf("expected exactly two uncovered-name messages, got %v", messages)
}
if !strings.Contains(messages[0], "BAR") || !strings.Contains(messages[1], "BAZ") {
t.Fatalf("messages %q do not name both uncovered variables", messages)
}
}
// TestUncoveredEnvReadsCoveredDotImportedOS documents that dot-imported reads
// are classified against the caller's scrubbed and exempt environment names.
func TestUncoveredEnvReadsCoveredDotImportedOS(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import . "os"
func getenv() string { return Getenv("FOO") }
func lookupenv() (string, bool) { return LookupEnv("BAR") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, []string{"FOO"}, []string{"BAR"})
if len(messages) != 0 {
t.Fatalf("covered dot-imported reads reported as uncovered: %v", messages)
}
}
// TestUncoveredEnvReadsIgnoresShadowedDotImportedOS ensures a local Getenv
// binding does not turn an unrelated function value into an environment read.
func TestUncoveredEnvReadsIgnoresShadowedDotImportedOS(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
import . "os"
func read(Getenv func(string) string) string { return Getenv("BAR") }
func genuineRead() string { return Getenv("REAL") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil)
if len(messages) != 1 || !strings.Contains(messages[0], "REAL") {
t.Fatalf("expected only the genuine dot-imported os read, got %v", messages)
}
}
// TestUncoveredEnvReadsIgnoresLocalPackageNamedOS ensures a package name does
// not make a local Getenv function look like the standard os.Getenv function.
func TestUncoveredEnvReadsIgnoresLocalPackageNamedOS(t *testing.T) {
fileSet, file := parseSnippet(t, `package os
func Getenv(string) string { return "" }
func read() string { return Getenv("BAR") }
`)
messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil)
if len(messages) != 0 {
t.Fatalf("local package Getenv should not be scanned, got %v", messages)
}
}
func TestUncoveredEnvReadsUnresolvableIdentifier(t *testing.T) {
fileSet, file := parseSnippet(t, `package example
+90
View File
@@ -0,0 +1,90 @@
---
created: 2026-09-14
status: done
requirements:
- REQ-INTEGRATIONS-GITLAB-INTEGRATION-001
- REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-001
system_design:
- ../../specs/integrations/system-design/gitlab-integration-02.md
- ../../specs/integrations/system-design/github-authentication-01.md
legacy_specs: []
---
# Implementation plan: Environment scrub drift guards
## Overview
Keep the hermetic environment scrubs used by the GitHub and GitLab integration
test suites from silently falling behind the environment reads those packages
actually perform. One shared scanner in `internal/testutil` resolves the
file-local binding of the `os` package, so an aliased or dot-imported
`os.Getenv` / `os.LookupEnv` call is classified the same way as a plain
`os.Getenv` call instead of bypassing the guard.
The integrations system owns this package because the guarded scrubs exist to
make the providers' environment-credential fallbacks deterministic under test:
an ambient `GITLAB_TOKEN` or `GH_TOKEN` from a developer shell would otherwise
silently activate those fallbacks and change which connection path a test
exercises.
## Scope
In scope: import-aware classification of `os` environment reads in the shared
scanner, adopting it for the GitHub guard, and regression coverage for every
classified import form.
Out of scope: production credential resolution, new environment fallbacks,
bulk `os.Environ`-style unnamed reads, non-`os` accessors such as
`syscall.Getenv`, and public user documentation.
## Technical approach
The original guard matched the literal identifier `os`, which left aliased and
dot-imported calls unscanned. `AssertEnvReadsCovered` now resolves identifier
bindings with `go/types` per file: a selector counts as an environment read
when its package identifier is bound to import path `os`, and a bare
`Getenv` / `LookupEnv` call counts when the identifier resolves to the `os`
package function. Type errors in unrelated package code do not stop the scan
because only import bindings are consulted.
`internal/github`'s package-local guard is replaced by the shared scanner, so
the GitHub and GitLab/process scrubs now follow one classification rule.
## Tests
| Criteria | Evidence |
| --- | --- |
| Aliased `os` import reads are reported as uncovered | `envscan_test.go` import-variant fixtures |
| Dot-imported `Getenv` / `LookupEnv` count as reads | `envscan_test.go` dot-import fixtures |
| Plain imports, extra readers, and non-`os` selectors stay unchanged | Existing `envscan_test.go` suite plus `internal/github` and `internal/gitlab` hermetic suites |
Red-green evidence: the aliased-import regression failed before the scanner
change and passed after it; the remaining import-variant tests pass against
the shared scanner.
## Work orders
- [x] [Task 01: Scan aliased os environment reads](task-01-scan-aliased-os-reads.md)
## Verification results
Commands run from `apps/backend` with the workspace GOMODCACHE/GOCACHE:
- `go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/...`: passed.
- `gofmt -l` on changed files: clean.
Existing referenced requirement and design documents are unchanged; they
qualify at the PR revision as-is.
## Risks
The scanner still does not name bulk unnamed environment reads or non-`os`
accessors; those channels remain outside a name-keyed scrub list and are
guarded by `extraReaders` and review instead.
## References
- [GitLab requirements](../../specs/integrations/requirements/gitlab-integration.md)
- [GitLab system design](../../specs/integrations/system-design/gitlab-integration-02.md)
- [GitHub authentication requirements](../../specs/integrations/requirements/github-authentication.md)
- [GitHub authentication system design](../../specs/integrations/system-design/github-authentication-01.md)
@@ -0,0 +1,106 @@
---
id: "01-scan-aliased-os-reads"
title: "Scan aliased os environment reads"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-INTEGRATIONS-GITLAB-INTEGRATION-001
- REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-001
acceptance_criteria:
- AC-INTEGRATIONS-GITLAB-INTEGRATION-001.4
- AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.1
system_design:
- ../../specs/integrations/system-design/gitlab-integration-02.md
- ../../specs/integrations/system-design/github-authentication-01.md
---
# Task 01: Scan aliased os environment reads
## Summary
Close the classification gap that let an aliased or dot-imported
`os.Getenv` / `os.LookupEnv` call bypass the shared hermetic-environment
guard, and adopt that guard for the GitHub suite instead of its
package-local copy.
## In scope
- `apps/backend/internal/testutil/envscan.go`
- `apps/backend/internal/testutil/envscan_test.go`
- `apps/backend/internal/github/env_hermetic_test.go`
## Out of scope
Production credential resolution, new environment fallbacks, bulk unnamed
reads such as `os.Environ`, non-`os` accessors such as `syscall.Getenv`, and
public user documentation.
## Acceptance
- An aliased `os` import is classified and reports an uncovered environment
variable; the regression was red before the scanner change and green after.
- Dot-imported bare `Getenv` / `LookupEnv` calls and shadowed local `os`
declarations are classified by their actual binding, not by spelling.
- Existing plain-import scanning, extra readers, and non-`os` selectors keep
their behavior; the GitHub, GitLab, and process hermetic suites pass
against the shared scanner.
- The GitLab `GITLAB_TOKEN` environment fallback and the GitHub
workspace-source selection stay testable without ambient shell credentials
sabotaging the scrubbed fixtures.
## Verification
Run from `apps/backend`:
```bash
GOMODCACHE=<workspace module cache> GOCACHE=<workspace build cache> \
go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/...
gofmt -l internal/testutil/envscan.go internal/testutil/envscan_test.go internal/github/env_hermetic_test.go
```
## Files likely touched
- `apps/backend/internal/testutil/envscan.go`
- `apps/backend/internal/testutil/envscan_test.go`
- `apps/backend/internal/github/env_hermetic_test.go`
- This plan and work order.
## Dependencies
None. The GitLab and process scrubs already used the shared scanner.
## Risks
The `go/types` pass resolves bindings per file and ignores type errors
elsewhere; keeping that tolerance documented avoids a future "fix" that
makes the guard fail on unrelated broken code.
## Parallelism
`sequential`
## Inputs
- [Plan](plan.md)
- [GitLab requirements](../../specs/integrations/requirements/gitlab-integration.md), criterion `AC-INTEGRATIONS-GITLAB-INTEGRATION-001.4`
- [GitLab system design](../../specs/integrations/system-design/gitlab-integration-02.md)
- [GitHub authentication requirements](../../specs/integrations/requirements/github-authentication.md), criterion `AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.1`
- [GitHub authentication system design](../../specs/integrations/system-design/github-authentication-01.md)
## Results
The scanner derives the file-local import name bound to package path `os`
through `go/types`, so alias and dot-import forms are classified exactly like
plain `os.Getenv` / `os.LookupEnv` calls. `internal/github` now reuses the
shared `testutil.AssertEnvReadsCovered` instead of its package-local copy.
Verification on 2026-09-09 (focused suites) recorded in the PR:
- `go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/...`: passed.
- `gofmt -l`: clean on the changed files.
The aliased-import regression was red before the scanner change and green
afterward. Existing standard `os` calls, extra readers, and non-`os`
selectors retain behavior.