Add security guidelines

README.md

@@ -145,21 +145,11 @@ gh aw add weekly-research --engine codex
 
 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.
-
-This repository is for demonstration purposes and the workflows are not intended to be run in production. The workflows are designed to be run in a controlled environment.
-
-⚠️ You should carefully review the contents of any workflow before installing it, especially if you have not authored it, as it may contain workflows that you do not want to run in your repository.
-
-⚠️⚠️ You should carefully review and assess the compiled workflows before adding them to your repository. You should assess the permissions required by the workflows, and ensure that they are appropriate for your repository. You can do this by reviewing the `.lock.yml` file for your workflow.
-
-⚠️⚠️ GitHub Actions applies many organization settings, limitations and defaults to help protect repositories from unintended actions. For example, by default workflows run in a read-only mode, and do not have access to secrets, when run over pull requests from forks. These rules all apply to agentic workflows as well. You can read more about [GitHub Actions security](https://docs.github.com/en/actions/reference/security/secure-use) and [GitHub Actions permissions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions) in the documentation.
+> **🔧 Advanced configuration**: For detailed information about permissions, tools, secrets, and all configuration options, see the [Documentation](docs/index.md)
 
-⚠️⚠️ If you specify the access for any permissions, all of those that are not specified are set to none.
+## Security and untrusted inputs
 
-> **🔧 Advanced configuration**: For detailed information about permissions, tools, secrets, and all configuration options, see the [Documentation](docs/index.md)
+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.
 
 ## 🔗 Related Projects
 

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

docs/security.md

@@ -0,0 +1,112 @@
+# Security Best Practices
+
+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.
+
+## Before You Begin
+
+When working with agentic workflows, thorough review is essential:
+
+1. **Review workflow contents** before installation, particularly third-party workflows that may contain unexpected automation. Treat prompt templates and rule files as code.
+2. **Assess compiled workflows** (`.lock.yml` files) to understand the actual permissions and operations being performed
+3. **Understand GitHub's security model** - GitHub Actions provides built-in protections like read-only defaults for fork PRs and restricted secret access. These apply to agentic workflows as well. See [GitHub Actions security](https://docs.github.com/en/actions/reference/security/secure-use) and [permissions documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions)
+4. **Remember permission defaults** - when you specify any permission explicitly, all unspecified permissions default to `none`
+
+## Threat Model
+
+Understanding the security risks in agentic workflows helps inform protective measures:
+
+### 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
+- **Supply chain attacks**: Unpinned Actions, npm packages and container images are vulnerable to tampering
+
+### Core Security Principles
+
+Apply these principles consistently across all workflow components:
+
+1. **Least privilege by default** - elevate permissions only when required, scoped to specific jobs or steps
+2. **Default-deny approach** - explicitly allowlist tools
+3. **Separation of concerns** - implement "plan" and "apply" phases with approval gates for risky operations
+4. **Supply chain integrity** - pin all dependencies (Actions, containers) to immutable SHAs
+
+## Implementation Guidelines
+
+### Workflow Permissions and Triggers
+
+Configure GitHub Actions with defense in depth:
+
+#### Permission Configuration
+
+Set minimal top-level permissions and elevate only where necessary:
+
+```yaml
+permissions:
+  contents: read  # Minimal baseline
+  # All others default to none
+
+jobs:
+  comment:
+    permissions:
+      issues: write  # Job-scoped elevation
+```
+
+### MCP Tool Hardening
+
+Model Context Protocol tools require strict containment:
+
+#### Sandboxing and Isolation
+
+Run MCP servers in explicit sandboxes to constrain blast radius:
+
+- Container isolation: Prefer running each MCP server in its own container with no shared state between workflows, repos, or users.
+- Non-root, least-capability: Use non-root UIDs, drop Linux capabilities, and apply seccomp/AppArmor where supported. Disable privilege escalation.
+- Supply-chain sanity: Use pinned images/binaries (digest/SHAs), run vulnerability scans, and track SBOMs for MCP containers.
+
+Example (pinned container with minimal allowances):
+
+```yaml
+tools:
+  web:
+    mcp:
+      container: "ghcr.io/example/web-mcp@sha256:abc123..."  # Pinned image digest
+    allowed: [fetch]
+```
+
+#### Access Control Strategy
+
+Start with empty allowlists and grant permissions incrementally:
+
+```yaml
+tools:
+  github:
+    allowed: [add_issue_comment]  # Minimal required verbs
+  web:
+    mcp:
+      allowed: [fetch]
+  container: my-registry/my-image@sha256:abc123...
+```
+
+#### Egress Filtering
+
+A critical guardrail is strict control over outbound network connections. Consider using network proxies to enforce allowlists for outbound hosts.
+
+### Agent Security and Prompt Injection Defense
+
+Protect against model manipulation through layered defenses:
+
+#### Policy Enforcement
+
+- **Input sanitization**: Minimize untrusted content exposure; strip embedded commands when not required for functionality
+- **Action validation**: Implement a plan-validate-execute flow where policy layers check each tool call against risk thresholds
+
+## See also
+
+- [Tools Configuration](tools.md)
+- [MCPs](mcps.md)
+- [Secrets Management](secrets.md)
+
+## References
+
+- Model Context Protocol: Security Best Practices (2025-06-18) — <https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices>

pkg/cli/templates/instructions.md

@@ -436,9 +436,64 @@ 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
@@ -464,4 +519,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.