Security Considerations
Relevant source files
The following files were used as context for generating this wiki page:
TDD Guard operates as an automated enforcement tool for Test-Driven Development (TDD) that integrates directly with Claude Code via hooks. Because it intercepts file operations (Write, Edit, MultiEdit) and executes with the same user permissions as the host environment, security is a primary consideration in its architecture and deployment.
The system relies on external test reporters and AI model clients to validate code changes. This document outlines the security boundaries, data handling practices, and validation logic used to protect the integrity of the user's filesystem and environment.
Sources: README.md:14-25, CLAUDE.md:7-14
Execution Environment and Permissions
TDD Guard runs with full user permissions. It functions by intercepting shell commands and file operations within the Claude Code environment. As noted in the documentation, hooks execute shell commands without explicit confirmation, placing the responsibility on the user to ensure the safety of the hook configuration.
Hook Security Flow
The following diagram illustrates how TDD Guard interacts with Claude Code and the filesystem:
TDD Guard implements several internal measures to maintain security during this process:
- Automated Scanning: Use of CI/CD workflows for security scanning and dependency audits.
- Permission Scope: Operating strictly within the user's permission model.
- Integrity: Use of Test-Driven Development for the tool itself to ensure predictable behavior.
Sources: README.md:231-244, package.json:65-72
Reporter Security and Path Validation
Language-specific reporters (Go, Rust, Python, etc.) are responsible for capturing test results. A critical security requirement for these reporters is the validation of the project root path to prevent unauthorized directory access or path traversal.
Path Constraints
Reporters must enforce the following rules for the project-root parameter:
- Absolute Paths: The project root path must be specified as an absolute path.
- Ancestry Check: The current working directory (CWD) must be either the project root or a descendant of it.
- Traversal Prevention: Paths must be checked for traversal patterns (e.g.,
../).
| Component | Function/Method | Security Purpose |
|---|---|---|
| Go Reporter | validateProjectRoot | Ensures CWD is within the absolute project root path. |
| Rust Reporter | main | Validates that the provided path exists and is absolute. |
| Config | CLAUDE_PROJECT_DIR validation | Prevents path traversal and ensures CWD is contained within the project. |
Sources: CONTRIBUTING.md:13-17, reporters/go/cmd/tdd-guard-go/main.go:88-106, reporters/rust/src/main.rs:48-60, src/config/Config.test.ts:76-114
Environment Variable and API Key Management
TDD Guard handles sensitive information, such as Anthropic API keys, via environment variables. The configuration logic prioritizes explicit options over environment variables to prevent accidental exposure or overriding.
Configuration Priorities
- API Keys:
TDD_GUARD_ANTHROPIC_API_KEYis retrieved from the environment if not provided via constructor options. - System Claude:
USE_SYSTEM_CLAUDEcontrols whether the system-installed Claude instance is used, defaulting tofalseif unset. - Pathing:
CLAUDE_PROJECT_DIRis used to establish the security context for file operations when no explicit project root is provided.
Sources: src/config/Config.test.ts:133-152, src/config/Config.test.ts:169-188, src/config/Config.test.ts:70-85
Dependency and Build Security
The project uses a structured build process and dependency management to minimize supply chain risks.
- Workspaces: Language-specific reporters are managed as separate npm workspaces or distinct language packages (Pip, Composer, Cargo, Go) to isolate dependencies.
- Automated Checks: The
npm run checkscommand integrates type-checking, linting (ESLint), and formatting (Prettier) to prevent the introduction of code smells or vulnerabilities. - Linter Integration: Support for
golangci-lintandeslintallows the tool to enforce code quality status before allowing implementation changes.
Sources: package.json:34-52, src/validation/prompts/tools/lint-results.ts:3-13, DEVELOPMENT.md:34-45
Data Privacy
TDD Guard stores temporary test results and session data in a local .claude/tdd-guard/data directory within the project root.
| File Name | Data Type | Description |
|---|---|---|
test.json | JSON | Results of the latest test run captured by reporters. |
config.json | JSON | Local guard configuration (enabled/disabled, ignore patterns). |
modifications.json | JSON | Pending file modifications under review. |
lint.json | JSON | Static analysis issues detected in the codebase. |
These files are stored locally and are subject to the same permissions as the project itself. The system does not transmit source code to external servers except for the content sent to the configured AI model for TDD validation.
Sources: src/config/Config.test.ts:39-68, reporters/rust/src/main.rs:163-177, reporters/go/cmd/tdd-guard-go/main.go:53-56
Conclusion
Security in TDD Guard is centered on the principle of "User-in-the-loop" awareness regarding hooks and strict path validation within its multi-language reporters. By enforcing absolute path requirements and validating the relationship between the working directory and the project root, TDD Guard mitigates the risk of unauthorized filesystem access during automated TDD enforcement.