How gh-aw Ensures Security for AI Agent Execution: A Defense-in-Depth Analysis

gh-aw implements a multi-layered security architecture that enforces strict mode validation, sandboxed containers, explicit network allow-lists, and isolated threat-detection jobs to prevent unauthorized access during AI agent execution.

GitHub Agentic Workflows (gh-aw) is an open-source framework that compiles markdown-based AI workflows into secure GitHub Actions. Understanding gh-aw security for AI agent execution requires examining its defense-in-depth strategy, which combines compile-time validation with runtime isolation mechanisms defined across multiple validation layers in the github/gh-aw repository.

Strict Mode Validation

The foundation of gh-aw security is strict mode, a compile-time enforcement layer defined in pkg/workflow/strict_mode_validation.go. When the --strict flag is passed to gh aw compile, the validateStrictMode orchestrator invokes specialized validators that reject unsafe configurations before they reach production.

Network and Firewall Enforcement

Strict mode requires explicit network declarations and mandatory firewall protection. The validateStrictNetwork and validateStrictFirewall functions enforce three critical rules:

• Wildcard network access (*) is prohibited; workflows must declare specific network.allowed ecosystems (e.g., python, node)
• The Agent Workflow Firewall (AWF) must be enabled when network domains are specified
• Custom domains are rejected in strict mode to prevent data exfiltration

Tool Restrictions

The validateStrictTools function blocks dangerous tool configurations that could expose the runner to local system access. For example, configuring the serena tool in local mode is explicitly forbidden, as is using cache-memory with scope: repo in strict mode.

Permission Hardening

Direct write permissions on sensitive GitHub resources are prohibited. The validateStrictPermissions function in strict_mode_validation.go rejects workflows requesting write scopes on contents, issues, or pull-requests. Instead, gh-aw requires the use of safe-outputs—a controlled mechanism for creating issues or pull requests that runs in an isolated job after the AI step completes.

Sandbox Validation

Before any AI agent executes, pkg/workflow/sandbox_validation.go validates the sandbox configuration. The SandboxConfig type requires:

• type: awf (Agent Workflow Firewall is the only supported sandbox type)
• An enabled agent configuration (disabled: false is mandatory in strict mode)
• An MCP gateway when the sandbox is active, ensuring tool calls are routed through a controlled interface

This validation ensures that AI engines run inside containerized environments with no direct access to the runner filesystem.

Threat Detection and Isolation

The pkg/workflow/threat_detection.go file implements runtime isolation through the threat-detection job. When a workflow uses safe-outputs, the compiler automatically inserts a separate job that:

• Runs the AI engine in a sandboxed container with restricted network access
• Writes all execution logs to a private artifact inaccessible to subsequent steps
• Executes only after all sandbox and network validations pass

The parseThreatDetectionConfig function allows explicit disabling via threat-detection: false, though this is discouraged for production workflows handling sensitive data.

MCP Server Isolation

When workflows include custom MCP (Model Context Protocol) servers running in containers, gh-aw enforces network isolation through validateStrictMCPNetwork. This validation requires a top-level network block that prevents the MCP container from reaching external internet services, ensuring that tool communications remain confined to the local workflow environment.

How the Security Layers Fit Together

The compilation process in pkg/workflow/compiler.go orchestrates these security checks through a deterministic pipeline:

1. Parsing: The compiler extracts front-matter (sandbox, network, tools, permissions) into a WorkflowData structure.

2. Validation: If the --strict flag is present, validateStrictMode runs the full suite of validators (validateStrictNetwork, validateStrictFirewall, validateStrictTools, validateStrictPermissions), collecting errors via NewErrorCollector.

3. Job Injection: When safe-outputs are detected (data.SafeOutputs != nil), the compiler inserts the threat-detection job from threat_detection.go, configuring it to run in an isolated container with private artifact logging.

4. YAML Generation: The final GitHub Actions YAML includes explicit permissions declarations, network blocks with firewall enforcement, and if conditions ensuring AI steps only execute after security constraints are satisfied.

If any validator fails, compilation aborts immediately with a descriptive error linking to the relevant documentation.

Practical Security Configurations

Enabling Strict Mode for Production

Compile workflows with the --strict flag to activate all security validators:

gh aw compile my-workflow.md --strict

The generated YAML includes strict-mode guards:

if: >-
  ${{ always() && (needs.my_workflow.outputs.output_types != '' ||
  needs.my_workflow.outputs.has_patch == 'true') }}

Configuring a Secure Sandbox

Define a sandbox that forces firewall protection:

---
sandbox:
  type: awf
  agent:
    disabled: false
network:
  allowed: [python, node]
  firewall:
    enabled: true
---

The compiler validates this through validateStrictFirewall and validateStrictNetwork in strict_mode_validation.go.

Blocking Unsafe Permissions

Attempting to request write access to sensitive resources fails in strict mode:

---
permissions:
  contents: write
  issues: read
---

Compilation produces:

strict mode: write permission 'contents: write' is not allowed for security reasons.
Use safe-outputs.create-issue, safe-outputs.create-pull-request, …

The validation occurs in validateStrictPermissions.

Using Safe-Outputs for Controlled Writes

Instead of direct permissions, use safe-outputs to create GitHub resources:

---
safe-outputs:
  create-issue:
    title: "Automated report"
    body: "{{ .output }}"
---

This triggers the threat-detection job isolation pattern, ensuring the AI cannot directly modify repository contents.

Summary

• Strict mode in pkg/workflow/strict_mode_validation.go provides compile-time enforcement of network restrictions, firewall requirements, tool configurations, and GitHub permissions.
• Sandbox validation via pkg/workflow/sandbox_validation.go ensures AI agents run inside AWF-sandboxed containers with mandatory MCP gateways.
• Threat detection in pkg/workflow/threat_detection.go isolates AI execution in separate jobs with private artifact logging, preventing output contamination.
• Safe-outputs replace dangerous write permissions, allowing controlled GitHub resource creation without exposing contents: write or pull-requests: write to the AI step.
• The compiler (pkg/workflow/compiler.go) orchestrates these layers, aborting on validation failures and injecting security jobs automatically when needed.

Frequently Asked Questions

What is strict mode in gh-aw?

Strict mode is a compile-time security flag (--strict) that activates comprehensive validation rules in pkg/workflow/strict_mode_validation.go. When enabled, it prohibits wildcard network access, mandates firewall protection, blocks dangerous tool configurations like serena in local mode, and rejects write permissions on sensitive GitHub resources such as contents or pull-requests.

How does gh-aw isolate AI agents from network threats?

gh-aw implements network isolation through multiple mechanisms. The validateStrictNetwork function requires explicit network.allowed lists without wildcards, while validateStrictFirewall mandates the Agent Workflow Firewall (AWF) when network access is granted. Additionally, the threat-detection job runs AI engines in sandboxed containers with restricted network namespaces, and MCP servers are isolated via validateStrictMCPNetwork to prevent external internet access.

Can I disable threat detection in gh-aw?

Yes, threat detection can be explicitly disabled by setting threat-detection: false in the workflow front-matter. The parseThreatDetectionConfig function in pkg/workflow/threat_detection.go handles this configuration. However, disabling threat detection removes the isolation job that runs AI engines in separate containers with private artifact logging, which is not recommended for production workflows handling sensitive data or executing untrusted AI outputs.

What permissions are blocked in strict mode?

In strict mode, validateStrictPermissions in pkg/workflow/strict_mode_validation.go explicitly blocks write scopes on contents, issues, and pull-requests. Instead of granting these dangerous permissions directly to AI steps, gh-aw requires the use of safe-outputs—a controlled mechanism that creates issues or pull requests in an isolated job after the AI execution completes, preventing the AI from directly modifying repository contents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}