awguard 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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/README.md

@@ -113,7 +113,7 @@ 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] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fail-on none|low|medium|high|critical]
 ```
 
 Examples:
@@ -124,6 +124,7 @@ 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 score
 node ./bin/awguard.js . --format badge --output awguard-badge.json
 node ./bin/awguard.js . --fix-dry-run
@@ -241,6 +242,16 @@ 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?"
+
 ## Agent Context Guard
 
 AWGuard also scans persistent agent instruction files:
@@ -251,6 +262,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`
 
@@ -330,6 +344,9 @@ 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.
@@ -337,3 +354,4 @@ If you omit rule ids, the suppression applies to all findings on the target line
 ## 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, or inventory.
     required: false
     default: github
   fail-on:

package/docs/launch-plan.md

@@ -39,20 +39,27 @@ Short pitch:
    ```
 
 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. Run:
+
+   ```bash
+   node ./bin/awguard.js . --format inventory
+   ```
+
+11. Show the surface map and say: "Before you secure agent workflows, find every place the repository gives agents instructions or tools."
+12. 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:
+13. Explain that AWGuard scans both the workflow and the persistent agent instructions that shape agent behavior.
+14. 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."
+15. 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,24 @@ 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.
+- a roadmap that moves toward policy mode, agent capability SBOMs, trend reports, and adoption generators.
+
+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/roadmap.md

@@ -0,0 +1,71 @@
+# 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
+
+- Ship `--format inventory`.
+- Expand `AWG012` coverage to Copilot custom agents, prompts, and skills.
+- Document the widened project roadmap.
+
+### Next
+
+- Add policy mode for MCP server allowlists and approved agent context files.
+- Add a setup generator for the GitHub Action, config, baseline, and README badge.
+- Add JSON inventory output for downstream dashboards.
+
+### 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.

package/examples/README.md

@@ -14,6 +14,7 @@ Try:
 node ../bin/awguard.js unsafe-agent.yml --format graph
 node ../bin/awguard.js unsafe-agent.yml --format html --output awguard-report.html
 node ../bin/awguard.js unsafe-agent.yml --format migration
+node ../bin/awguard.js . --format inventory
 node ../bin/awguard.js unsafe-agent.yml --format score
 node ../bin/awguard.js safe-agent.yml --format badge
 node ../bin/awguard.js .mcp.json --format text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awguard",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Scan GitHub Actions workflows, agent instructions, and MCP configs for AI-agent injection and unsafe tool boundaries.",
   "type": "module",
   "homepage": "https://github.com/Mughal-Baig/agentic-workflow-guard#readme",

package/src/cli.js

@@ -5,12 +5,24 @@ import { applyBaseline, createBaseline, loadBaseline, writeBaseline } from './ba
 import { loadConfig } from './config.js';
 import { renderFixDryRun } from './remediation.js';
 import { scanWorkflows, severityRank } from './scanner.js';
-import { renderBadge, renderGithubAnnotations, renderGraph, renderHtml, renderJson, renderMarkdown, renderMigration, renderSarif, renderScore, renderText } from './reporters.js';
+import {
+  renderBadge,
+  renderGithubAnnotations,
+  renderGraph,
+  renderHtml,
+  renderJson,
+  renderMarkdown,
+  renderMigration,
+  renderSarif,
+  renderScore,
+  renderSurfaceInventory,
+  renderText
+} from './reporters.js';
 
 const HELP = `Agentic Workflow Guard
 
 Usage:
-  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] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fail-on none|low|medium|high|critical]
 
 Examples:
   awguard .
@@ -20,6 +32,7 @@ Examples:
   awguard .github/workflows/agent.yml --format markdown --fail-on high
   awguard . --format html --output awguard-report.html
   awguard . --format migration --output awguard-migration.md
+  awguard . --format inventory
   awguard . --format score
   awguard . --format badge --output awguard-badge.json
   awguard . --fix-dry-run
@@ -121,7 +134,19 @@ export function parseArgs(args, env = {}) {
     }
   }
 
-  validateEnum('format', options.format, ['text', 'json', 'markdown', 'github', 'sarif', 'graph', 'html', 'migration', 'score', 'badge']);
+  validateEnum('format', options.format, [
+    'text',
+    'json',
+    'markdown',
+    'github',
+    'sarif',
+    'graph',
+    'html',
+    'migration',
+    'score',
+    'badge',
+    'inventory'
+  ]);
   validateEnum('fail-on', options.failOn, ['none', 'low', 'medium', 'high', 'critical']);
 
   return options;
@@ -141,6 +166,7 @@ function render(result, format) {
   if (format === 'migration') return renderMigration(result);
   if (format === 'score') return renderScore(result);
   if (format === 'badge') return renderBadge(result);
+  if (format === 'inventory') return renderSurfaceInventory(result);
   if (format === 'github') return renderGithubAnnotations(result);
   return renderText(result);
 }

package/src/inventory.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import { classifyScanFile, severityRank } from './scanner.js';
+
+const surfaceLabels = {
+  'github-workflow': 'GitHub Actions workflows',
+  'agent-context': 'Agent context files',
+  'mcp-config': 'MCP configs',
+  other: 'Other scanned files'
+};
+
+const surfaceOrder = ['github-workflow', 'agent-context', 'mcp-config', 'other'];
+
+export function buildInventory(result) {
+  const fileRows = result.scannedFiles.map((file) => {
+    const relativeFile = path.relative(result.root, file) || file;
+    const surface = classifyScanFile(file, result.root);
+    const findings = result.findings.filter((finding) => finding.file === relativeFile);
+
+    return {
+      file: relativeFile,
+      surface,
+      label: surfaceLabels[surface] || surfaceLabels.other,
+      findings: findings.length,
+      highest: highestSeverity(findings),
+      rules: [...new Set(findings.map((finding) => finding.ruleId))]
+    };
+  });
+
+  const surfaces = surfaceOrder
+    .map((surface) => {
+      const files = fileRows.filter((file) => file.surface === surface);
+      const findings = result.findings.filter((finding) => files.some((file) => file.file === finding.file));
+
+      return {
+        surface,
+        label: surfaceLabels[surface],
+        files: files.length,
+        findings: findings.length,
+        highest: highestSeverity(findings),
+        rules: [...new Set(findings.map((finding) => finding.ruleId))]
+      };
+    })
+    .filter((surface) => surface.files > 0);
+
+  return {
+    summary: {
+      scannedFiles: result.scannedFiles.length,
+      surfaces: surfaces.length,
+      findings: result.findings.length,
+      highest: result.summary.highest
+    },
+    surfaces,
+    files: fileRows,
+    recommendations: recommendationsFor(surfaces, result.findings)
+  };
+}
+
+export function renderInventory(result) {
+  const inventory = buildInventory(result);
+  const lines = [
+    '# Agentic Surface Inventory',
+    '',
+    `Scanned files: **${inventory.summary.scannedFiles}**`,
+    `Agentic surfaces: **${inventory.summary.surfaces}**`,
+    `Findings: **${inventory.summary.findings}**`,
+    `Highest severity: **${inventory.summary.highest}**`,
+    '',
+    '## Surface Summary',
+    '',
+    '| Surface | Files | Findings | Highest | Rules |',
+    '| --- | ---: | ---: | --- | --- |'
+  ];
+
+  if (inventory.surfaces.length === 0) {
+    lines.push('| None found | 0 | 0 | none |  |');
+  } else {
+    for (const surface of inventory.surfaces) {
+      lines.push(
+        `| ${surface.label} | ${surface.files} | ${surface.findings} | ${surface.highest} | ${
+          surface.rules.length > 0 ? surface.rules.join(', ') : ''
+        } |`
+      );
+    }
+  }
+
+  lines.push('', '## Files', '', '| Surface | File | Findings | Highest | Rules |', '| --- | --- | ---: | --- | --- |');
+
+  if (inventory.files.length === 0) {
+    lines.push('| None found |  | 0 | none |  |');
+  } else {
+    for (const file of inventory.files) {
+      lines.push(
+        `| ${file.label} | \`${escapeMarkdown(file.file)}\` | ${file.findings} | ${file.highest} | ${
+          file.rules.length > 0 ? file.rules.join(', ') : ''
+        } |`
+      );
+    }
+  }
+
+  lines.push('', '## Recommended Next Steps', '');
+  for (const recommendation of inventory.recommendations) {
+    lines.push(`- ${recommendation}`);
+  }
+
+  return lines.join('\n');
+}
+
+function recommendationsFor(surfaces, findings) {
+  const surfaceNames = new Set(surfaces.map((surface) => surface.surface));
+  const rules = new Set(findings.map((finding) => finding.ruleId));
+  const recommendations = [];
+
+  if (rules.has('AWG014')) {
+    recommendations.push('Remove and rotate committed MCP credentials before widening agent access.');
+  }
+
+  if (rules.has('AWG013')) {
+    recommendations.push('Pin MCP server packages, container images, and startup commands before enabling repository-scoped tools.');
+  }
+
+  if (rules.has('AWG012')) {
+    recommendations.push('Review persistent agent context files before relying on workflow permission boundaries.');
+  }
+
+  if (!surfaceNames.has('agent-context')) {
+    recommendations.push('Add an explicit `AGENTS.md` or `.github/copilot-instructions.md` with conservative safety rules before introducing agents.');
+  }
+
+  if (!surfaceNames.has('mcp-config')) {
+    recommendations.push('Keep MCP configs absent until there is a reviewed tool allowlist and credential handling plan.');
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push('Keep this inventory in CI so new agent surfaces are visible during review.');
+  }
+
+  return recommendations;
+}
+
+function highestSeverity(findings) {
+  return findings.reduce((current, finding) => {
+    return severityRank[finding.severity] > severityRank[current] ? finding.severity : current;
+  }, 'none');
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}

package/src/reporters.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { findingFingerprint } from './fingerprints.js';
 import { renderGraphMarkdown, renderHtmlReport } from './graph.js';
+import { renderInventory } from './inventory.js';
 import { renderMigrationPlan } from './migration.js';
 import { renderBadgeJson, renderScorecard } from './score.js';
 import { ruleCatalog } from './scanner.js';
@@ -83,7 +84,7 @@ export function renderSarif(result) {
             driver: {
               name: 'Agentic Workflow Guard',
               informationUri: 'https://github.com/Mughal-Baig/agentic-workflow-guard',
-              semanticVersion: '1.4.0',
+              semanticVersion: '1.5.0',
               rules: Object.entries(ruleCatalog).map(([id, rule]) => ({
                 id,
                 name: id,
@@ -205,6 +206,10 @@ export function renderBadge(result) {
   return renderBadgeJson(result);
 }
 
+export function renderSurfaceInventory(result) {
+  return renderInventory(result);
+}
+
 export function renderGithubAnnotations(result) {
   if (result.findings.length === 0) {
     return 'Agentic Workflow Guard: no findings.';

package/src/scanner.js

@@ -306,6 +306,13 @@ export function scanMcpConfigText(text, file = '.mcp.json', root = process.cwd()
   return context.findings;
 }
 
+export function classifyScanFile(file, root = process.cwd()) {
+  if (isMcpConfigFile(file, root)) return 'mcp-config';
+  if (isAgentInstructionFile(file, root)) return 'agent-context';
+  if (workflowExtensions.has(path.extname(file))) return 'github-workflow';
+  return 'other';
+}
+
 function scanFile(file, root, config) {
   const text = fs.readFileSync(file, 'utf8');
   if (isAgentInstructionFile(file, root)) {
@@ -831,6 +838,21 @@ function discoverAgentInstructionFiles(root) {
     files.push(...walk(githubInstructionsDir).filter((file) => file.endsWith('.instructions.md')));
   }
 
+  const githubAgentsDir = path.join(root, '.github', 'agents');
+  if (fs.existsSync(githubAgentsDir)) {
+    files.push(...walk(githubAgentsDir).filter((file) => file.endsWith('.md')));
+  }
+
+  const githubPromptsDir = path.join(root, '.github', 'prompts');
+  if (fs.existsSync(githubPromptsDir)) {
+    files.push(...walk(githubPromptsDir).filter((file) => file.endsWith('.prompt.md')));
+  }
+
+  const githubSkillsDir = path.join(root, '.github', 'skills');
+  if (fs.existsSync(githubSkillsDir)) {
+    files.push(...walk(githubSkillsDir).filter((file) => path.basename(file).toLowerCase() === 'skill.md'));
+  }
+
   const cursorRulesDir = path.join(root, '.cursor', 'rules');
   if (fs.existsSync(cursorRulesDir)) {
     files.push(...walk(cursorRulesDir).filter((file) => ['.md', '.mdc', '.txt'].includes(path.extname(file))));
@@ -859,6 +881,12 @@ function isAgentInstructionFile(file, root) {
     /\/\.github\/copilot-instructions\.md$/i.test(normalizedFile) ||
     /^\.github\/instructions\/.+\.instructions\.md$/i.test(relativeFile) ||
     /\/\.github\/instructions\/.+\.instructions\.md$/i.test(normalizedFile) ||
+    /^\.github\/agents\/.+\.md$/i.test(relativeFile) ||
+    /\/\.github\/agents\/.+\.md$/i.test(normalizedFile) ||
+    /^\.github\/prompts\/.+\.prompt\.md$/i.test(relativeFile) ||
+    /\/\.github\/prompts\/.+\.prompt\.md$/i.test(normalizedFile) ||
+    /^\.github\/skills\/.+\/skill\.md$/i.test(relativeFile) ||
+    /\/\.github\/skills\/.+\/skill\.md$/i.test(normalizedFile) ||
     /^\.cursor\/rules\/.+\.(?:md|mdc|txt)$/i.test(relativeFile) ||
     /\/\.cursor\/rules\/.+\.(?:md|mdc|txt)$/i.test(normalizedFile)
   );