Document container mount security model and guidance

[Copilot]

This adds security documentation for mounting host paths into agent containers, covering threat modeling, safeguards, and best practices for workflow authors and reviewers.

• Security guide additions

  • New container mount security guide with threat model, risks, controls, best practices, and reviewer checklist.
  • Linked the new guide from the main security best practices page.

• Reference updates

  • Added mount safety warning and link in sandbox reference.
  • Updated internal references to the moved security guide path.

• Specs and policy

  • Added container mount security model spec and listed it in specs index.
  • Extended SECURITY.md with container mount guidance and doc link.

Example (safe vs unsafe mount patterns):

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"

Screenshot

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build iptables -w ithub/workflows security /usr/bin/infocmp OUTPUT -d 168.63.129.16 infocmp -1 k/gh-aw/gh-aw/.github/workflows 53 /usr/bin/infocmp l GO111MODULE 64/bin/go infocmp (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Document security implications and best practices for container mounting</issue_title>
<issue_description>## Objective

Create comprehensive security documentation explaining the risks and best practices for mounting host paths into the agent container.

Context

As we expand what's mounted from the host runner into the agent container, we need clear security guidance:

• What are the risks of mounting /usr/bin, /lib, etc.?
• What protections are in place (read-only mounts)?
• What should NOT be mounted?
• How to minimize attack surface?
• What's the threat model?

Approach

1. Research Docker mount security best practices
2. Document threat model for agent container:
   • Malicious workflow attempting to escape container
   • Compromised dependencies trying to access host
   • Accidental exposure of sensitive data
3. Document current security controls:
   • Read-only mounts (ro flag)
   • Limited mount set (principle of least privilege)
   • No access to Docker socket
   • No privileged mode
4. Provide guidelines for workflow authors:
   • When custom mounts are safe vs risky
   • How to minimize dependencies
   • Alternative approaches (install tools inside container)
5. Create security checklist for adding new mounts

Files to Create/Modify

• Create: docs/src/content/docs/guides/security/container-mounts.md (security guide)
• Update: docs/src/content/docs/reference/sandbox.md (add security section)
• Create: specs/container-security-model.md (threat model documentation)
• Update: SECURITY.md (add container security section if applicable)

Acceptance Criteria

• Document explains threat model clearly
• Current security controls are documented
• Best practices provided for workflow authors
• Guidelines for adding new default mounts
• Examples show safe vs unsafe mounting patterns
• Checklist helps reviewers assess security of mount changes

Related

Provides security context for all mounting work (#11971, #11972, #11973, #11974)
Related to #11970

AI generated by Plan Command for #11970

Comments on the Issue (you are @copilot in this section)

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

• Fixes [plan] Document security implications and best practices for container mounting #12380

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 45/100

Scores Breakdown

• Impact: 15/50 - Documentation/test improvement
• Urgency: 15/30 - 0 days old, 0 comments
• Quality: 15/20 - Description: good, CI: unknown

📋 Recommended Action: defer

Low impact or work in progress

---

Triaged by PR Triage Agent on 2026-01-29

AI generated by PR Triage Agent

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 35/100

Scores Breakdown

• Impact: 15/50 - Documents container mount security model
• Urgency: 10/30 - 2 days old
• Quality: 10/20 - Draft status, CI pending

📋 Recommended Action: batch_review

Part of Batch #3: Documentation (batch-docs-001) along with PR #12444. Security documentation requires careful review.

---

Triaged by PR Triage Agent on 2026-01-31 | Run #21540069309

AI generated by PR Triage Agent

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 40/100

Scores Breakdown

• Impact: 15/50 - Docs with low risk level
• Urgency: 10/30 - Recent PR (2 days), CI pending
• Quality: 15/20 - CI pending, Draft status

📋 Recommended Action: Batch Review

This PR is recommended for batch review with similar PRs.

📦 Batch Processing

This PR is part of batch-docs-001 with 1 other PR(s): #12444

Consider reviewing these PRs together for consistency and efficiency.

---

Triaged by PR Triage Agent on 2026-01-31 12:17 UTC
See full report: PR Triage Discussion

AI generated by PR Triage Agent