Skip to content

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

@github-actions

Description

@github-actions

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

Metadata

Metadata

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions