awguard 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- Scan GitHub Copilot custom agents, reusable prompts, and repository skills under `.github/agents`, `.github/prompts`, and `.github/skills`.
+- Add a scope expansion roadmap for policy mode, agent capability SBOMs, trend reports, and adoption tooling.
+
 ## 1.4.0
 
 - Add `AWG013` for project MCP configs that start mutable packages, unpinned containers, or shell wrappers.

package/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:20-alpine
+
+WORKDIR /app
+COPY package.json README.md LICENSE action.yml ./
+COPY bin ./bin
+COPY src ./src
+
+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,12 @@ Install from npm:
 npx awguard .
 ```
 
+Generate a starter config, GitHub Action, baseline command, and badge snippet:
+
+```bash
+npx awguard init
+```
+
 ## Use In GitHub Actions
 
 After you upload this repository to GitHub, users can add:
@@ -113,7 +122,9 @@ jobs:
 ## CLI
 
 ```bash
-awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge] [--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] [--fail-on none|low|medium|high|critical]
+awguard init
+awguard --compare previous.json current.json
 ```
 
 Examples:
@@ -124,6 +135,8 @@ 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
@@ -131,6 +144,7 @@ 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
 ```
 
@@ -241,6 +255,50 @@ Then add a badge to your README:
 
 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
+
+Generate a repository map of agent-related surfaces:
+
+```bash
+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
+```
+
+The comparison report shows introduced findings, resolved findings, added scanned files, and removed scanned files.
+
+## 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"],
+    "approvedMcpCommands": ["npx", "node"]
+  }
+}
+```
+
+Anything outside the policy is reported as `AWG015`.
+
 ## Agent Context Guard
 
 AWGuard also scans persistent agent instruction files:
@@ -251,6 +309,9 @@ AWGuard also scans persistent agent instruction files:
 - `GEMINI.md`
 - `.github/copilot-instructions.md`
 - `.github/instructions/*.instructions.md`
+- `.github/agents/*.md`
+- `.github/prompts/*.prompt.md`
+- `.github/skills/**/SKILL.md`
 - `.cursor/rules/*.{md,mdc,txt}`
 - `.cursorrules`, `.windsurfrules`, and `.clinerules`
 
@@ -313,6 +374,11 @@ 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 |
+
+## 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.
 
 ## Example Finding
 
@@ -330,10 +396,18 @@ If you omit rule ids, the suppression applies to all findings on the target line
 - 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).
+
 ## Research Backing
 
 See [docs/market-analysis.md](docs/market-analysis.md) for the demand analysis, gap, audience, and launch plan.
+See [docs/roadmap.md](docs/roadmap.md) for the scope expansion roadmap.

package/action.yml

@@ -7,7 +7,7 @@ inputs:
     required: false
     default: .
   format:
-    description: Output format: github, text, json, markdown, sarif, graph, html, migration, score, or badge.
+    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:

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,23 @@
+# Comparison
+
+AWGuard is intentionally narrow. It should sit beside general CI/CD and AI security tools, not replace them.
+
+| 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. |
+
+## Best Stack
+
+Use these together:
+
+```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
+```

package/docs/launch-plan.md

@@ -10,49 +10,64 @@ Short pitch:
 
 ## Star-Worthy Demo
 
-1. Show `examples/unsafe-agent.yml`.
-2. Run:
+1. Show the terminal demo image in `docs/assets/terminal-demo.svg`.
+2. Show `examples/unsafe-agent.yml`.
+3. Run:
 
    ```bash
    node ./bin/awguard.js examples/unsafe-agent.yml --format graph
    ```
 
-3. Show the generated Mermaid chain.
-4. Run:
+4. Show the generated Mermaid chain.
+5. Run:
 
    ```bash
    node ./bin/awguard.js examples/unsafe-agent.yml --fix-dry-run
    ```
 
-5. Show the safe remediation steps.
-6. Run:
+6. Show the safe remediation steps.
+7. Run:
 
    ```bash
    node ./bin/awguard.js examples/unsafe-agent.yml --format migration
    ```
 
-7. Show the migration from unsafe agent job to read-only proposal job plus safe outputs or an approved apply job.
-8. Run:
+8. Show the migration from unsafe agent job to read-only proposal job plus safe outputs or an approved apply job.
+9. Run:
 
    ```bash
    node ./bin/awguard.js . --format score
    ```
 
-9. Show the README badge and say: "Add an AWI risk badge to your repo before adding AI agents to CI."
-10. Show an unsafe `AGENTS.md` or `.github/copilot-instructions.md` line and run:
+10. Show the README badge and say: "Add an AWI risk badge to your repo before adding AI agents to CI."
+11. Run:
+
+   ```bash
+   node ./bin/awguard.js . --format inventory
+   ```
+
+12. Show the surface map and say: "Before you secure agent workflows, find every place the repository gives agents instructions or tools."
+13. Run:
+
+   ```bash
+   node ./bin/awguard.js init
+   ```
+
+14. Show the one-command setup guide.
+15. Show an unsafe `AGENTS.md` or `.github/copilot-instructions.md` line and run:
 
    ```bash
    node ./bin/awguard.js . --format text
    ```
 
-11. Explain that AWGuard scans both the workflow and the persistent agent instructions that shape agent behavior.
-12. Show an unsafe `.mcp.json` with `npx @modelcontextprotocol/server-github` and a committed token, then run:
+16. Explain that AWGuard scans both the workflow and the persistent agent instructions that shape agent behavior.
+17. Show an unsafe `.mcp.json` with `npx @modelcontextprotocol/server-github` and a committed token, then run:
 
    ```bash
    node ./bin/awguard.js examples/.mcp.json --format text
    ```
 
-13. Explain the new hook: "This scanner checks repo-provided MCP tool wiring without executing the MCP server."
+18. Explain the new hook: "This scanner checks repo-provided MCP tool wiring without executing the MCP server."
 
 ## Release Checklist
 

package/docs/market-analysis.md

@@ -197,6 +197,26 @@ Agentic Workflow Guard now supports:
 
 This keeps the project focused: AWGuard does not try to replace MCP runtime scanners. It gives maintainers a GitHub-native, zero-dependency first check before an agent or scanner executes repo-provided MCP server commands.
 
+## Deep Research Refresh: Agentic Surface Inventory
+
+The next scope expansion is an inventory view. GitHub now documents repository-level custom agents in `.github/agents`, Copilot MCP configuration, and custom instructions. VS Code documents workspace MCP config. This means the repository itself can contain multiple agent-control surfaces before a single workflow runs.
+
+The useful maintainer question is no longer only "is this workflow unsafe?" It is:
+
+```text
+what agent surfaces does this repository expose, and which ones changed?
+```
+
+Agentic Workflow Guard now supports:
+
+- `--format inventory` for a surface map grouped by workflows, agent context files, and MCP configs.
+- scanning `.github/agents/*.md`, `.github/prompts/*.prompt.md`, and `.github/skills/**/SKILL.md` as persistent agent context.
+- `awguard init` for adoption snippets, `--format inventory-json` for dashboards, and `--compare` for trend reports.
+- first policy allowlists for approved files, MCP servers, MCP packages, and MCP commands.
+- a roadmap that moves toward agent capability SBOMs, richer policy ownership, and hosted monitoring.
+
+This widens the project while preserving its niche: AWGuard remains a zero-execution repository scanner for agentic risk, not a broad runtime agent firewall.
+
 ## Distribution Plan
 
 1. Publish the repo with a short demo GIF or screenshot.

package/docs/marketplace-listing.md

@@ -0,0 +1,40 @@
+# GitHub Marketplace Listing Draft
+
+## Name
+
+Agentic Workflow Guard
+
+## Short Description
+
+Scan GitHub Actions, agent instruction files, and MCP configs for AI-agent injection risk.
+
+## Categories
+
+- Security
+- Code quality
+- Utilities
+
+## Full Description
+
+Agentic Workflow Guard finds where untrusted GitHub issue, pull request, comment, branch, or artifact text can steer AI agents inside CI.
+
+It scans:
+
+- GitHub Actions workflows;
+- persistent agent instruction files such as `AGENTS.md`, Copilot instructions, custom agents, prompts, and skills;
+- MCP configs such as `.mcp.json`, `.vscode/mcp.json`, Cursor, Windsurf, Cline, and Roo config files.
+
+Outputs include GitHub annotations, SARIF for code scanning, attack graphs, migration plans, AWI scorecards, badges, and agentic surface inventory reports.
+
+## Example
+
+```yaml
+- uses: Mughal-Baig/agentic-workflow-guard@v0
+  with:
+    preset: strict
+    fail-on: high
+```
+
+## Suggested Release Note
+
+Use this Action before adding AI agents, custom prompts, or MCP tools to a repository.

package/docs/roadmap.md

@@ -0,0 +1,75 @@
+# Scope Expansion Roadmap
+
+## Research Signal
+
+AWGuard should widen from "workflow scanner" into an agentic repository safety map while staying small and zero-dependency.
+
+Current research points:
+
+- GitHub Copilot now documents repository-level custom agents in `.github/agents`, repository MCP configuration, and repo-scoped agent behavior.
+- VS Code and Copilot document MCP configuration in repository or workspace files such as `.vscode/mcp.json`.
+- GitHub Actions security docs still warn that attacker-controlled GitHub context must be treated as untrusted input.
+- OpenSSF Scorecard shows that security tools travel further when they produce a simple public score, badge, and clear adoption path.
+- Existing MCP scanners focus on live server/tool inspection; AWGuard's lane is zero-execution repository scanning before those tools start.
+
+## Feature List
+
+1. Agentic Surface Inventory
+   - Add `--format inventory`.
+   - Group scanned files into GitHub Actions workflows, agent context files, and MCP configs.
+   - Show findings, highest severity, and recommended next steps per surface.
+
+2. Wider Agent Context Coverage
+   - Scan `.github/agents/*.md` for Copilot custom agents.
+   - Scan `.github/prompts/*.prompt.md` for reusable prompts.
+   - Scan `.github/skills/**/SKILL.md` for repository skills.
+   - Keep using `AWG012` for risky persistent instructions.
+
+3. Policy Mode
+   - Add an `awguard.policy.json` format for explicit allowlists.
+   - Allow approved MCP commands, package pins, Docker digests, action owners, and workflow write scopes.
+   - Report drift when the repository adds a new agent surface without policy.
+
+4. Setup And Adoption Generator
+   - Add a command that prints a starter GitHub Action, strict config, baseline command, and badge snippet.
+   - Keep it as a print-only generator first so it remains safe.
+
+5. Agent Capability SBOM
+   - Export a machine-readable inventory of agent prompts, tools, MCP servers, permissions, secrets exposure, and write capabilities.
+   - Make it useful for security reviews and audits.
+
+6. Trend Reports
+   - Compare current scan output with a previous JSON report.
+   - Show newly added agent surfaces and newly introduced rules.
+
+7. Vulnerable Lab
+   - Add a set of intentionally unsafe mini-repositories under examples or a separate demo repo.
+   - Each lab should include exploit explanation, AWGuard output, and fixed pattern.
+
+8. GitHub App Or Scheduled Monitor
+   - Long-term: run continuously across repositories.
+   - Open issues when new agent surfaces appear or risk score drops.
+
+## Work Plan
+
+### Now
+
+- Shipped `--format inventory`.
+- Shipped `--format inventory-json`.
+- Shipped `awguard init`.
+- Shipped `--compare previous.json current.json`.
+- Shipped first policy allowlists with `AWG015`.
+- Expanded `AWG012` coverage to Copilot custom agents, prompts, and skills.
+- Added Docker, GitLab CI, pre-commit, VS Code task, Marketplace, comparison, visual demo, and vulnerable lab assets.
+
+### Next
+
+- Add agent capability SBOM export for prompts, tools, MCP servers, permissions, and write paths.
+- Add safer patch previews for common workflow permission fixes.
+- Add richer policy ownership fields for approved file owners and review cadence.
+
+### Later
+
+- Add trend reports for "new agent surface introduced" diffs.
+- Build the vulnerable lab and screenshot-friendly walkthroughs.
+- Explore a GitHub App after the CLI and Action adoption path is stable.