Document container mount security model and guidance

.github/aw/runbooks/workflow-health.md

@@ -438,6 +438,6 @@ tools:
 ## Additional Resources
 
 - [Getting Started with MCP](/docs/src/content/docs/guides/getting-started-mcp.md)
-- [Security Guide](/docs/src/content/docs/guides/security.md)
+- [Security Guide](/docs/src/content/docs/guides/security/index.md)
 - [Error Reference](/docs/src/content/docs/troubleshooting/errors.md)
 - [Common Issues](/docs/src/content/docs/troubleshooting/common-issues.md)

SECURITY.md

@@ -30,6 +30,18 @@ This information will help us triage your report more quickly.
 
 See [GitHub's Safe Harbor Policy](https://docs.github.com/en/github/site-policy/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
 
+
+## Container Mount Security
+
+Agentic workflows run in containers, and mounting host paths
+increases exposure of runner files. Default mounts are kept
+narrow and read-only where possible, and Docker socket access
+is explicitly blocked. Avoid mounting system directories or
+user home paths unless a security review confirms the need.
+
+See [Container Mount Security](https://githubnext.github.io/gh-aw/guides/security/container-mounts/)
+for best practices and the review checklist.
+
 ## Software Bill of Materials (SBOM)
 
 We generate Software Bill of Materials (SBOM) for this project to provide complete visibility into the dependency tree, enabling compliance reporting, vulnerability tracking, and supply chain risk assessment.

docs/src/content/docs/guides/security/container-mounts.md

@@ -0,0 +1,124 @@
+---
+title: Container mount security
+description: Threat model and best practices for mounting host paths into agent containers.
+---
+
+# Container mount security
+
+Mounting host paths into agent containers can be powerful, but
+it expands what the agent can read and write on the runner.
+Use mounts only when you cannot achieve the same outcome by
+installing tools inside the container or by passing data
+through workflow inputs.
+
+## Threat model
+
+Agentic workflows run in containers, but mounts pierce the
+filesystem boundary. Consider three main threats:
+
+- **Malicious workflow author** attempts to read or alter
+  host files by adding broad mounts.
+- **Compromised dependencies** try to access host secrets or
+  runner configuration through mounted paths.
+- **Accidental exposure** of sensitive data (tokens, SSH keys,
+  config files) when mounting user directories or system paths.
+
+## Current security controls
+
+gh-aw limits the default mount set and applies defense-in-depth:
+
+- **Read-only mounts for system tools.** Only specific binaries
+  such as `gh` and `yq` are mounted, not entire system paths.
+- **Principle of least privilege.** Default mounts are narrow
+  and purpose-built for agent execution.
+- **No Docker socket access.** The agent sandbox does not mount
+  `/var/run/docker.sock`, and custom mounts cannot add it.
+- **No privileged containers.** The agent container runs without
+  `--privileged` and does not grant kernel-level capabilities.
+
+For the full default mount list, see
+[Sandbox Configuration](/gh-aw/reference/sandbox/).
+
+## Risks by host path
+
+Some host paths create outsized risk even when mounted read-only:
+
+- **System binaries and libraries** (`/usr/bin`, `/lib`,
+  `/usr/local/bin`): broad visibility into the host runtime and
+  access to tooling you may not intend to expose.
+- **Configuration and secrets** (`/etc`, `/home/runner`,
+  `/root`, `/var/lib`): likely to contain credentials,
+  SSH keys, or package manager state.
+- **Process and device paths** (`/proc`, `/sys`, `/dev`,
+  `/var/run`): can expose kernel interfaces or sockets.
+- **Workspace root** (`${GITHUB_WORKSPACE}`): already mounted
+  by default. Additional mounts that overlap it can create
+  confusing precedence or unreviewed write access.
+
+> [!WARNING]
+> Read-only mounts still allow disclosure.
+> Treat any readable host path as sensitive data that the
+> workflow can exfiltrate through allowed tools.
+
+## Best practices for workflow authors
+
+Follow these guidelines whenever you add `sandbox.agent.mounts`:
+
+1. **Prefer installing tools inside the container.** Use
+   setup steps or MCP tools instead of mounting host binaries.
+2. **Mount the smallest possible path.** Mount a single file or
+   dedicated directory instead of a whole tree.
+3. **Default to `ro`.** Use `rw` only for explicit output paths
+   such as `/tmp` caches or scratch directories.
+4. **Avoid system and credential paths.** Do not mount
+   `/usr`, `/lib`, `/etc`, `/home`, `/root`, `/proc`, `/sys`,
+   `/dev`, `/var/run`, or `/var/lib/docker`.
+5. **Document the purpose.** Treat mounts as security-sensitive
+   configuration that must be reviewed.
+
+## Safe and unsafe examples
+
+✅ Safe, narrow, read-only mounts:
+
+```yaml wrap
+sandbox:
+  agent:
+    id: awf
+    mounts:
+      - "/opt/tools/custom-cli:/usr/local/bin/custom-cli:ro"
+      - "/opt/data/input:/data/input:ro"
+      - "/tmp/gh-aw-cache:/cache:rw"
+```
+
+❌ Unsafe, overly broad mounts:
+
+```yaml wrap
+sandbox:
+  agent:
+    id: awf
+    mounts:
+      - "/usr:/usr:ro"
+      - "/:/host:ro"
+      - "/var/run/docker.sock:/var/run/docker.sock:rw"
+```
+
+## Checklist for adding new default mounts
+
+Use this checklist when proposing new default mounts:
+
+- [ ] Mount is required for core agent functionality.
+- [ ] No safer alternative exists (install in container or MCP).
+- [ ] Path is as narrow as possible.
+- [ ] Access mode is `ro` unless write access is unavoidable.
+- [ ] Path does not expose system configuration or secrets.
+- [ ] Impact is documented in the security guide and sandbox
+      reference.
+- [ ] Threat model review completed with security reviewers.
+
+## See also
+
+- [Sandbox Configuration](/gh-aw/reference/sandbox/)
+- [Security Best Practices](/gh-aw/guides/security/)
+- [Network Configuration](/gh-aw/reference/network/)
+
+

docs/src/content/docs/guides/security.md → docs/src/content/docs/guides/security/index.md

@@ -106,6 +106,18 @@ Compilation-time security measures include:
 
 Apply defense-in-depth consistently: least privilege by default, default-deny approach, separation of concerns (plan/apply with approval gates), and supply chain integrity (pin to immutable SHAs).
 
+
+## Container Mount Security
+
+Mounting host paths into the agent container expands what the
+workflow can access on the runner. Use mounts only when you
+cannot install tools inside the container or pass data through
+workflow inputs.
+
+See [Container Mount Security](/gh-aw/guides/security/container-mounts/)
+for the threat model, safe vs unsafe examples, and the reviewer
+checklist for new mounts.
+
 ## Implementation Guidelines
 
 ### Workflow Permissions and Triggers
@@ -452,6 +464,7 @@ network: {}
 
 ## See also
 
+- [Container Mount Security](/gh-aw/guides/security/container-mounts/)
 - [Threat Detection Guide](/gh-aw/guides/threat-detection/) - Comprehensive threat detection configuration and examples
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/)
 - [Network Configuration](/gh-aw/reference/network/)

docs/src/content/docs/reference/sandbox.md

@@ -78,6 +78,15 @@ network:
     - "api.example.com"
 ```
 
+
+> [!WARNING]
+> Mounts expand container access to host files.
+> Prefer read-only mounts and avoid system paths
+> like `/usr`, `/lib`, `/etc`, `/home`, `/proc`,
+> `/sys`, `/dev`, and `/var/run`. See
+> [Container Mount Security](/gh-aw/guides/security/container-mounts/)
+> for threat modeling and review guidance.
+
 #### Default Mounted Volumes
 
 AWF automatically mounts several paths from the host into the container to enable agent functionality:

pkg/cli/templates/github-agentic-workflows.md

@@ -138,6 +138,20 @@ The YAML frontmatter supports these fields:
   - Enables searching and retrieving assets associated with this workflow
   - Examples: `"workflow-2024-q1"`, `"team-alpha-bot"`, `"security_audit_v2"`
 
+- **`project:`** - GitHub Projects integration configuration (string or object)
+  - String format: `"https://github.com/orgs/myorg/projects/42"` - Project URL only
+  - Object format for advanced configuration:
+    ```yaml
+    project:
+      url: "https://github.com/orgs/myorg/projects/42"  # Required: full project URL
+      scope: ["owner/repo", "org:name"]                  # Optional: repositories/organizations workflow can operate on
+      max-updates: 100                                   # Optional: max project updates per run (default: 100)
+      max-status-updates: 1                              # Optional: max status updates per run (default: 1)
+      github-token: ${{ secrets.PROJECTS_PAT }}          # Optional: custom token for project operations
+    ```
+  - When configured, enables project board management operations
+  - Works with `update-project` safe-output for automated project tracking
+
 - **`secret-masking:`** - Configuration for secret redaction behavior in workflow outputs and artifacts (object)
   - `steps:` - Additional secret redaction steps to inject after the built-in secret redaction (array)
   - Use this to mask secrets in generated files using custom patterns
@@ -609,6 +623,9 @@ The YAML frontmatter supports these fields:
     safe-outputs:
       assign-to-agent:
         name: "copilot"                 # Optional: agent name
+        allowed: [copilot]              # Optional: restrict to specific agent names
+        max: 1                          # Optional: max assignments (default: 1)
+        target: "*"                     # Optional: "triggering" (default), "*", or number
         target-repo: "owner/repo"       # Optional: cross-repository
     ```
     Requires PAT with elevated permissions as `GH_AW_AGENT_TOKEN`.

specs/README.md

@@ -24,13 +24,14 @@ This directory contains design specifications and implementation documentation f
 | [YAML Version Compatibility](./yaml-version-gotchas.md) | ✅ Documented | `pkg/workflow/compiler.go` |
 | [Schema Validation](./SCHEMA_VALIDATION.md) | ✅ Documented | `pkg/parser/schemas/` |
 | [GitHub Actions Security Best Practices](./github-actions-security-best-practices.md) | ✅ Documented | Workflow security guidelines and patterns |
+| [Container Mount Security Model](./container-security-model.md) | ✅ Documented | Threat model and checklist for host path mounts |
 | [End-to-End Feature Testing](./end-to-end-feature-testing.md) | ✅ Documented | `.github/workflows/dev.md`, `.github/workflows/dev-hawk.md` |
 
 ## Security Reviews
 
 | Document | Date | Status |
 |----------|------|--------|
-| [Template Injection Security Review](./SECURITY_REVIEW_TEMPLATE_INJECTION.md) | 2025-11-11 | ✅ No vulnerabilities found |
+| [Template Injection Security Review](./security_review.md) | 2025-11-11 | ✅ No vulnerabilities found |
 
 ## Comparative Analysis
 

specs/container-security-model.md

@@ -0,0 +1,85 @@
+# Container Mount Security Model
+
+This document defines the threat model and review checklist for
+mounting host paths into agent containers. It complements the
+user-facing guide in
+`docs/src/content/docs/guides/security/container-mounts.md`.
+
+## Scope
+
+This model covers:
+
+- AWF-based agent containers that mount host paths
+- Custom mounts defined by `sandbox.agent.mounts`
+- Default mounts required for agent operation
+
+It does not cover:
+
+- MCP gateway container mounts (see
+  `docs/src/content/docs/reference/mcp-gateway.md`)
+- Sandbox Runtime filesystem rules
+
+## Threat model
+
+### Adversaries
+
+- **Malicious workflow author** with write access tries to
+  expand mounts to access host secrets or runtime internals.
+- **Compromised dependencies** (CLI tools, packages) attempt to
+  read or alter host files exposed through mounts.
+- **Accidental exposure** where legitimate workflows leak
+  sensitive data via overly broad mounts.
+
+### Assets at risk
+
+- GitHub Actions runner configuration and tokens
+- Repository secrets cached on disk
+- Host system binaries and configuration
+- Docker daemon and other privileged sockets
+
+### Abuse paths
+
+1. Mounting system directories (`/usr`, `/lib`, `/etc`) gives
+   read access to host runtime details and secrets.
+2. Mounting `/var/run` or `/dev` can expose control sockets or
+   device interfaces.
+3. Mounting home directories leaks cached tokens, SSH keys, or
+   package manager credentials.
+
+## Existing controls
+
+- **Default mounts are narrow** and explicitly enumerated.
+- **Read-only mounts for binaries** (`/usr/bin/gh`, `yq`, etc.).
+- **No Docker socket mount**: `/var/run/docker.sock` is blocked.
+- **No privileged container flags**: agent container runs
+  without `--privileged` or extra capabilities.
+
+## Required review questions
+
+Use these questions in code review when adding mounts:
+
+1. **Is the mount necessary?** Can the workflow install tools
+   inside the container or use an MCP tool instead?
+2. **Is the path minimal?** Prefer a single file or directory.
+3. **Is the mode correct?** Use `ro` unless write access is
+   essential.
+4. **Is the path sensitive?** Reject mounts that expose system
+   configuration, credentials, or device sockets.
+5. **Is the purpose documented?** Add docs and release notes
+   for any new default mount.
+
+## Default mount change checklist
+
+- [ ] Justification ties to core functionality.
+- [ ] Alternative approaches documented and rejected.
+- [ ] Path is the smallest possible surface.
+- [ ] Access mode is `ro` unless output requires `rw`.
+- [ ] No system, secrets, or socket paths.
+- [ ] Security guide updated.
+- [ ] Sandbox reference updated.
+
+## References
+
+- `docs/src/content/docs/reference/sandbox.md`
+- `docs/src/content/docs/guides/security/container-mounts.md`
+- `specs/github-actions-security-best-practices.md`

specs/github-actions-security-best-practices.md

@@ -1009,7 +1009,7 @@ Use this checklist when creating or reviewing GitHub Actions workflows:
 - [Supply Chain Attacks via Actions](https://blog.gitguardian.com/github-actions-security-cheat-sheet/)
 
 ### Related Documentation (gh-aw specific)
-- [Security Guide](../docs/src/content/docs/guides/security.md)
+- [Security Guide](../docs/src/content/docs/guides/security/index.md)
 - [Safe Outputs](../docs/src/content/docs/reference/safe-outputs/)
 - [Network Configuration](../docs/src/content/docs/reference/network/)
 - [GitHub Agentic Workflows Instructions](../.github/aw/github-agentic-workflows.md)