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

> Discover how gh-aw provides robust security for AI agent execution with its defense-in-depth approach including strict mode, sandboxing, and network controls.

- Repository: [GitHub/gh-aw](https://github.com/github/gh-aw)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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:

```bash
gh aw compile my-workflow.md --strict

```

The generated YAML includes strict-mode guards:

```yaml
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:

```yaml
---
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`](https://github.com/github/gh-aw/blob/main/strict_mode_validation.go).

### Blocking Unsafe Permissions

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

```yaml
---
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:

```yaml
---
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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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.