awguard 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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.
+- Add `--format inventory-json` for machine-readable agentic surface inventories.
+- Add `--compare previous.json current.json` for introduced/resolved finding and file drift reports.
+- Add policy allowlists with `AWG015` for unapproved files, MCP servers, packages, or commands.
+- Add Docker, GitLab CI, pre-commit, VS Code task, Marketplace, comparison, demo, and vulnerable lab assets.
+
 ## 1.5.0
 
 - Add `--format inventory` to map agentic repository surfaces by workflows, agent context files, and MCP configs.

package/Dockerfile

@@ -0,0 +1,15 @@
+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

@@ -5,8 +5,11 @@
 [![GitHub release](https://img.shields.io/github/v/release/Mughal-Baig/agentic-workflow-guard)](https://github.com/Mughal-Baig/agentic-workflow-guard/releases)
 [![npm](https://img.shields.io/npm/v/awguard)](https://www.npmjs.com/package/awguard)
 [![AWI risk](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/docs/awguard-badge.json)](docs/awguard-badge.json)
+[![Project site](https://img.shields.io/badge/site-live-0f766e)](https://mughal-baig.github.io/agentic-workflow-guard/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
+![Agentic Workflow Guard terminal demo](docs/assets/terminal-demo.svg)
+
 `agentic-workflow-guard` is a small, zero-dependency scanner for GitHub Actions workflows, persistent agent instruction files, and MCP configs used by AI coding agents, LLMs, or automated review bots.
 
 It looks for a new class of CI/CD risk: untrusted issue, pull request, comment, or branch text flowing into an AI agent prompt, then into write-capable tools, secrets, shell scripts, persistent instructions that weaken review boundaries, or MCP servers that expand agent authority.
@@ -42,6 +45,26 @@ Install from npm:
 npx awguard .
 ```
 
+Generate a starter config, GitHub Action, baseline command, and badge snippet:
+
+```bash
+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:
@@ -60,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
@@ -68,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
@@ -98,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
@@ -113,25 +138,46 @@ jobs:
 ## CLI
 
 ```bash
-awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge|inventory] [--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
 node ./bin/awguard.js . --format html --output awguard-report.html
 node ./bin/awguard.js . --format migration --output awguard-migration.md
 node ./bin/awguard.js . --format inventory
+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
 node ./bin/awguard.js . --baseline awguard.baseline.json --fail-on high
+node ./bin/awguard.js --compare old-awguard.json new-awguard.json
 node ./bin/awguard.js . --format github --fail-on high
 ```
 
@@ -153,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",
@@ -175,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:
 
@@ -240,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
@@ -252,6 +382,44 @@ node ./bin/awguard.js . --format inventory
 
 The inventory groups scanned files into GitHub Actions workflows, persistent agent context files, and MCP configs. It shows which surfaces exist, which rules fired, and what to review next. This is useful before a team enables new coding agents because it answers: "Where can agents read instructions, get tools, or act in CI?"
 
+For dashboards, use JSON:
+
+```bash
+node ./bin/awguard.js . --format inventory-json --output awguard-inventory.json
+```
+
+## Compare Reports
+
+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, 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
+
+Policy mode makes new agent surfaces visible during review. Add allowlists to `awguard.config.json`:
+
+```json
+{
+  "policy": {
+    "approvedFiles": ["AGENTS.md", ".github/workflows/*"],
+    "approvedMcpServers": ["github"],
+    "approvedMcpPackages": ["@modelcontextprotocol/server-github@1.2.3"],
+    "approvedMcpPackageScopes": ["@modelcontextprotocol/"],
+    "approvedMcpCommands": ["npx", "node"]
+  }
+}
+```
+
+Anything outside the policy is reported as `AWG015`.
+
 ## Agent Context Guard
 
 AWGuard also scans persistent agent instruction files:
@@ -287,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
 
@@ -296,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 `--`.
@@ -327,6 +518,38 @@ If you omit rule ids, the suppression applies to all findings on the target line
 | AWG012 | High/Critical | Agent instruction files that weaken approval, permission, or secret boundaries |
 | 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
 
@@ -339,17 +562,14 @@ If you omit rule ids, the suppression applies to all findings on the target line
 
 ## 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 [docs/rule-authoring.md](docs/rule-authoring.md), and report sensitive security issues using [SECURITY.md](SECURITY.md).
 
 ## Research Backing
 

package/action.yml

@@ -7,7 +7,7 @@ inputs:
     required: false
     default: .
   format:
-    description: Output format: github, text, json, markdown, sarif, graph, html, migration, score, badge, or inventory.
+    description: Output format: github, text, json, markdown, sarif, graph, html, migration, score, badge, inventory, or inventory-json.
     required: false
     default: github
   fail-on:
@@ -15,7 +15,7 @@ inputs:
     required: false
     default: high
   output:
-    description: Optional file path for json, markdown, sarif, graph, html, migration, score, or badge output.
+    description: Optional file path for json, markdown, sarif, graph, html, migration, score, badge, inventory, or inventory-json output.
     required: false
     default: ''
   baseline:
@@ -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/assets/terminal-demo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="430" viewBox="0 0 920 430" role="img" aria-labelledby="title desc">
+  <title id="title">Agentic Workflow Guard terminal demo</title>
+  <desc id="desc">A terminal-style screenshot showing AWGuard inventory and MCP findings.</desc>
+  <rect width="920" height="430" rx="10" fill="#101820"/>
+  <rect x="0" y="0" width="920" height="42" rx="10" fill="#17242f"/>
+  <circle cx="24" cy="21" r="6" fill="#ff5f57"/>
+  <circle cx="44" cy="21" r="6" fill="#ffbd2e"/>
+  <circle cx="64" cy="21" r="6" fill="#28c840"/>
+  <text x="88" y="27" fill="#d8e6ee" font-family="Menlo, Consolas, monospace" font-size="14">awguard demo</text>
+  <text x="28" y="78" fill="#7dd3fc" font-family="Menlo, Consolas, monospace" font-size="16">$ npx awguard . --format inventory</text>
+  <text x="28" y="118" fill="#e7f4f2" font-family="Menlo, Consolas, monospace" font-size="16">Agentic Surface Inventory</text>
+  <text x="28" y="154" fill="#a7f3d0" font-family="Menlo, Consolas, monospace" font-size="14">✓ GitHub Actions workflows: 2 files, 0 findings</text>
+  <text x="28" y="184" fill="#fde68a" font-family="Menlo, Consolas, monospace" font-size="14">! Agent context files: 1 file, AWG012</text>
+  <text x="28" y="214" fill="#fca5a5" font-family="Menlo, Consolas, monospace" font-size="14">! MCP configs: 1 file, AWG013, AWG014</text>
+  <text x="28" y="260" fill="#7dd3fc" font-family="Menlo, Consolas, monospace" font-size="16">$ npx awguard examples/.mcp.json --fix-dry-run</text>
+  <text x="28" y="300" fill="#fca5a5" font-family="Menlo, Consolas, monospace" font-size="14">CRITICAL AWG014 MCP config hardcodes secrets or auth material</text>
+  <text x="28" y="330" fill="#fdba74" font-family="Menlo, Consolas, monospace" font-size="14">HIGH AWG013 MCP config starts mutable tool servers</text>
+  <text x="28" y="372" fill="#d8e6ee" font-family="Menlo, Consolas, monospace" font-size="14">Fix: pin tool packages, move credentials to prompts/env, and review policy drift.</text>
+</svg>

package/docs/comparison.md

@@ -0,0 +1,168 @@
+# How AWGuard Compares
+
+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.
+
+## Short Version
+
+| 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. |
+
+## What AWGuard Owns
+
+AWGuard focuses on a threat shape that general CI tools rarely model:
+
+```text
+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/>