From 4edd49aba00858b834ea7df5f491d068bf4e3397 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 28 Jan 2026 23:16:38 +0000 Subject: [PATCH 1/4] Initial plan From a7b684db0d9806f658b33059bf572db1402a3412 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 28 Jan 2026 23:29:45 +0000 Subject: [PATCH 2/4] Plan container mount security docs Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --- pkg/cli/templates/github-agentic-workflows.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/pkg/cli/templates/github-agentic-workflows.md b/pkg/cli/templates/github-agentic-workflows.md index aeb7321327..70a786b553 100644 --- a/pkg/cli/templates/github-agentic-workflows.md +++ b/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`. From 9f608159e5c3ea769aa9f27b49f61673acd33fd2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 29 Jan 2026 00:00:48 +0000 Subject: [PATCH 3/4] Document container mount security guidance Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --- .github/aw/runbooks/workflow-health.md | 2 +- SECURITY.md | 12 ++ .../docs/guides/security/container-mounts.md | 124 ++++++++++++++++++ .../guides/{security.md => security/index.md} | 13 ++ docs/src/content/docs/reference/sandbox.md | 9 ++ specs/README.md | 3 +- specs/container-security-model.md | 85 ++++++++++++ .../github-actions-security-best-practices.md | 2 +- 8 files changed, 247 insertions(+), 3 deletions(-) create mode 100644 docs/src/content/docs/guides/security/container-mounts.md rename docs/src/content/docs/guides/{security.md => security/index.md} (97%) create mode 100644 specs/container-security-model.md diff --git a/.github/aw/runbooks/workflow-health.md b/.github/aw/runbooks/workflow-health.md index e995523f2c..5a1043326d 100644 --- a/.github/aw/runbooks/workflow-health.md +++ b/.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) diff --git a/SECURITY.md b/SECURITY.md index f5cf4bfea6..02cbb4e818 100644 --- a/SECURITY.md +++ b/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. diff --git a/docs/src/content/docs/guides/security/container-mounts.md b/docs/src/content/docs/guides/security/container-mounts.md new file mode 100644 index 0000000000..43beadc2ef --- /dev/null +++ b/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/) + + diff --git a/docs/src/content/docs/guides/security.md b/docs/src/content/docs/guides/security/index.md similarity index 97% rename from docs/src/content/docs/guides/security.md rename to docs/src/content/docs/guides/security/index.md index 251ddaa8e1..9c9ef14697 100644 --- a/docs/src/content/docs/guides/security.md +++ b/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/) diff --git a/docs/src/content/docs/reference/sandbox.md b/docs/src/content/docs/reference/sandbox.md index db6b347541..2c7a19e27d 100644 --- a/docs/src/content/docs/reference/sandbox.md +++ b/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: diff --git a/specs/README.md b/specs/README.md index d7ee6e47b9..bec7e43fca 100644 --- a/specs/README.md +++ b/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 diff --git a/specs/container-security-model.md b/specs/container-security-model.md new file mode 100644 index 0000000000..16e3a2f56d --- /dev/null +++ b/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` diff --git a/specs/github-actions-security-best-practices.md b/specs/github-actions-security-best-practices.md index 72d2357ff8..f9e13e3358 100644 --- a/specs/github-actions-security-best-practices.md +++ b/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) From 210d537fab8f390319c82783282e9be1d2284a04 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 29 Jan 2026 00:04:57 +0000 Subject: [PATCH 4/4] Tidy container mount security wording Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --- docs/src/content/docs/guides/security/container-mounts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/security/container-mounts.md b/docs/src/content/docs/guides/security/container-mounts.md index 43beadc2ef..8d7ce57193 100644 --- a/docs/src/content/docs/guides/security/container-mounts.md +++ b/docs/src/content/docs/guides/security/container-mounts.md @@ -25,7 +25,7 @@ filesystem boundary. Consider three main threats: ## Current security controls -gh-aw limits the default mount set and applies defense in depth: +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.