From 0bf47a6953ca9164c224edc47df96b8be83e89e1 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 14 Aug 2025 18:52:45 +0100 Subject: [PATCH 1/5] updates to security notes --- README.md | 5 ++++- docs/security.md | 27 ++++++++++++++++++++++----- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 88e3c9e2b7..7f8056bcd6 100644 --- a/README.md +++ b/README.md @@ -149,7 +149,10 @@ This will override the `engine` setting in the frontmatter of the markdown file. ## Security and untrusted inputs -Security is a key consideration when using agentic workflows. Please see the [Security Best Practices](docs/security.md) for guidelines on how to secure your workflows and handle untrusted inputs. +Security is a key consideration when using agentic workflows. Please see the [Security](docs/security.md) for guidelines related to securing your workflows and handling untrusted inputs. + +> [!CAUTION] +> GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use. ## 🔗 Related Projects diff --git a/docs/security.md b/docs/security.md index 9dd566dfb6..ba3d854f75 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,6 +1,9 @@ -# Security Best Practices +# Security Notes -This guide provides security recommendations for Agentic Workflows (AW). The fundamental principle: treat all user-supplied inputs as untrusted, enforcing guardrails through code and configuration rather than prompts alone. +> [!CAUTION] +> GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use. + +This material documents some thinking of the security implications of using partially-automated agentic workflows. It's not a security guide, but rather a set of working notes. ## Before You Begin @@ -17,13 +20,27 @@ Understanding the security risks in agentic workflows helps inform protective me ### Primary Threats -- **Prompt injection and malicious inputs**: Attackers can craft inputs that poison an agent. Agentic workflows often pull data from many sources, including GitHub Issues, PRs, comments, code, and external APIs, so any of those inputs could carry a hidden trigger for AI. -- **Automated execution without review**: Unlike IDEs, agentic workflows may execute code and call tools automatically. If not tightly controlled, an attacker might make the agent fetch and run malicious code. -- **Tool exposure**: Unconstrained MCP tools (filesystem, network) can enable data exfiltration or privilege escalation +- **Malicious inputs**: Attackers can craft inputs that poison an agent. Agentic workflows often pull data from many sources, including GitHub Issues, PRs, comments and code. If considered untrusted, e.g. in an open source setting, any of those inputs could carry a hidden payload for AI. Agentic workflows are designed to minimize the risk of malicious inputs by restricting the expressions that can be used in workflow markdown content. This means inputs such as GitHub Issues and Pull Requests must be accessed via the GitHub MCP, however the returned data can, in principle, be used to manipulate the AI's behavior if not properly assessed and sanitized. +- **Command execution**: Agentic workflows are, by default, configured not to allow the execution of arbitrary shell commands. However, they may optionally be manually configured to allow specific commands, and if so they will not ask for confirmation before executing these specific commands. This execution is performed in the partially-sandboxed environment of GitHub Actions. If not tightly controlled, an attacker might use this capability to make the agent fetch and run malicious code to exfiltrate data or perform unauthorized execution within this environment. +- **Tool exposure**: By default, Agentic Workflows are configured to have no access to MCPs except the GitHub MCP in read-only mode. However unconstrained use of 3rd-party MCP tools can enable data exfiltration or privilege escalation. - **Supply chain attacks**: Unpinned Actions, npm packages and container images are vulnerable to tampering ### Core Security Principles +The fundamental principle of security for Agentic Workflows is that they are GitHub Actions workflows and should be reviewed with the same rigour and rules that are applied to all GitHub Actions. + +This means they inherit the security model of GitHub Actions, which includes: +- **Isolated copy of the repository** - each workflow runs in a separate copy of the repository, so it cannot access other repositories or workflows +- **Read-only defaults** for forked PRs +- **Restricted secret access** - secrets are not available in forked PRs by default +- **Explicit permissions** - all permissions default to `none` unless explicitly set +- **Explicit tool allowlisting** - only tools explicitly allowed in the workflow can be used +- **Highly restricted commands** - by default, no commands are allowed to be executed, and any commands that are allowed must be explicitly specified in the workflow + +In addition, the compilation step of Agentic Workflows enforces additional security measures: +- **Expression restrictions** - only a limited set of expressions are allowed in the workflow frontmatter, preventing arbitrary code execution +- **Tool allowlisting** - only explicitly allowed tools can be used in the workflow + Apply these principles consistently across all workflow components: 1. **Least privilege by default** - elevate permissions only when required, scoped to specific jobs or steps From 2fb2b83f930fda3872c0bbd897029f2b2ef4b168 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 14 Aug 2025 18:58:39 +0100 Subject: [PATCH 2/5] updates to security notes --- README.md | 4 ++-- docs/index.md | 2 +- docs/{security.md => security-notes.md} | 12 ++++++++++-- 3 files changed, 13 insertions(+), 5 deletions(-) rename docs/{security.md => security-notes.md} (89%) diff --git a/README.md b/README.md index 7f8056bcd6..512bec3ddb 100644 --- a/README.md +++ b/README.md @@ -147,9 +147,9 @@ This will override the `engine` setting in the frontmatter of the markdown file. > **🔧 Advanced configuration**: For detailed information about permissions, tools, secrets, and all configuration options, see the [Documentation](docs/index.md) -## Security and untrusted inputs +## Security of Agentic Workflows -Security is a key consideration when using agentic workflows. Please see the [Security](docs/security.md) for guidelines related to securing your workflows and handling untrusted inputs. +Security is a key consideration when using agentic workflows. Please see the [Security Notes](docs/security-notes.md) for guidelines related to workflow security and handling untrusted inputs. > [!CAUTION] > GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use. diff --git a/docs/index.md b/docs/index.md index 5cb44cf567..5f1d1e431b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,4 +17,4 @@ Complete documentation for creating and managing agentic workflows with GitHub A - **[Tools Configuration](tools.md)** - GitHub and other tools setup - **[MCPs](mcps.md)** - Model Context Protocol setup and configuration - **[Secrets Management](secrets.md)** - Managing secrets and environment variables -- **[Security Best Practices](security.md)** - Hardening agentic workflows and MCP tools +- **[Security Notes](security-notes.md)** - Notes on the agentic workflows and security diff --git a/docs/security.md b/docs/security-notes.md similarity index 89% rename from docs/security.md rename to docs/security-notes.md index ba3d854f75..16de1b31d7 100644 --- a/docs/security.md +++ b/docs/security-notes.md @@ -34,12 +34,12 @@ This means they inherit the security model of GitHub Actions, which includes: - **Read-only defaults** for forked PRs - **Restricted secret access** - secrets are not available in forked PRs by default - **Explicit permissions** - all permissions default to `none` unless explicitly set -- **Explicit tool allowlisting** - only tools explicitly allowed in the workflow can be used -- **Highly restricted commands** - by default, no commands are allowed to be executed, and any commands that are allowed must be explicitly specified in the workflow In addition, the compilation step of Agentic Workflows enforces additional security measures: - **Expression restrictions** - only a limited set of expressions are allowed in the workflow frontmatter, preventing arbitrary code execution - **Tool allowlisting** - only explicitly allowed tools can be used in the workflow +- **Highly restricted commands** - by default, no commands are allowed to be executed, and any commands that are allowed must be explicitly specified in the workflow +- **Explicit tool allowlisting** - only tools explicitly allowed in the workflow can be used Apply these principles consistently across all workflow components: @@ -69,6 +69,14 @@ jobs: issues: write # Job-scoped elevation ``` +### Human in the Loop + +GitHub Actions workflows are not designed to be fully autonomous. Some critical operations should always involve human review: +- **Approval gates**: Use manual approval steps for high-risk operations like deployments, secret management, or external tool invocations +- **Pull requests require humans**: GitHub Actions cannot approve or merge pull requests. This means a human will always be involved in reviewing and merging pull requests that contain agentic workflows. +- **Plan-apply separation**: Implement a "plan" phase that generates a preview of actions before execution. This allows human reviewers to assess the impact of changes. This is usually done via a pull request. +- **Review and audit**: Regularly review workflow history, permissions, and tool usage to ensure compliance with security policies. + ### MCP Tool Hardening Model Context Protocol tools require strict containment: From 23c57aedcf9f403c656e99202779f5b985e79742 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 14 Aug 2025 18:59:03 +0100 Subject: [PATCH 3/5] updates to security notes --- docs/security-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security-notes.md b/docs/security-notes.md index 16de1b31d7..8716746168 100644 --- a/docs/security-notes.md +++ b/docs/security-notes.md @@ -3,7 +3,7 @@ > [!CAUTION] > GitHub Agentic Workflows is a research demonstrator, and Agentic Workflows are not for production use. -This material documents some thinking of the security implications of using partially-automated agentic workflows. It's not a security guide, but rather a set of working notes. +This material documents some notes on the security of using partially-automated agentic workflows. ## Before You Begin From 1ac9ead7bc1660249149afc7571f660cea9eb99d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 14 Aug 2025 19:01:30 +0100 Subject: [PATCH 4/5] updates to security notes --- docs/security-notes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/security-notes.md b/docs/security-notes.md index 8716746168..3379f9b70f 100644 --- a/docs/security-notes.md +++ b/docs/security-notes.md @@ -20,14 +20,14 @@ Understanding the security risks in agentic workflows helps inform protective me ### Primary Threats -- **Malicious inputs**: Attackers can craft inputs that poison an agent. Agentic workflows often pull data from many sources, including GitHub Issues, PRs, comments and code. If considered untrusted, e.g. in an open source setting, any of those inputs could carry a hidden payload for AI. Agentic workflows are designed to minimize the risk of malicious inputs by restricting the expressions that can be used in workflow markdown content. This means inputs such as GitHub Issues and Pull Requests must be accessed via the GitHub MCP, however the returned data can, in principle, be used to manipulate the AI's behavior if not properly assessed and sanitized. - **Command execution**: Agentic workflows are, by default, configured not to allow the execution of arbitrary shell commands. However, they may optionally be manually configured to allow specific commands, and if so they will not ask for confirmation before executing these specific commands. This execution is performed in the partially-sandboxed environment of GitHub Actions. If not tightly controlled, an attacker might use this capability to make the agent fetch and run malicious code to exfiltrate data or perform unauthorized execution within this environment. +- **Malicious inputs**: Attackers can craft inputs that poison an agent. Agentic workflows often pull data from many sources, including GitHub Issues, PRs, comments and code. If considered untrusted, e.g. in an open source setting, any of those inputs could carry a hidden payload for AI. Agentic workflows are designed to minimize the risk of malicious inputs by restricting the expressions that can be used in workflow markdown content. This means inputs such as GitHub Issues and Pull Requests must be accessed via the GitHub MCP, however the returned data can, in principle, be used to manipulate the AI's behavior if not properly assessed and sanitized. - **Tool exposure**: By default, Agentic Workflows are configured to have no access to MCPs except the GitHub MCP in read-only mode. However unconstrained use of 3rd-party MCP tools can enable data exfiltration or privilege escalation. -- **Supply chain attacks**: Unpinned Actions, npm packages and container images are vulnerable to tampering +- **Supply chain attacks and other generic GitHub Actions threats**: Unpinned Actions, npm packages and container images are vulnerable to tampering ### Core Security Principles -The fundamental principle of security for Agentic Workflows is that they are GitHub Actions workflows and should be reviewed with the same rigour and rules that are applied to all GitHub Actions. +The fundamental principle of security for Agentic Workflows is that they are GitHub Actions workflows and should be reviewed with the same rigour and rules that are applied to all GitHub Actions. See [GitHub Actions security](https://docs.github.com/en/actions/reference/security/secure-use). This means they inherit the security model of GitHub Actions, which includes: - **Isolated copy of the repository** - each workflow runs in a separate copy of the repository, so it cannot access other repositories or workflows From eb0945992f9e02fb5d79a6f4dffa6dbd414d2365 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 14 Aug 2025 19:11:53 +0100 Subject: [PATCH 5/5] updates to security notes --- docs/security-notes.md | 2 +- pkg/cli/templates/instructions.md | 65 +------------------------------ 2 files changed, 2 insertions(+), 65 deletions(-) diff --git a/docs/security-notes.md b/docs/security-notes.md index 3379f9b70f..500a45d7f0 100644 --- a/docs/security-notes.md +++ b/docs/security-notes.md @@ -20,7 +20,7 @@ Understanding the security risks in agentic workflows helps inform protective me ### Primary Threats -- **Command execution**: Agentic workflows are, by default, configured not to allow the execution of arbitrary shell commands. However, they may optionally be manually configured to allow specific commands, and if so they will not ask for confirmation before executing these specific commands. This execution is performed in the partially-sandboxed environment of GitHub Actions. If not tightly controlled, an attacker might use this capability to make the agent fetch and run malicious code to exfiltrate data or perform unauthorized execution within this environment. +- **Command execution**: Agentic workflows are, executed in the partially-sandboxed environment of GitHub Actions. By default, they are configured disallow the execution of arbitrary shell commands. However, they may optionally be manually configured to allow specific commands, and if so they will not ask for confirmation before executing these specific commands as part of the GitHub Actions workflow run. If these configuration options are used inappropriately, or on sensitive code, an attacker might use this capability to make the agent fetch and run malicious code to exfiltrate data or perform unauthorized execution within this environment. - **Malicious inputs**: Attackers can craft inputs that poison an agent. Agentic workflows often pull data from many sources, including GitHub Issues, PRs, comments and code. If considered untrusted, e.g. in an open source setting, any of those inputs could carry a hidden payload for AI. Agentic workflows are designed to minimize the risk of malicious inputs by restricting the expressions that can be used in workflow markdown content. This means inputs such as GitHub Issues and Pull Requests must be accessed via the GitHub MCP, however the returned data can, in principle, be used to manipulate the AI's behavior if not properly assessed and sanitized. - **Tool exposure**: By default, Agentic Workflows are configured to have no access to MCPs except the GitHub MCP in read-only mode. However unconstrained use of 3rd-party MCP tools can enable data exfiltration or privilege escalation. - **Supply chain attacks and other generic GitHub Actions threats**: Unpinned Actions, npm packages and container images are vulnerable to tampering diff --git a/pkg/cli/templates/instructions.md b/pkg/cli/templates/instructions.md index 2bcd443e6a..ab26dbb03e 100644 --- a/pkg/cli/templates/instructions.md +++ b/pkg/cli/templates/instructions.md @@ -190,12 +190,6 @@ Use GitHub Actions context expressions throughout the workflow content. **Note: - **`${{ github.event.review_comment.id }}`** - ID of the review comment - **`${{ github.event.sender.id }}`** - ID of the user who triggered the event - **`${{ github.event.workflow_run.id }}`** - ID of the workflow run -- **`${{ github.event.workflow_run.conclusion }}`** - Conclusion of the workflow run -- **`${{ github.event.workflow_run.html_url }}`** - URL of the workflow run -- **`${{ github.event.workflow_run.head_sha }}`** - Head SHA of the workflow run -- **`${{ github.event.workflow_run.run_number }}`** - Run number of the workflow run -- **`${{ github.event.workflow_run.event }}`** - Event that triggered the workflow run -- **`${{ github.event.workflow_run.status }}`** - Status of the workflow run - **`${{ github.actor }}`** - Username of the person who initiated the workflow - **`${{ github.job }}`** - Job ID of the current workflow run - **`${{ github.owner }}`** - Owner of the repository @@ -228,8 +222,6 @@ Using output from previous task: "${{ needs.task.outputs.text }}" Deploy to environment: "${{ github.event.inputs.environment }}" -Previous workflow conclusion: "${{ github.event.workflow_run.conclusion }}" - # Invalid expressions (will cause compilation errors) # Token: ${{ secrets.GITHUB_TOKEN }} # Environment: ${{ env.MY_VAR }} @@ -436,64 +428,9 @@ permissions: models: read # Typically needed for AI workflows ``` -### Security Best Practices (summary) - -The following condensed guidance is adapted from the full Security Best Practices guide in `docs/security.md`: - -- Review before install: treat prompt templates, includes, and rules as code. Always inspect compiled `.lock.yml` to see actual permissions and steps. -- Understand defaults: once any permission is set at the workflow level, all others default to `none`. Elevate narrowly at job/step scope. -- Threat model highlights: prompt injection via issues/PRs/comments/code; automated execution without review; over-broad tool exposure; supply chain risks from unpinned actions/images. -- Core principles: least privilege; default-deny tool allowlists; separate plan vs. apply with approval gates for risky actions; pin all dependencies by immutable SHAs/digests. - -#### Practical implementation - -- Workflow permissions - - Keep top-level minimal (e.g., `contents: read`). - - Elevate per job only when required (e.g., a comment job needs `issues: write`). - - - Example: - ```yaml - permissions: - contents: read - - jobs: - comment: - permissions: - issues: write - ``` - -- MCP tool hardening - - Sandbox: run MCP servers in isolated containers, non-root, least capabilities; disable privilege escalation; apply seccomp/AppArmor where supported. - - Supply chain: pin images/binaries to digests/SHAs; scan for vulns; track SBOMs. - - Access control: start with empty allowlists; grant only required verbs/hosts. - - - Example (pinned container with minimal allowances): - ```yaml - tools: - web: - mcp: - container: "ghcr.io/example/web-mcp@sha256:abc123..." # pinned digest - allowed: [fetch] - ``` - -- Network egress filtering - - Prefer outbound allowlists (proxy or policy) for MCP tools and any web access. - -- Agent safety and policy - - Reduce exposure to untrusted inputs; strip embedded commands when not needed. - - Use plan-validate-execute: require validation checkpoints before executing high-risk tool calls. - -- Supply chain integrity - - Pin GitHub Actions by SHA, containers by digest; avoid floating tags. - -For deeper guidance and references, see the full guide: `docs/security.md`. - ## Compilation Process Agentic workflows compile to GitHub Actions YAML: - - `.github/workflows/example.md` → `.github/workflows/example.lock.yml` - Include dependencies are resolved and merged - Tool configurations are processed @@ -519,4 +456,4 @@ The workflow frontmatter is validated against JSON Schema during compilation. Co - **Invalid enum values** - e.g., `engine` must be "claude" or "codex" - **Missing required fields** - Some triggers require specific configuration -Use `gh aw compile --verbose` to see detailed validation messages. +Use `gh aw compile --verbose` to see detailed validation messages. \ No newline at end of file