Add support for custom AWF installation path in firewall configuration

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

docs/src/content/docs/reference/frontmatter-full.md

@@ -878,6 +878,11 @@ network:
     # (optional)
     log-level: "debug"
 
+    # Custom path to AWF binary. When specified, skips downloading AWF from GitHub
+    # releases. Supports absolute paths or paths relative to GITHUB_WORKSPACE.
+    # (optional)
+    path: "example-value"
+
 # Conditional execution expression
 # (optional)
 if: "example-value"

docs/src/content/docs/reference/network.md

@@ -112,6 +112,39 @@ The default log level is `info`, which provides a balance between visibility and
 
 See the [Copilot Engine - Network Permissions](/gh-aw/reference/engines/#network-permissions) documentation for detailed AWF configuration options.
 
+### Custom AWF Binary Path
+
+Specify a custom AWF binary instead of downloading from GitHub releases:
+
+```yaml wrap
+network:
+  firewall:
+    path: /usr/local/bin/awf-custom  # Absolute path
+  allowed:
+    - defaults
+```
+
+Relative paths are resolved relative to the repository root:
+
+```yaml wrap
+network:
+  firewall:
+    path: bin/awf  # Resolves to ${GITHUB_WORKSPACE}/bin/awf
+  allowed:
+    - defaults
+```
+
+When `path` is specified:
+- AWF is not downloaded from GitHub releases
+- The specified binary must exist and be executable
+- Path is validated before workflow execution
+- The `version` field is ignored (if also specified)
+
+**Use cases:**
+- Pre-installed AWF on self-hosted runners
+- Custom AWF builds with patches or modifications
+- Repository-specific AWF versions
+
 ## Best Practices
 
 Follow the principle of least privilege by only allowing access to domains and ecosystems actually needed. Prefer ecosystem identifiers over broad wildcard patterns. Avoid overly permissive patterns like `"*"` or `"*.com"`.

pkg/parser/schemas/main_workflow_schema.json

@@ -1675,6 +1675,10 @@
                       "type": "string",
                       "description": "AWF log level (default: info). Valid values: debug, info, warn, error",
                       "enum": ["debug", "info", "warn", "error"]
+                    },
+                    "path": {
+                      "type": "string",
+                      "description": "Custom path to AWF binary. When specified, skips downloading AWF from GitHub releases. Supports absolute paths or paths relative to GITHUB_WORKSPACE."
                     }
                   },
                   "additionalProperties": false

pkg/workflow/copilot_engine.go

@@ -62,18 +62,24 @@ func (e *CopilotEngine) GetInstallationSteps(workflowData *WorkflowData) []GitHu
 		steps = append(steps, npmSteps[0]) // Setup Node.js step
 	}
 
-	// Add AWF installation steps only if firewall is enabled
+	// Add AWF installation or validation steps only if firewall is enabled
 	if isFirewallEnabled(workflowData) {
-		// Install AWF after Node.js setup but before Copilot CLI installation
 		firewallConfig := getFirewallConfig(workflowData)
-		var awfVersion string
-		if firewallConfig != nil {
-			awfVersion = firewallConfig.Version
-		}
 
-		// Install AWF binary
-		awfInstall := generateAWFInstallationStep(awfVersion)
-		steps = append(steps, awfInstall)
+		if firewallConfig == nil || firewallConfig.Path == "" {
+			// Default: Download and install AWF from GitHub releases
+			var awfVersion string
+			if firewallConfig != nil {
+				awfVersion = firewallConfig.Version
+			}
+
+			awfInstall := generateAWFInstallationStep(awfVersion)
+			steps = append(steps, awfInstall)
+		} else {
+			// Custom path: Validate the binary exists and is executable
+			validationStep := generateAWFPathValidationStep(firewallConfig.Path)
+			steps = append(steps, validationStep)
+		}
 	}
 
 	// Add Copilot CLI installation step after AWF
@@ -249,11 +255,14 @@ func (e *CopilotEngine) GetExecutionSteps(workflowData *WorkflowData, logFile st
 			awfArgs = append(awfArgs, firewallConfig.Args...)
 		}
 
+		// Get AWF binary path (custom or default)
+		awfBinary := getAWFBinaryPath(firewallConfig)
+
 		// Build the full AWF command with proper argument separation
 		// AWF v0.2.0 uses -- to separate AWF args from the actual command
 		// The command arguments should be passed as individual shell arguments, not as a single string
 		command = fmt.Sprintf(`set -o pipefail
-sudo -E awf %s \
+sudo -E %s %s \
   -- %s \
   2>&1 | tee %s
 
@@ -264,7 +273,7 @@ if [ -n "$COPILOT_LOGS_DIR" ] && [ -d "$COPILOT_LOGS_DIR" ]; then
   sudo mkdir -p %s
   sudo mv "$COPILOT_LOGS_DIR"/* %s || true
   sudo rmdir "$COPILOT_LOGS_DIR" || true
-fi`, shellJoinArgs(awfArgs), copilotCommand, shellEscapeArg(logFile), shellEscapeArg(logsFolder), shellEscapeArg(logsFolder), shellEscapeArg(logsFolder))
+fi`, shellEscapeArg(awfBinary), shellJoinArgs(awfArgs), copilotCommand, shellEscapeArg(logFile), shellEscapeArg(logsFolder), shellEscapeArg(logsFolder), shellEscapeArg(logsFolder))
 	} else {
 		// Run copilot command without AWF wrapper
 		command = fmt.Sprintf(`set -o pipefail
@@ -866,6 +875,50 @@ func generateAWFInstallationStep(version string) GitHubActionStep {
 	return GitHubActionStep(stepLines)
 }
 
+// resolveAWFPath handles path resolution for absolute and relative paths
+func resolveAWFPath(customPath string) string {
+	if customPath == "" {
+		return "/usr/local/bin/awf"
+	}
+
+	if strings.HasPrefix(customPath, "/") {
+		return customPath // Absolute path
+	}
+
+	// Relative path - resolve against GITHUB_WORKSPACE
+	return fmt.Sprintf("${GITHUB_WORKSPACE}/%s", customPath)
+}
+
+// getAWFBinaryPath returns appropriate AWF binary path for execution
+func getAWFBinaryPath(firewallConfig *FirewallConfig) string {
+	if firewallConfig != nil && firewallConfig.Path != "" {
+		return resolveAWFPath(firewallConfig.Path)
+	}
+	return "awf" // Default (in PATH from installation step)
+}
+
+// generateAWFPathValidationStep creates a validation step to verify custom AWF binary
+func generateAWFPathValidationStep(customPath string) GitHubActionStep {
+	resolvedPath := resolveAWFPath(customPath)
+
+	stepLines := []string{
+		"      - name: Validate custom AWF binary",
+		"        run: |",
+		fmt.Sprintf("          echo \"Validating custom AWF binary at: %s\"", resolvedPath),
+		fmt.Sprintf("          if [ ! -f %s ]; then", shellEscapeArg(resolvedPath)),
+		fmt.Sprintf("            echo \"Error: AWF binary not found at %s\"", resolvedPath),
+		"            exit 1",
+		"          fi",
+		fmt.Sprintf("          if [ ! -x %s ]; then", shellEscapeArg(resolvedPath)),
+		fmt.Sprintf("            echo \"Error: AWF binary at %s is not executable\"", resolvedPath),
+		"            exit 1",
+		"          fi",
+		fmt.Sprintf("          %s --version", shellEscapeArg(resolvedPath)),
+	}
+
+	return GitHubActionStep(stepLines)
+}
+
 // generateSquidLogsCollectionStep creates a GitHub Actions step to collect Squid logs from AWF
 func generateSquidLogsCollectionStep(workflowName string) GitHubActionStep {
 	sanitizedName := strings.ToLower(SanitizeWorkflowName(workflowName))

pkg/workflow/firewall.go

@@ -13,6 +13,7 @@ type FirewallConfig struct {
 	Args          []string `yaml:"args,omitempty"`           // Additional arguments to pass to AWF
 	LogLevel      string   `yaml:"log_level,omitempty"`      // AWF log level (default: "info")
 	CleanupScript string   `yaml:"cleanup_script,omitempty"` // Cleanup script path (default: "./scripts/ci/cleanup.sh")
+	Path          string   `yaml:"path,omitempty"`           // Custom AWF binary path (skips download when specified)
 }
 
 // isFirewallEnabled checks if AWF firewall is enabled for the workflow