diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25fa8adb2a..a8f6dab299 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,13 +148,13 @@ When adding validation logic, follow the established architecture: - Repository-level feature detection **Domain-specific validation** (dedicated files): -- `strict_mode.go` - Security and strict mode enforcement -- `pip.go` - Python package validation -- `npm.go` - NPM package validation +- `strict_mode_validation.go` - Security and strict mode enforcement +- `pip_validation.go` - Python package validation +- `npm_validation.go` - NPM package validation +- `docker_validation.go` - Docker image validation - `expression_safety.go` - GitHub Actions expression security - `engine.go` - AI engine configuration - `mcp-config.go` - MCP server configuration -- `docker.go` - Docker image validation - `template.go` - Template structure validation **When to create a new validation file**: diff --git a/pkg/workflow/strict_mode.go b/pkg/workflow/strict_mode.go deleted file mode 100644 index c347a3e51c..0000000000 --- a/pkg/workflow/strict_mode.go +++ /dev/null @@ -1,63 +0,0 @@ -// Package workflow provides strict mode security validation for agentic workflows. -// -// # Strict Mode Validation -// -// This file contains the main orchestrator for strict mode validation. Individual -// validation functions are implemented in validation_strict_mode.go. -// -// Strict mode is designed for production workflows that require enhanced security -// guarantees. It enforces constraints on: -// - Write permissions on sensitive scopes -// - Network access configuration -// - Custom MCP server network settings -// - Bash wildcard tool usage -// -// # Integration with Security Scanners -// -// Strict mode also affects the zizmor security scanner behavior (see pkg/cli/zizmor.go). -// When zizmor is enabled with --zizmor flag, strict mode treats any security findings -// as compilation errors rather than warnings. -// -// # Architecture -// -// The strict mode validation is split across two files: -// - strict_mode.go (this file) - Main orchestrator function -// - validation_strict_mode.go - Individual validation functions -// -// For general validation, see validation.go. -// For detailed documentation, see specs/validation-architecture.md -package workflow - -// validateStrictMode performs strict mode validations on the workflow -// -// This is the main orchestrator that calls individual validation functions -// defined in validation_strict_mode.go. It performs progressive validation: -// 1. validateStrictPermissions() - Refuses write permissions on sensitive scopes -// 2. validateStrictNetwork() - Requires explicit network configuration -// 3. validateStrictMCPNetwork() - Requires network config on custom MCP servers -// -// Note: Strict mode also affects zizmor security scanner behavior (see pkg/cli/zizmor.go) -// When zizmor is enabled with --zizmor flag, strict mode will treat any security -// findings as compilation errors rather than warnings. -func (c *Compiler) validateStrictMode(frontmatter map[string]any, networkPermissions *NetworkPermissions) error { - if !c.strictMode { - return nil - } - - // 1. Refuse write permissions - if err := c.validateStrictPermissions(frontmatter); err != nil { - return err - } - - // 2. Require network configuration and refuse "*" wildcard - if err := c.validateStrictNetwork(networkPermissions); err != nil { - return err - } - - // 3. Require network configuration on custom MCP servers - if err := c.validateStrictMCPNetwork(frontmatter); err != nil { - return err - } - - return nil -} diff --git a/pkg/workflow/validation_strict_mode.go b/pkg/workflow/strict_mode_validation.go similarity index 68% rename from pkg/workflow/validation_strict_mode.go rename to pkg/workflow/strict_mode_validation.go index 84be5bfec9..bb9a20491b 100644 --- a/pkg/workflow/validation_strict_mode.go +++ b/pkg/workflow/strict_mode_validation.go @@ -1,17 +1,24 @@ // Package workflow provides strict mode security validation for agentic workflows. // -// # Strict Mode Validation Functions +// # Strict Mode Validation // -// This file contains the individual validation functions that enforce security +// This file contains strict mode validation functions that enforce security // and safety constraints when workflows are compiled with the --strict flag. -// These functions are called by validateStrictMode() in strict_mode.go. +// +// Strict mode is designed for production workflows that require enhanced security +// guarantees. It enforces constraints on: +// - Write permissions on sensitive scopes +// - Network access configuration +// - Custom MCP server network settings +// - Bash wildcard tool usage // // # Validation Functions // // The strict mode validator performs progressive validation: -// 1. validateStrictPermissions() - Refuses write permissions on sensitive scopes -// 2. validateStrictNetwork() - Requires explicit network configuration -// 3. validateStrictMCPNetwork() - Requires network config on custom MCP servers +// 1. validateStrictMode() - Main orchestrator that coordinates all strict mode checks +// 2. validateStrictPermissions() - Refuses write permissions on sensitive scopes +// 3. validateStrictNetwork() - Requires explicit network configuration +// 4. validateStrictMCPNetwork() - Requires network config on custom MCP servers // // # Integration with Security Scanners // @@ -28,7 +35,6 @@ // - It enforces tool usage restrictions for security // // For general validation, see validation.go. -// For the main strict mode orchestrator, see strict_mode.go. // For detailed documentation, see specs/validation-architecture.md package workflow @@ -118,3 +124,37 @@ func (c *Compiler) validateStrictMCPNetwork(frontmatter map[string]any) error { return nil } + +// validateStrictMode performs strict mode validations on the workflow +// +// This is the main orchestrator that calls individual validation functions. +// It performs progressive validation: +// 1. validateStrictPermissions() - Refuses write permissions on sensitive scopes +// 2. validateStrictNetwork() - Requires explicit network configuration +// 3. validateStrictMCPNetwork() - Requires network config on custom MCP servers +// +// Note: Strict mode also affects zizmor security scanner behavior (see pkg/cli/zizmor.go) +// When zizmor is enabled with --zizmor flag, strict mode will treat any security +// findings as compilation errors rather than warnings. +func (c *Compiler) validateStrictMode(frontmatter map[string]any, networkPermissions *NetworkPermissions) error { + if !c.strictMode { + return nil + } + + // 1. Refuse write permissions + if err := c.validateStrictPermissions(frontmatter); err != nil { + return err + } + + // 2. Require network configuration and refuse "*" wildcard + if err := c.validateStrictNetwork(networkPermissions); err != nil { + return err + } + + // 3. Require network configuration on custom MCP servers + if err := c.validateStrictMCPNetwork(frontmatter); err != nil { + return err + } + + return nil +} diff --git a/pkg/workflow/validation.go b/pkg/workflow/validation.go index 95180c9829..4200ba8b0e 100644 --- a/pkg/workflow/validation.go +++ b/pkg/workflow/validation.go @@ -5,13 +5,13 @@ // This file contains general-purpose validation functions that apply across the entire // workflow system. For domain-specific validation (e.g., strict mode, package validation, // expression safety), see the corresponding domain files: -// - strict_mode.go: Security and strict mode validation -// - pip.go: Python package validation -// - npm.go: NPM package validation +// - strict_mode_validation.go: Security and strict mode validation +// - pip_validation.go: Python package validation +// - npm_validation.go: NPM package validation +// - docker_validation.go: Docker image validation // - expression_safety.go: GitHub Actions expression security // - engine.go: AI engine configuration validation // - mcp-config.go: MCP server configuration validation -// - docker_validation.go: Docker image validation // - template.go: Template structure validation // // # When to Add Validation Here diff --git a/specs/validation-architecture.md b/specs/validation-architecture.md index 5472618df0..3afadc98f0 100644 --- a/specs/validation-architecture.md +++ b/specs/validation-architecture.md @@ -42,26 +42,22 @@ This architecture balances maintainability with domain expertise, allowing valid Domain-specific validation is organized into separate files based on functional area: -#### 1. **Strict Mode Validation**: `strict_mode.go` and `validation_strict_mode.go` +#### 1. **Strict Mode Validation**: `strict_mode_validation.go` -**Location**: -- `pkg/workflow/strict_mode.go` (70 lines) - Main orchestrator -- `pkg/workflow/validation_strict_mode.go` (170 lines) - Individual validation functions +**Location**: `pkg/workflow/strict_mode_validation.go` (190 lines) **Purpose**: Enforces security and safety constraints in strict mode **Validation Functions**: -- `validateStrictMode()` - Main strict mode orchestrator (in `strict_mode.go`) -- `validateStrictPermissions()` - Refuses write permissions (in `validation_strict_mode.go`) -- `validateStrictNetwork()` - Requires explicit network configuration (in `validation_strict_mode.go`) -- `validateStrictMCPNetwork()` - Requires network config on custom MCP servers (in `validation_strict_mode.go`) -- `validateStrictBashTools()` - Refuses bash wildcard tools (in `validation_strict_mode.go`) +- `validateStrictMode()` - Main strict mode orchestrator +- `validateStrictPermissions()` - Refuses write permissions +- `validateStrictNetwork()` - Requires explicit network configuration +- `validateStrictMCPNetwork()` - Requires network config on custom MCP servers +- `validateStrictBashTools()` - Refuses bash wildcard tools **Pattern**: Security policy enforcement with progressive validation -**Architecture**: The strict mode validation is split across two files for better organization: -- `strict_mode.go` contains the main orchestrator that coordinates validation -- `validation_strict_mode.go` contains the individual validation function implementations +**Architecture**: All strict mode validation logic is consolidated in a single file following the `*_validation.go` naming pattern used throughout the codebase **When to add validation here**: - ✅ Strict mode security policies @@ -200,7 +196,7 @@ Use this decision tree to determine where to place new validation logic: ┌───────────────┐ │ Is it about │ │ security or │ YES - │ strict mode? ├──────────► strict_mode.go + │ strict mode? ├──────────► strict_mode_validation.go └───────┬───────┘ │ NO ▼ @@ -332,7 +328,7 @@ func (c *Compiler) validateGitHubActionsSchema(yamlContent string) error { ### Pattern 4: Progressive Validation -**Used in**: `strict_mode.go` +**Used in**: `strict_mode_validation.go` **Purpose**: Apply multiple validation checks in sequence