From 74ac9adb761d7a66faa23c0c50a307bff9877f56 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 23 Jul 2026 12:02:35 +0000 Subject: [PATCH] split workshop step 05 into intro (7.76) and security (8.64) pages Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../workshop-student-journey.js | 15 +++++ workshop/05-agentic-workflows-intro.md | 49 +-------------- workshop/05b-agentic-workflows-security.md | 62 +++++++++++++++++++ workshop/README.md | 1 + 4 files changed, 80 insertions(+), 47 deletions(-) create mode 100644 workshop/05b-agentic-workflows-security.md diff --git a/.github/skills/micro-environment-simulator/workshop-student-journey.js b/.github/skills/micro-environment-simulator/workshop-student-journey.js index 15096351..04d59e4e 100644 --- a/.github/skills/micro-environment-simulator/workshop-student-journey.js +++ b/.github/skills/micro-environment-simulator/workshop-student-journey.js @@ -33,6 +33,7 @@ const STEP_FILE_ALIASES = { "02-setup": ["02a-setup-codespace.md", "02b-setup-local.md", "02c-setup-browser.md"], "04-actions-intro": ["04-github-actions-intro.md"], "05-agentic-intro": ["05-agentic-workflows-intro.md"], + "05b-agentic-security": ["05b-agentic-workflows-security.md"], "06-install-gh-aw": [ "06-install-gh-aw.md", "06a-install-terminal.md", @@ -71,6 +72,7 @@ const STEP_IDS = [ "02-setup", "04-actions-intro", "05-agentic-intro", + "05b-agentic-security", "06-install-gh-aw", "07-first-workflow", "08-run-your-workflow", @@ -655,6 +657,19 @@ function buildTransitions() { next.flags.sawAgenticIntro = true; return { ok: true, state: applyLearning(next, context, { agentic: 0.1, actions: 0.03 }) }; }, + "05b-agentic-security": (state, context) => { + const readiness = contentReadinessCheck(state, context, { + salt: 79, + category: "agentic-security-gap", + failedAssumption: "The learner does not grasp how the sandbox and safe-output system together prevent agents from causing damage when run unattended.", + remediation: "Reinforce the two-layer security model with a concrete scenario that distinguishes the sandbox from the safe-output guardrails.", + emphasis: { conceptWeight: 0.14, bias: 0.06 } + }); + if (!readiness.ok) return readiness; + const next = cloneState(state); + next.flags.sawAgenticSecurity = true; + return { ok: true, state: applyLearning(next, context, { agentic: 0.06, concepts: 0.04 }) }; + }, "06-install-gh-aw": (state, context) => { const envCheck = ensure( state.flags.environmentReady, diff --git a/workshop/05-agentic-workflows-intro.md b/workshop/05-agentic-workflows-intro.md index 71e8ef48..83069298 100644 --- a/workshop/05-agentic-workflows-intro.md +++ b/workshop/05-agentic-workflows-intro.md @@ -19,9 +19,7 @@ An [**Agentic Workflow**](https://github.github.com/gh-aw/introduction/overview/ Think of it like a **scheduled email digest** you've set up in an app: every morning it reads your inbox, picks out the three most important messages, and sends you a one-paragraph summary — without you touching a keyboard. An agentic workflow does the same thing for your GitHub repository: it runs on a schedule, reads your issues, pull requests, or code, and posts a structured summary exactly where your team will see it. You describe the job in plain English; the agent figures out how to do it. -The part that makes this safe to run unattended: the agent operates **read-only inside a [sandbox](https://github.github.com/gh-aw/reference/sandbox/)** with controlled network access, and it can never write to your repo directly. Anything the agent wants to change flows through a guardrailed **[safe-output](https://github.github.com/gh-aw/reference/safe-outputs/)** system, where a separate, permission-scoped job validates the request before acting. - -![Animated GitHub Actions run showing four security jobs: activation validates the agent is authorized to run, agent runs with sandbox, firewall, and integrity filter enabled, detection scans for malicious code, and safe-outputs applies changes within guardrails](images/05-agent-run-log.svg) +The agent always runs within a sandbox and posts results through a guardrailed output system — you will explore how this works in [How Agentic Workflows Stay Safe](05b-agentic-workflows-security.md).
Why not just use a standard Actions workflow? @@ -86,48 +84,6 @@ The **compile command** — it reads the `.md` source and writes the `.lock.yml` > [!TIP] > Want more examples of how the two-file structure works? [Side Quest: Agentic Workflows Deep Dive](side-quest-05-02-aw-deep-dive.md) includes a fully annotated workflow pair. -## Safe by design: sandbox + guardrailed outputs - -Letting an AI agent act on your repository on a schedule only works if it can't do damage. Agentic workflows enforce two trust boundaries so you can run agents in automation with confidence: - -- **A [sandbox](https://github.github.com/gh-aw/reference/sandbox/) around the agent.** The agent runs isolated inside the [Agent Workflow Firewall](https://github.github.com/gh-aw/reference/sandbox/), with **read-only** access to your repo and network egress limited to the domains you allow. Even if a prompt injection or a compromised tool tries to reach out or exfiltrate data, the firewall blocks anything outside the allowlist. -- **A guardrailed [safe-output](https://github.github.com/gh-aw/reference/safe-outputs/) system for writes.** The agent never holds write permissions. Instead, it emits a *structured request* — "create this issue," "post this comment" — and a separate, permission-scoped job validates and executes it, applying per-operation limits (max counts, label and title constraints, allowed repos). That separation gives you least privilege, defense against prompt injection, and a full audit trail of every action. - -The security jobs in the run log above map to these boundaries: **activation** checks the agent is authorized to run, the **agent** runs sandboxed behind the firewall, **detection** scans for malicious behavior, and **safe-outputs** applies changes within the guardrails. - -
-Why can't the agent just write to the repo directly? - -Direct write access would make every prompt injection a potential supply-chain attack. By keeping the agent read-only and routing all changes through the safe-output system, a malicious instruction the agent picks up from issue text or a fetched page can, at worst, produce a *request* that the guardrails then reject or cap — it can never silently push code, leak secrets, or open unlimited pull requests. - -
- -## Try it: sandbox or safe-output? - -For each scenario below, decide whether the **sandbox** or the **safe-output system** is the primary defence. Make your decision before revealing the answer. - -**Scenario A:** A prompt injected into an issue comment instructs the agent to push to a protected branch. - -- [ ] I've made my decision for Scenario A - -
-Reveal Scenario A answer - -**Safe-output system.** The agent holds no write permissions. Even if the injected instruction causes the agent to produce a write request, the separate permission-scoped job validates it against the guardrails and rejects any operation outside the allowed set. - -
- -**Scenario B:** A page the agent fetches during a run tries to send your repository secrets to an external server. - -- [ ] I've made my decision for Scenario B - -
-Reveal Scenario B answer - -**Sandbox / Agent Workflow Firewall.** Outbound network traffic is limited to the domain allowlist. Any request to an unlisted domain is blocked at the firewall before it leaves the runner — the exfiltration attempt never reaches the external server. - -
- ## Try it: agentic or standard? For each task below, decide whether it calls for an **agentic workflow** or a **standard Actions workflow**, then reveal the answer. @@ -183,8 +139,7 @@ as an issue with the title "Weekly PR Digest". - [ ] I can describe what an agentic workflow is in one sentence - [ ] I can explain one way an agentic workflow differs from a standard Actions workflow - [ ] I can identify the three parts: trigger → agent → safe output -- [ ] I can explain how the sandbox and safe-output system keep the agent safe to run in automation -**Next:** [Install the gh-aw CLI Extension](06-install-gh-aw.md) +**Next:** [How Agentic Workflows Stay Safe](05b-agentic-workflows-security.md) diff --git a/workshop/05b-agentic-workflows-security.md b/workshop/05b-agentic-workflows-security.md new file mode 100644 index 00000000..5bcae32d --- /dev/null +++ b/workshop/05b-agentic-workflows-security.md @@ -0,0 +1,62 @@ + + +# How Agentic Workflows Stay Safe + +## 📋 Before You Start + +- You've read [What Are Agentic Workflows?](05-agentic-workflows-intro.md) + +Letting an AI agent act on your repository on a schedule only works if it can't do damage. Agentic workflows enforce two trust boundaries so you can run agents in automation with confidence. + +![Animated GitHub Actions run showing four security jobs: activation validates the agent is authorized to run, agent runs with sandbox, firewall, and integrity filter enabled, detection scans for malicious code, and safe-outputs applies changes within guardrails](images/05-agent-run-log.svg) + +## Safe by design: sandbox + guardrailed outputs + +- **A [sandbox](https://github.github.com/gh-aw/reference/sandbox/) around the agent.** The agent runs isolated inside the [Agent Workflow Firewall](https://github.github.com/gh-aw/reference/sandbox/), with **read-only** access to your repo and network egress limited to the domains you allow. Even if a prompt injection or a compromised tool tries to reach out or exfiltrate data, the firewall blocks anything outside the allowlist. +- **A guardrailed [safe-output](https://github.github.com/gh-aw/reference/safe-outputs/) system for writes.** The agent never holds write permissions. Instead, it emits a *structured request* — "create this issue," "post this comment" — and a separate, permission-scoped job validates and executes it, applying per-operation limits (max counts, label and title constraints, allowed repos). That separation gives you least privilege, defense against prompt injection, and a full audit trail of every action. + +The security jobs in the run log above map to these boundaries: **activation** checks the agent is authorized to run, the **agent** runs sandboxed behind the firewall, **detection** scans for malicious behavior, and **safe-outputs** applies changes within the guardrails. + +
+Why can't the agent just write to the repo directly? + +Direct write access would make every prompt injection a potential supply-chain attack. By keeping the agent read-only and routing all changes through the safe-output system, a malicious instruction the agent picks up from issue text or a fetched page can, at worst, produce a *request* that the guardrails then reject or cap — it can never silently push code, leak secrets, or open unlimited pull requests. + +
+ +## Try it: sandbox or safe-output? + +For each scenario below, decide whether the **sandbox** or the **safe-output system** is the primary defence. Make your decision before revealing the answer. + +**Scenario A:** A prompt injected into an issue comment instructs the agent to push to a protected branch. + +- [ ] I've made my decision for Scenario A + +
+Reveal Scenario A answer + +**Safe-output system.** The agent holds no write permissions. Even if the injected instruction causes the agent to produce a write request, the separate permission-scoped job validates it against the guardrails and rejects any operation outside the allowed set. + +
+ +**Scenario B:** A page the agent fetches during a run tries to send your repository secrets to an external server. + +- [ ] I've made my decision for Scenario B + +
+Reveal Scenario B answer + +**Sandbox / Agent Workflow Firewall.** Outbound network traffic is limited to the domain allowlist. Any request to an unlisted domain is blocked at the firewall before it leaves the runner — the exfiltration attempt never reaches the external server. + +
+ +## ✅ Checkpoint + +- [ ] I can describe what the sandbox does and why it matters for automation safety +- [ ] I can explain how the safe-output system prevents the agent from writing to the repo directly +- [ ] I can identify whether the sandbox or the safe-output system is the primary defence for a given scenario +- [ ] I can explain how the two-layer model makes agentic workflows safe to run on a schedule + + +**Next:** [Install the gh-aw CLI Extension](06-install-gh-aw.md) + diff --git a/workshop/README.md b/workshop/README.md index fbacc3bc..c46b724f 100644 --- a/workshop/README.md +++ b/workshop/README.md @@ -11,6 +11,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo | 2 | Choose one: [02a-setup-codespace.md](02a-setup-codespace.md), [02b-setup-local.md](02b-setup-local.md), **or** [02c-setup-browser.md](02c-setup-browser.md) | Setup Adventure — A: Codespace, B: Local Terminal, or C: Browser (no terminal) | ✅ | | 4 | [04-github-actions-intro.md](04-github-actions-intro.md) | What Are GitHub Actions? | ✅ | | 5 | [05-agentic-workflows-intro.md](05-agentic-workflows-intro.md) | What Are Agentic Workflows? | ✅ | +| 5b | [05b-agentic-workflows-security.md](05b-agentic-workflows-security.md) | How Agentic Workflows Stay Safe | ✅ | | 6 | [06-install-gh-aw.md](06-install-gh-aw.md) | Install the gh-aw CLI Extension | ✅ | | 6a | [06a-install-terminal.md](06a-install-terminal.md) | Codespace Terminal Path — Install gh-aw | ✅ | | 6b | [06b-install-local.md](06b-install-local.md) | Local Terminal Path — Install gh-aw | ✅ |