Security Audit Report — go-tool-base¶

Date: 2026-04-02
Auditor Role: Senior Security Analyst (Go specialist)
Scope: Full codebase review — authentication, cryptography, input validation, supply chain, information disclosure
Branch: develop (commit 50e9cbc)
Status: Reviewed — all findings triaged with owner responses

Executive Summary¶

The go-tool-base project demonstrates a strong security posture overall. TLS configuration is hardened, HTTP clients use secure defaults, cryptographic operations use crypto/rand, and error handling is structured. Several findings were identified and triaged with the project owner. Code fixes, specification drafts, CI tooling, and documentation have been produced as part of this audit.

Finding counts by severity and resolution:

Part 1: Findings and Resolutions¶

HIGH Severity¶

H-1: Unencrypted Credential Storage at Rest¶

Location: pkg/config/container.go:116-118, pkg/setup/ai/ai.go:327-366, pkg/setup/github/github.go:189

Description: API keys for AI providers (Claude, OpenAI, Gemini), GitHub tokens, and Bitbucket app passwords are stored as plaintext YAML/JSON in the user's config file on disk.

Evidence:

// pkg/config/container.go:116-118
func (c *Container) WriteConfigAs(filename string) error {
    return c.v.WriteConfigAs(filename)
}

Owner Response: Agreed this is a concern. In non-development environments, credential management is expected to be handled externally (CSI drivers, Kubernetes Secrets, Vault). The solution must be selective — not all environments need OS keychain integration. The env-var approach already exists but isn't the default setup path.

Resolution: SPEC DRAFTED
Specification: docs/development/specs/2026-04-02-credential-storage-hardening.md
Key proposals: make env-var references the default in the setup wizard, optional OS keychain integration gated behind a build tag, documented trust model across deployment contexts.

H-2: Agent Tool Executes Arbitrary Commands¶

Location: internal/agent/tools.go:196

Description: Code at the cited location uses exec.CommandContext with a //nolint:gosec comment.

Owner Response: FALSE POSITIVE. There is no exec_command AI tool defined — this was an intentional decision to prevent AI from running arbitrary commands. The cited code is a tool-building helper with the //nolint tag because it's a helper function that cannot determine the safety of the constructing call being made. It is not an AI-accessible tool.

Resolution: NO ACTION REQUIRED

H-3: No Checksum Verification for Downloaded Release Binaries¶

Location: pkg/setup/update.go (download flow), pkg/setup/checksum.go

Description: The remote update download path relies solely on HTTPS transport integrity. The local UpdateFromFile() path already has SHA-256 verification.

Owner Response: Agreed, but noted that checksums hosted at the same VCS provider don't protect against full platform compromise. Needs a full spec to address trust model considerations.

Resolution: SPEC DRAFTED
Specification: docs/development/specs/2026-04-02-remote-update-checksum-verification.md
Key proposals: download and verify checksums.txt alongside release assets, fail-open by default with strict mode opt-in, cosign keyless verification as a future phase for defense-in-depth.

MEDIUM Severity¶

M-1: Health Endpoints Expose Internal Error Messages¶

Location: pkg/http/server.go:26-39, pkg/controls/controls.go:170, pkg/controls/healthcheck.go:62

Description: Health endpoints return raw error messages from service health checks in the ServiceStatus.Error field.

Owner Response: The emitting of error messages is intentional. It is the developer's responsibility to ensure sensitive information does not leak through these endpoints.

Resolution: DOCUMENTED (Accepted Risk)
- Added "Security Considerations" section to docs/how-to/register-health-checks.md - Recorded in docs/development/security-decisions.md as accepted risk M-1

M-2: Stack Traces Logged at Non-Debug Levels¶

Location: pkg/setup/middleware_builtin.go:50-56, pkg/config/container.go:139,141,203

Description: Panic recovery logged full stack traces at ERROR level. Config failures logged stack traces at WARN level.

Owner Response: Agreed. These should leverage debug-level logging for stack trace output.

Resolution: FIXED
- pkg/setup/middleware_builtin.go: Panic details logged at ERROR (no stack), stack trace logged separately at DEBUG - pkg/config/container.go: Stack traces moved from WARN/ERROR to DEBUG level at all three locations (lines 139, 141, 203)

M-3: Config File Permissions Not Restrictive¶

Location: pkg/setup/ai/ai.go, pkg/setup/github/github.go, pkg/setup/init.go

Description: Config files containing credentials were written with default umask permissions (typically 0644).

Owner Response: Agreed. All config files should get 0600 permissions.

Resolution: FIXED
- pkg/setup/ai/ai.go: Added p.FS.Chmod(targetFile, 0o600) after WriteConfigAs - pkg/setup/github/github.go: Added p.FS.Chmod(targetFile, 0o600) after WriteConfigAs - pkg/setup/init.go: Added props.FS.Chmod(targetFile, 0o600) after WriteConfigAs (with warning on failure)

M-4: Sensitive Data Not Cleared from Memory¶

Location: pkg/vcs/repo/repo.go:302-315, pkg/vcs/bitbucket/release.go:85-86

Description: SSH passphrases and VCS credentials remain in Go string variables for the process lifetime.

Owner Response: Agreed this is a limitation of Go's GC runtime. Document as accepted risk.

Resolution: DOCUMENTED (Accepted Risk)
Recorded in docs/development/security-decisions.md as accepted risk M-4.

M-5: URL Opened via System Command Without Scheme Validation¶

Location: pkg/telemetry/deletion.go:108-121

Description: The openURL() function passes URLs to system commands without validating the scheme.

Owner Response: Agreed. Needs a spec.

Resolution: SPEC DRAFTED
Specification: docs/development/specs/2026-04-02-url-scheme-validation.md
Key proposal: new pkg/browser/ package with scheme allowlist (https, http, mailto), replacing both existing call sites.

M-6: update --from-file Reads Arbitrary Paths¶

Location: pkg/cmd/update/update.go:56-77

Description: The --from-file flag accepts arbitrary filesystem paths.

Owner Response: Arbitrary paths are by design. Should be documented.

Resolution: DOCUMENTED (Accepted Risk)
Recorded in docs/development/security-decisions.md as accepted risk M-6.

M-7: Template Data from CLI Flags Not Escaped¶

Location: internal/generator/skeleton.go:551-557

Description: text/template renders scaffolded files with user-provided data. Code locations intentionally unescaped; non-code locations (YAML values, README prose) are not escaped either.

Owner Response: Template data is intentionally not escaped for code locations. However, values passed into non-code locations should be reviewed and escaped where appropriate. Needs a spec.

Resolution: SPEC DRAFTED
Specification: docs/development/specs/2026-04-02-generator-template-escaping.md
Key proposals: context-specific escape functions (escapeYAML, escapeMarkdown, etc.), applied via pipe syntax only at non-code template locations.

M-8: Environment Variable Auto-Binding Could Cause Config Pollution¶

Location: pkg/config/container.go:25-26

Description: viper.AutomaticEnv() allows any matching environment variable to override config.

Owner Response: The binding is somewhat intentional, but adding a custom prefix is the right approach. The config package should allow consumers to specify a custom prefix (GTB uses GTB_, other tools define their own).

Resolution: SPEC DRAFTED
Specification: docs/development/specs/2026-04-02-config-env-prefix.md
Key proposals: WithEnvPrefix option leveraging Viper's SetEnvPrefix(), backward-compatible (no prefix = current behavior), generator scaffolds new tools with a derived prefix.

LOW Severity¶

L-1: Debug-Mode Stack Traces in Error Handler¶

Location: pkg/errorhandling/handling.go:119-121,134

Owner Response: Intentional for development. Document accordingly.

Resolution: DOCUMENTED
Recorded in docs/development/security-decisions.md.

L-2: Provider Environment Variable Value Logged at Debug Level¶

Location: pkg/chat/client.go

Owner Response: Acceptable for debugging. Document accordingly.

Resolution: DOCUMENTED
Recorded in docs/development/security-decisions.md.

L-3: No Security Headers in Default HTTP Server¶

Location: pkg/http/server.go

Owner Response: Intentional. Document and provide how-to guides.

Resolution: DOCUMENTED
Created docs/how-to/security-headers.md with middleware examples covering HSTS, CSP, X-Content-Type-Options, and X-Frame-Options.

L-4: SSH Key Discovery Scans Entire ~/.ssh¶

Location: pkg/setup/github/ssh.go:132-168

Owner Response: Required for TUI initialisation. Only reads filenames, not contents.

Resolution: DOCUMENTED (Accepted Risk)
Recorded in docs/development/security-decisions.md.

L-5: Machine ID in Telemetry Deletion Emails¶

Location: pkg/telemetry/deletion.go:97-98, pkg/telemetry/machine.go:17-35

Owner Response: Should already be hashed. Verify.

Resolution: FALSE POSITIVE
Verified: HashedMachineID() in pkg/telemetry/machine.go collects OS machine ID, MAC address, hostname, and username, joins them, SHA-256 hashes the result, and returns only the first 8 bytes as 16 hex characters. Raw identifiable values are never transmitted.

L-6: fmt.Printf for Server URL Instead of Logger¶

Location: pkg/docs/serve.go:34

Owner Response: Needs to be addressed to use info logging.

Resolution: FIXED
Changed fmt.Printf("Documentation server starting at %s\n", url) to slog.Info("Documentation server starting", "url", url) using Go's standard library structured logger (no API signature change required).

Informational (Positive Findings)¶

These security controls are well-implemented and require no action:

Part 2: CI Security Tooling¶

Previously In Place¶

Added in This Audit¶

Remaining Recommendations (Not Yet Implemented)¶

Part 3: Action Items¶

Immediate (Code fixes applied in this audit)¶

Specs Requiring Review and Approval¶

Follow-up Tasks (Post Spec Approval)¶

Report generated 2026-04-02. All line numbers reference the develop branch at commit 50e9cbc. Updated with owner responses and resolutions on the same date.