awguard 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## Unreleased
+
+## 1.7.0 - 2026-05-30
+
+- Add `awguard doctor` for setup, config, scan target, schema, and GitHub Actions summary checks.
+- Add `awguard explain AWG###` for rule-level explanations and remediation guidance.
+- Add `awguard badges` to print copyable README badge snippets.
+- Add `awguard demo` for an offline unsafe-to-fixed vulnerable lab walkthrough.
+- Add `awguard templates` for GitHub Actions, code scanning, GitLab CI, pre-commit, and VS Code snippets.
+- Add `awguard policy-pack` for OSS, strict, and enterprise policy starter configs.
+- Add `scan.include` and `scan.exclude` config globs for narrowing discovered scan files.
+- Add `AWG016`, `AWG017`, and `AWG018` for checkout credentials, unsafe agent writeback, and MCP input injection.
+- Improve SARIF metadata with stable AWGuard fingerprints, categories, snippets, and columns.
+- Move the JavaScript GitHub Action runtime and bundled workflow templates to Node 24-ready actions.
+- Add machine-readable remediation codes to JSON and SARIF findings.
+- Add scan guardrails for maximum discovered files and maximum scanned file size.
+- Add end-to-end golden tests for unsafe/fixed labs, compare, inventory, and score outputs.
+- Add `awguard baseline-review` with explicit `--prune` support for stale baselines.
+- Add `awguard policy-wizard` for reviewed policy allowlist starter configs.
+- Add a safe PR comment workflow example and Docker image publishing workflow.
+- Add `schemas/awguard.config.schema.json` for editor validation of AWGuard config files.
+- Add schemas for JSON scan reports, inventories, comparisons, baselines, and badge endpoints.
+- Add compare report surface diffs and `--compare ... --format json`.
+- Add automatic GitHub Actions job summaries with scan metrics and top findings.
+- Add expanded comparison, setup recipe, report gallery, rule authoring, release checklist, and npm trusted publishing docs.
+- Add a trusted publishing GitHub Actions workflow for tokenless npm releases.
+- Add a real-world pattern corpus for unsafe agent workflow, prompt, instruction, Cursor rule, and MCP examples.
+- Add VS Code task, problem matcher, and extension proof-of-concept assets.
+- Add a local dashboard proof of concept for AWI score and finding trends.
+- Add opt-in `--fix` for narrow workflow hardening edits and improve `--fix-dry-run` with an autofix plan.
+- Add `AWG019` for offline MCP package reputation policy using trusted package scopes.
+
 ## 1.6.0
 
 - Add `awguard init` to print starter GitHub Action, strict config, baseline, report, and badge setup snippets.

package/Dockerfile

@@ -1,8 +1,15 @@
-FROM node:20-alpine
+FROM node:24-alpine
+
+LABEL org.opencontainers.image.title="Agentic Workflow Guard"
+LABEL org.opencontainers.image.description="Scan GitHub Actions workflows, agent instructions, and MCP configs for agentic workflow risk."
+LABEL org.opencontainers.image.source="https://github.com/Mughal-Baig/agentic-workflow-guard"
+LABEL org.opencontainers.image.licenses="MIT"
 
 WORKDIR /app
 COPY package.json README.md LICENSE action.yml ./
 COPY bin ./bin
 COPY src ./src
+RUN chmod +x /app/bin/awguard.js && ln -s /app/bin/awguard.js /usr/local/bin/awguard
 
+WORKDIR /repo
 ENTRYPOINT ["node", "/app/bin/awguard.js"]

package/README.md

@@ -51,6 +51,20 @@ Generate a starter config, GitHub Action, baseline command, and badge snippet:
 npx awguard init
 ```
 
+Check your local setup, config discovery, scan target, and GitHub Actions summary support:
+
+```bash
+npx awguard doctor
+```
+
+Explain a rule, print README badge snippets, or run the built-in vulnerable lab demo:
+
+```bash
+npx awguard explain AWG001
+npx awguard badges --repo OWNER/REPO --site https://OWNER.github.io/REPO/
+npx awguard demo
+```
+
 ## Use In GitHub Actions
 
 After you upload this repository to GitHub, users can add:
@@ -69,7 +83,7 @@ jobs:
   scan-agent-workflows:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: Mughal-Baig/agentic-workflow-guard@v0
         with:
           config: awguard.config.json
@@ -77,6 +91,8 @@ jobs:
           fail-on: high
 ```
 
+When AWGuard runs inside GitHub Actions it also writes a job summary with scanned file count, finding count, highest severity, top findings, and follow-up commands.
+
 To adopt the scanner without breaking CI on old findings, commit a baseline file and use:
 
 ```yaml
@@ -107,7 +123,7 @@ jobs:
   scan:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: Mughal-Baig/agentic-workflow-guard@v0
         with:
           format: sarif
@@ -122,14 +138,30 @@ jobs:
 ## CLI
 
 ```bash
-awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge|inventory|inventory-json] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fail-on none|low|medium|high|critical]
+awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge|inventory|inventory-json] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fix] [--fail-on none|low|medium|high|critical]
 awguard init
+awguard doctor [path] [--config file] [--preset name]
+awguard explain [AWG###]
+awguard badges [--repo OWNER/REPO] [--branch main] [--badge-file docs/awguard-badge.json] [--site URL]
+awguard demo
+awguard templates [all|github|code-scanning|gitlab|pre-commit|vscode]
+awguard policy-pack [oss|strict|enterprise]
+awguard policy-wizard [path] [--dry-run] [--format markdown|json] [--output awguard.config.json]
+awguard baseline-review [path] --baseline awguard.baseline.json [--format text|json] [--prune]
 awguard --compare previous.json current.json
 ```
 
 Examples:
 
 ```bash
+node ./bin/awguard.js doctor
+node ./bin/awguard.js explain AWG013
+node ./bin/awguard.js badges --repo Mughal-Baig/agentic-workflow-guard --site https://mughal-baig.github.io/agentic-workflow-guard/
+node ./bin/awguard.js demo
+node ./bin/awguard.js templates github
+node ./bin/awguard.js policy-pack strict
+node ./bin/awguard.js policy-wizard . --dry-run
+node ./bin/awguard.js baseline-review . --baseline awguard.baseline.json
 node ./bin/awguard.js examples/unsafe-agent.yml
 node ./bin/awguard.js . --config awguard.config.json
 node ./bin/awguard.js . --preset strict --format graph
@@ -140,6 +172,7 @@ node ./bin/awguard.js . --format inventory-json --output awguard-inventory.json
 node ./bin/awguard.js . --format score
 node ./bin/awguard.js . --format badge --output awguard-badge.json
 node ./bin/awguard.js . --fix-dry-run
+node ./bin/awguard.js . --fix
 node ./bin/awguard.js . --format markdown --fail-on medium
 node ./bin/awguard.js . --format sarif --output awguard.sarif --fail-on none
 node ./bin/awguard.js . --write-baseline awguard.baseline.json
@@ -166,12 +199,29 @@ node ./bin/awguard.js . --baseline awguard.baseline.json --fail-on high
 
 The baseline stores stable finding fingerprints, not secrets or workflow contents.
 
+Review and prune stale baseline entries:
+
+```bash
+node ./bin/awguard.js baseline-review . --baseline awguard.baseline.json
+node ./bin/awguard.js baseline-review . --baseline awguard.baseline.json --format json
+node ./bin/awguard.js baseline-review . --baseline awguard.baseline.json --prune
+```
+
+`baseline-review` never rewrites the baseline unless `--prune` is present.
+
 ## Configuration
 
 Agentic Workflow Guard automatically loads `awguard.config.json` or `.awguard.json` from the scan root. You can also pass `--config`.
 
 ```json
 {
+  "$schema": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json",
+  "scan": {
+    "include": [".github/workflows/*", "AGENTS.md", ".mcp.json"],
+    "exclude": ["node_modules/*", "dist/*", "build/*"],
+    "maxFiles": 250,
+    "maxFileBytes": 262144
+  },
   "rules": {
     "AWG010": "off",
     "AWG008": "low",
@@ -188,6 +238,67 @@ Agentic Workflow Guard automatically loads `awguard.config.json` or `.awguard.js
 
 Rule values can be `"off"`, `"low"`, `"medium"`, `"high"`, or `"critical"`.
 See `examples/awguard.config.example.json` for a complete template.
+The config schema is published at `schemas/awguard.config.schema.json` for editor completion and validation.
+`scan.maxFiles` and `scan.maxFileBytes` are optional guardrails for very large repositories; leave them out if you do not want hard limits.
+
+Generate starter policy packs:
+
+```bash
+node ./bin/awguard.js policy-pack oss
+node ./bin/awguard.js policy-pack strict
+node ./bin/awguard.js policy-pack enterprise
+```
+
+Generate a starter policy from the current repository surfaces:
+
+```bash
+node ./bin/awguard.js policy-wizard . --dry-run
+node ./bin/awguard.js policy-wizard . --format json --output awguard.config.json
+```
+
+Review the generated allowlists before committing them. The wizard preserves existing config fields when you pass `--config`.
+
+Generate CI and editor templates:
+
+```bash
+node ./bin/awguard.js templates all
+node ./bin/awguard.js templates code-scanning
+node ./bin/awguard.js templates pre-commit
+```
+
+PR comment bot starter:
+
+- Copy `examples/pr-comment-bot.yml` to `.github/workflows/awguard-pr-comment.yml`.
+- It uses `pull_request`, `contents: read`, and `pull-requests: write`.
+- It only posts comments for same-repository pull requests; forked pull requests still get the scan job without exposing secrets or privileged `pull_request_target` behavior.
+
+Docker usage:
+
+```bash
+docker run --rm -v "$PWD:/repo" ghcr.io/mughal-baig/agentic-workflow-guard:latest . --preset strict
+```
+
+GitHub Actions Docker job:
+
+```yaml
+jobs:
+  awguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: docker run --rm -v "$PWD:/repo" ghcr.io/mughal-baig/agentic-workflow-guard:latest . --preset strict --fail-on high
+```
+
+GitLab CI container job:
+
+```yaml
+awguard:
+  image:
+    name: ghcr.io/mughal-baig/agentic-workflow-guard:latest
+    entrypoint: [""]
+  script:
+    - awguard . --preset strict --fail-on high
+```
 
 Built-in presets:
 
@@ -253,6 +364,12 @@ Then add a badge to your README:
 [![AWI risk](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/docs/awguard-badge.json)](docs/awguard-badge.json)
 ```
 
+Or print all common badge snippets:
+
+```bash
+node ./bin/awguard.js badges --repo OWNER/REPO
+```
+
 The score starts at 100 and subtracts risk for critical, high, medium, and low findings. This makes AWGuard easy to show in a README without hiding the detailed SARIF, graph, and migration reports.
 
 ## Agentic Surface Inventory
@@ -278,9 +395,12 @@ Track newly introduced agentic risk across branches or releases:
 ```bash
 node ./bin/awguard.js . --format json --output current-awguard.json
 node ./bin/awguard.js --compare previous-awguard.json current-awguard.json
+node ./bin/awguard.js --compare previous-awguard.json current-awguard.json --format json
 ```
 
-The comparison report shows introduced findings, resolved findings, added scanned files, and removed scanned files.
+The comparison report shows introduced findings, resolved findings, added scanned files, removed scanned files, and agentic surface drift by workflows, agent context files, MCP configs, and other scanned files.
+
+Machine-readable report schemas are documented in [docs/schemas.md](docs/schemas.md).
 
 ## Policy Mode
 
@@ -292,6 +412,7 @@ Policy mode makes new agent surfaces visible during review. Add allowlists to `a
     "approvedFiles": ["AGENTS.md", ".github/workflows/*"],
     "approvedMcpServers": ["github"],
     "approvedMcpPackages": ["@modelcontextprotocol/server-github@1.2.3"],
+    "approvedMcpPackageScopes": ["@modelcontextprotocol/"],
     "approvedMcpCommands": ["npx", "node"]
   }
 }
@@ -334,6 +455,7 @@ AWGuard also scans project-scoped MCP config files without starting the configur
 - `claude_desktop_config.json`
 
 It flags MCP configs that start mutable packages such as `npx package`, `uvx package@latest`, or unpinned Docker images, and configs that commit tokens, API keys, passwords, or authorization headers.
+When `policy.approvedMcpPackageScopes` is configured, it also reports MCP packages outside reviewed publisher scopes as `AWG019` without contacting package registries.
 
 ## Fix Dry Run
 
@@ -343,6 +465,28 @@ Print remediation guidance without editing files:
 node ./bin/awguard.js examples/unsafe-agent.yml --fix-dry-run
 ```
 
+Apply only narrow, deterministic workflow hardening edits:
+
+```bash
+node ./bin/awguard.js . --fix
+```
+
+Autofix currently handles safe `permissions: write-all` replacement, missing top-level `permissions: contents: read`, and `actions/checkout` `persist-credentials: false`. Review `git diff` before committing.
+
+## Explain And Demo
+
+Explain any rule:
+
+```bash
+node ./bin/awguard.js explain AWG004
+```
+
+Run the built-in unsafe-to-fixed lab walkthrough without network access:
+
+```bash
+node ./bin/awguard.js demo
+```
+
 ## Inline Suppressions
 
 Suppressions are for reviewed false positives. They must include a reason after `--`.
@@ -375,11 +519,38 @@ If you omit rule ids, the suppression applies to all findings on the target line
 | AWG013 | High | MCP configs that start mutable packages, unpinned containers, or shell wrappers |
 | AWG014 | Critical | MCP configs that hardcode secrets, tokens, passwords, or auth headers |
 | AWG015 | Medium | Agentic surfaces, MCP servers, packages, or commands not approved by policy |
+| AWG016 | High | Checkout credentials persisting in elevated agent workflows |
+| AWG017 | Critical | Agent writeback without branch, PR, or artifact containment |
+| AWG018 | High/Critical | Untrusted GitHub event text passed into MCP tool inputs or environment |
+| AWG019 | Medium | MCP packages outside configured trusted package scopes |
+
+JSON and SARIF outputs also include a stable `remediationCode` such as `permissions.tighten-token`, `mcp.pin-server`, or `writeback.use-pr-branch`. Use these codes for dashboards, routing, and automation that should not depend on free-text suggestions.
 
 ## How It Compares
 
 See [docs/comparison.md](docs/comparison.md) for how AWGuard fits beside `zizmor`, `actionlint`, OpenSSF Scorecard, secret scanners, and MCP runtime scanners.
 
+## Adoption Docs
+
+- [Setup recipes](docs/setup-recipes.md): Claude Code, Codex, Cursor, GitHub Copilot, Cline, and safe PR comment bots.
+- [Report gallery](docs/report-gallery.md): text, GitHub annotations, SARIF, inventory, attack graph, HTML, migration, score, badge, compare, and policy wizard outputs.
+- [Rule authoring](docs/rule-authoring.md): how to add high-signal AWGuard rules and fixtures.
+- [npm publishing](docs/npm-publishing.md): trusted publishing, OIDC, and provenance setup.
+- [Release checklist](docs/release-checklist.md): Marketplace screenshots, package checks, and release steps.
+- [VS Code extension POC](examples/vscode-extension/README.md): command palette scan, diagnostics, and `$awguard` problem matcher.
+- [Dashboard POC](examples/dashboard/README.md): local trend dashboard for AWI score, findings, and agentic surface growth.
+
+## Example Corpus
+
+The [real-world pattern corpus](examples/corpus/README.md) contains intentionally unsafe fixtures for PR review agents, `pull_request_target`, persistent instructions, reusable prompts, Cursor rules, and MCP configs.
+
+Run it locally:
+
+```bash
+node ./bin/awguard.js examples/corpus --format inventory
+node ./bin/awguard.js examples/corpus --format migration
+```
+
 ## Example Finding
 
 ```text
@@ -391,21 +562,14 @@ See [docs/comparison.md](docs/comparison.md) for how AWGuard fits beside `zizmor
 
 ## Roadmap
 
-- Safe autofix for low-risk permission changes.
-- Safe-output migration patch previews for common triage and review bots.
 - Hosted AWI score API for dynamic cross-repository badges.
-- Agent instruction file rule packs for Copilot, Claude Code, Codex, Gemini, Cursor, and Windsurf.
-- MCP config rule packs for Claude Code, Copilot, VS Code, Cursor, Windsurf, Cline, and Roo.
-- Policy mode for approved MCP packages, actions, token scopes, and agent context files.
 - Agent capability SBOM for prompts, tools, MCP servers, permissions, and write paths.
 - Trend reports that show newly added agent surfaces and newly introduced findings.
 - GitHub App integration for always-on repository monitoring.
-- Rule packs for Claude Code, Codex, Gemini, Copilot, Aider, and custom agents.
-- Public vulnerable workflow lab with attack and fix walkthroughs.
 
 ## Contributing And Security
 
-Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and report sensitive security issues using [SECURITY.md](SECURITY.md).
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/rule-authoring.md](docs/rule-authoring.md), and report sensitive security issues using [SECURITY.md](SECURITY.md).
 
 ## Research Backing
 

package/action.yml

@@ -38,8 +38,12 @@ inputs:
     description: Print remediation guidance instead of the normal report.
     required: false
     default: 'false'
+  fix:
+    description: Apply narrow safe workflow hardening edits instead of the normal report. Review git diff before committing generated changes.
+    required: false
+    default: 'false'
 runs:
-  using: node20
+  using: node24
   main: bin/awguard.js
 branding:
   icon: shield

package/docs/comparison.md

@@ -1,23 +1,168 @@
-# Comparison
+# How AWGuard Compares
 
-AWGuard is intentionally narrow. It should sit beside general CI/CD and AI security tools, not replace them.
+Agentic Workflow Guard is not trying to replace general GitHub Actions linters, project health scorecards, secret scanners, or live MCP inspectors. Its lane is narrower: find places where repository automation gives AI agents attacker-influenced text, tools, secrets, or write authority.
 
-| Tool | Main job | Where AWGuard differs |
-| --- | --- | --- |
-| `zizmor` | General GitHub Actions security analysis | AWGuard focuses on AI-agent prompt, tool, MCP, and repository instruction paths. |
-| `actionlint` | GitHub Actions syntax and workflow linting | AWGuard looks for agentic trust-boundary risk, not YAML correctness. |
-| OpenSSF Scorecard | Open-source project security posture | AWGuard gives an Agentic Workflow Injection score and agent surface inventory. |
-| MCP runtime scanners | Inspect live MCP servers and tool descriptions | AWGuard scans repository MCP configs without executing server commands. |
-| Secret scanners | Find committed secrets | AWGuard connects MCP/agent secret exposure to agent capabilities and remediation. |
+## Short Version
 
-## Best Stack
+| Tool | Best at | AWGuard difference | Use together |
+| --- | --- | --- | --- |
+| `zizmor` | Static security analysis for GitHub Actions. | AWGuard adds AI-agent prompt flow, MCP config, persistent agent instruction, and writeback boundary checks. | Run `zizmor` for broad Actions hardening, then AWGuard for agentic workflow injection risk. |
+| `actionlint` | Syntax, expression, input, and workflow semantics checks for GitHub Actions. | AWGuard is not a syntax checker. It assumes valid YAML and looks for trust-boundary patterns. | Run `actionlint` first so broken workflows are caught before security review. |
+| OpenSSF Scorecard | Repository-level supply-chain health signals. | AWGuard produces a focused AWI score, inventory, SARIF, and attack graph for agentic surfaces. | Use Scorecard for public trust posture, AWGuard for AI-agent risk inside the repo. |
+| Secret scanners | Hardcoded credential detection and push protection. | AWGuard looks for secrets exposed to untrusted agent workflows and MCP configs, even when the secret is referenced through `${{ secrets.NAME }}`. | Keep GitHub secret scanning enabled, then use AWGuard to check whether agents can reach secrets. |
+| MCP runtime scanners | Live server and tool behavior inspection. | AWGuard is zero-execution. It reviews committed MCP config before a server starts. | Run AWGuard in CI, then run live MCP inspection in a sandbox for approved servers. |
 
-Use these together:
+## What AWGuard Owns
+
+AWGuard focuses on a threat shape that general CI tools rarely model:
 
 ```text
-actionlint -> workflow correctness
-zizmor -> broad GitHub Actions hardening
-OpenSSF Scorecard -> project posture
-secret scanning -> committed credentials
-AWGuard -> agentic workflow, context, and MCP trust boundaries
+untrusted GitHub event text
+  -> AI agent prompt, instruction, MCP input, or shell script
+  -> tools, secrets, token permissions, or repository writeback
+  -> repository change, data exposure, or unsafe automation
 ```
+
+The scanner turns that shape into:
+
+- Rule findings such as `AWG001`, `AWG004`, `AWG012`, `AWG013`, `AWG017`, and `AWG018`.
+- SARIF for GitHub code scanning.
+- Human-readable attack graphs and migration plans.
+- Agentic surface inventories for workflows, instruction files, and MCP configs.
+- Baselines and compare reports for gradual adoption.
+- Policy allowlists for reviewed files, MCP servers, packages, and commands.
+
+## Tool-by-tool Notes
+
+### zizmor
+
+[`zizmor`](https://docs.zizmor.sh/) is a static analysis tool for GitHub Actions and can find common CI/CD security issues. AWGuard should sit beside it, not in front of it.
+
+Use `zizmor` for:
+
+- GitHub Actions security audits.
+- Broad CI/CD hardening checks.
+- Existing GitHub Actions security recipes and integrations.
+
+Use AWGuard for:
+
+- Agent prompts built from issue, comment, PR, branch, or workflow input text.
+- Agent jobs with broad write permissions or persisted checkout credentials.
+- Unsafe agent writeback paths.
+- MCP configs that use mutable packages, shell wrappers, unpinned containers, or hardcoded credentials.
+- Persistent agent instruction files that weaken approval or secret boundaries.
+
+### actionlint
+
+[`actionlint`](https://github.com/rhysd/actionlint) is a static checker for GitHub Actions workflows. It checks syntax, expression semantics, action usage, reusable workflow contracts, and shell/python snippets.
+
+Use `actionlint` for:
+
+- Invalid workflow keys.
+- Broken `${{ }}` expressions.
+- Missing or mismatched reusable workflow inputs.
+- Shellcheck-style script quality.
+
+Use AWGuard after that for:
+
+- Whether a valid workflow gives an AI agent too much authority.
+- Whether untrusted GitHub context reaches an AI prompt, MCP input, or shell boundary.
+- Whether an agent workflow is safe to run on PRs, comments, and issue events.
+
+### OpenSSF Scorecard
+
+[OpenSSF Scorecard](https://github.com/ossf/scorecard) evaluates repository security health. Its checks include areas such as dangerous workflows, pinned dependencies, packaging, token permissions, and vulnerabilities.
+
+Use Scorecard for:
+
+- Public repository trust signals.
+- Broad open-source security hygiene.
+- A badge that maintainers and users already recognize.
+
+Use AWGuard for:
+
+- A narrower score around Agentic Workflow Injection risk.
+- Reviewable findings that explain which exact prompt, workflow, instruction, or MCP config creates the risk.
+- Repository-specific adoption artifacts: baselines, migration plans, and policy allowlists.
+
+### GitHub Secret Scanning And Other Secret Scanners
+
+[GitHub secret scanning](https://docs.github.com/en/code-security/concepts/secret-security/about-secret-scanning) detects exposed credentials in code, issues, PRs, discussions, wikis, and other supported surfaces. GitHub also documents ways to enable additional leak detection and push protection.
+
+Use secret scanners for:
+
+- Detecting leaked token values.
+- Blocking supported secrets before they land.
+- Alerting and rotation workflows.
+
+Use AWGuard for:
+
+- Finding workflows where `${{ secrets.NAME }}` is available to an untrusted AI-agent job.
+- Finding committed MCP auth material in project-scoped configs.
+- Explaining how to split privileged secrets into reviewed workflows.
+
+### MCP Runtime Scanners
+
+Runtime MCP scanners and inspectors can execute or introspect live servers. AWGuard intentionally does not start MCP servers. That makes it safe to run in pull requests and on untrusted branches.
+
+Use runtime inspection for:
+
+- Tool schemas.
+- Server behavior.
+- Network access and live capabilities.
+
+Use AWGuard for:
+
+- Pre-execution review of committed `.mcp.json`, `.vscode/mcp.json`, Cursor, Windsurf, Cline, Roo, and similar config files.
+- Mutable package and container launch detection.
+- Policy drift when a new MCP server appears in the repository.
+
+## Recommended Stack
+
+For a public repository using AI coding agents:
+
+```yaml
+name: Security
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  actions-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: actionlint
+
+  agentic-workflow-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Mughal-Baig/agentic-workflow-guard@v0
+        with:
+          preset: strict
+          format: sarif
+          output: awguard.sarif
+          fail-on: high
+      - uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: awguard.sarif
+          category: agentic-workflow-guard
+```
+
+Add `zizmor`, Scorecard, and secret scanning according to the repository's security program. AWGuard is the agentic layer in that stack.
+
+## Official References
+
+- zizmor documentation: <https://docs.zizmor.sh/>
+- actionlint repository: <https://github.com/rhysd/actionlint>
+- OpenSSF Scorecard repository: <https://github.com/ossf/scorecard>
+- GitHub secret scanning docs: <https://docs.github.com/en/code-security/concepts/secret-security/about-secret-scanning>
+- npm trusted publishing docs: <https://docs.npmjs.com/trusted-publishers/>

package/docs/launch-plan.md

@@ -68,12 +68,21 @@ Short pitch:
    ```
 
 18. Explain the new hook: "This scanner checks repo-provided MCP tool wiring without executing the MCP server."
+19. Show the real-world corpus:
+
+   ```bash
+   node ./bin/awguard.js examples/corpus --format inventory
+   ```
+
+20. Explain that visitors can clone the repo and see high-signal findings immediately, without needing a real vulnerable project.
 
 ## Release Checklist
 
-- Publish GitHub release notes for `v1.0.0`.
+- Use `docs/release-checklist.md` for the release gate.
+- Use `docs/report-gallery.md` for screenshot commands.
+- Publish GitHub release notes for the target version.
 - Add the action to GitHub Marketplace from the release UI.
-- Publish the npm package as `awguard`; do not use `agentic-workflow-guard` because that npm name is already controlled by another maintainer.
+- Publish the npm package as `awguard` with trusted publishing when possible.
 - Pin the README demo to the attack graph, not the rule table.
 - Post with the headline: "I built a scanner that maps and migrates Agentic Workflow Injection in GitHub Actions."
 - Include the AWI attack chain screenshot in social posts.
@@ -81,6 +90,7 @@ Short pitch:
 - Include the AWI risk badge as the final screenshot because it is the easiest artifact for other maintainers to copy.
 - Include a short "workflow looked safe, AGENTS.md made it unsafe" example because it is the most surprising hook.
 - Include a short "MCP config looked like developer tooling, but it gave the agent a mutable tool server and a token" example because MCP is the hottest adjacent security topic.
+- Include the setup recipes link so Claude Code, Codex, Cursor, Copilot, and Cline users have an immediate next step.
 
 ## Distribution Targets
 

package/docs/marketplace-listing.md

@@ -38,3 +38,22 @@ Outputs include GitHub annotations, SARIF for code scanning, attack graphs, migr
 ## Suggested Release Note
 
 Use this Action before adding AI agents, custom prompts, or MCP tools to a repository.
+
+## Screenshot Plan
+
+1. Terminal demo from `docs/assets/terminal-demo.svg`.
+2. Inventory output from `node ./bin/awguard.js examples/corpus --format inventory`.
+3. Attack graph from `node ./bin/awguard.js examples/lab/unsafe --format graph`.
+4. Migration plan from `node ./bin/awguard.js examples/lab/unsafe --format migration`.
+5. GitHub Code Scanning page after SARIF upload.
+6. Policy wizard output from `node ./bin/awguard.js policy-wizard examples/corpus --dry-run`.
+7. Dashboard POC from `examples/dashboard`.
+8. VS Code Problems panel from `examples/vscode-extension`.
+
+## Docs To Link
+
+- Comparison: `docs/comparison.md`
+- Setup recipes: `docs/setup-recipes.md`
+- Report gallery: `docs/report-gallery.md`
+- Rule authoring: `docs/rule-authoring.md`
+- Release checklist: `docs/release-checklist.md`