awguard 1.5.0 → 1.7.0

package/src/demo.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildComparison } from './compare.js';
+import { scanWorkflows } from './scanner.js';
+import { calculateScore } from './score.js';
+
+export function renderDemoWalkthrough({ packageRoot = getPackageRoot() } = {}) {
+  const unsafeRoot = path.join(packageRoot, 'examples', 'lab', 'unsafe');
+  const fixedRoot = path.join(packageRoot, 'examples', 'lab', 'fixed');
+  const unsafe = scanWorkflows({ root: unsafeRoot });
+  const fixed = scanWorkflows({ root: fixedRoot });
+  const comparison = buildComparison(toPortableReport(unsafe), toPortableReport(fixed));
+  const unsafeScore = calculateScore(unsafe);
+  const fixedScore = calculateScore(fixed);
+
+  const lines = [
+    '# Agentic Workflow Guard Demo',
+    '',
+    'This offline demo scans the built-in vulnerable lab and its fixed version.',
+    '',
+    '## Commands',
+    '',
+    '```bash',
+    'npx awguard@latest examples/lab/unsafe --format inventory',
+    'npx awguard@latest examples/lab/fixed --format inventory',
+    'npx awguard@latest examples/lab/fixed --fail-on high',
+    '```',
+    '',
+    '## Before And After',
+    '',
+    '| Lab | Scanned files | Findings | Highest | AWI score |',
+    '| --- | ---: | ---: | --- | --- |',
+    `| Unsafe | ${unsafe.scannedFiles.length} | ${unsafe.findings.length} | ${unsafe.summary.highest} | ${unsafeScore.grade} ${unsafeScore.score}/100 |`,
+    `| Fixed | ${fixed.scannedFiles.length} | ${fixed.findings.length} | ${fixed.summary.highest} | ${fixedScore.grade} ${fixedScore.score}/100 |`,
+    '',
+    '## Resolved Risk',
+    '',
+    `Resolved findings: **${comparison.summary.resolvedFindings}**`,
+    `Remaining findings: **${comparison.summary.currentFindings}**`,
+    '',
+    '## Unsafe Findings',
+    ''
+  ];
+
+  appendFindings(lines, unsafe.findings);
+  lines.push(
+    '',
+    '## Fixed Result',
+    '',
+    fixed.findings.length === 0
+      ? 'The fixed lab is clean for the enabled rules.'
+      : `The fixed lab still has ${fixed.findings.length} finding(s).`,
+    '',
+    'Lab docs: `examples/lab/README.md`'
+  );
+
+  return lines.join('\n');
+}
+
+function appendFindings(lines, findings) {
+  if (findings.length === 0) {
+    lines.push('None.');
+    return;
+  }
+
+  lines.push('| Severity | Rule | Location | Finding |', '| --- | --- | --- | --- |');
+  for (const finding of findings) {
+    lines.push(
+      `| ${escapeMarkdown(finding.severity)} | ${escapeMarkdown(finding.ruleId)} | \`${escapeMarkdown(
+        `${finding.file}:${finding.line}`
+      )}\` | ${escapeMarkdown(finding.title)} |`
+    );
+  }
+}
+
+function toPortableReport(result) {
+  return {
+    ...result,
+    scannedFiles: result.scannedFiles.map((file) => path.relative(result.root, file) || file)
+  };
+}
+
+function getPackageRoot() {
+  const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(sourceDir, '..');
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}

package/src/doctor.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.js';
+import { scanWorkflows } from './scanner.js';
+
+const schemaPath = 'schemas/awguard.config.schema.json';
+
+export function buildDoctorReport({ root = '.', configPath = '', presets = [], env = process.env } = {}) {
+  const checks = [];
+  const packageInfo = readPackageInfo();
+  const packageRoot = getPackageRoot();
+
+  addCheck(
+    checks,
+    nodeMajor(process.version) >= 20 ? 'ok' : 'fail',
+    'Node.js runtime',
+    `${process.version} detected; AWGuard requires Node.js 20 or newer.`,
+    'Install a current Node.js release before running AWGuard.'
+  );
+
+  addCheck(
+    checks,
+    packageInfo.version ? 'ok' : 'warn',
+    'AWGuard package metadata',
+    packageInfo.version ? `awguard ${packageInfo.version}` : 'Could not read package.json version.',
+    'Reinstall the package if this command is running from a broken checkout.'
+  );
+
+  const absoluteRoot = path.resolve(root);
+  if (!fs.existsSync(absoluteRoot)) {
+    addCheck(
+      checks,
+      'fail',
+      'Scan target',
+      `Target does not exist: ${absoluteRoot}`,
+      'Pass a repository directory, workflow file, agent instruction file, or MCP config file.'
+    );
+    return finish(checks);
+  }
+
+  const targetStat = fs.statSync(absoluteRoot);
+  addCheck(
+    checks,
+    targetStat.isDirectory() || targetStat.isFile() ? 'ok' : 'fail',
+    'Scan target',
+    `${absoluteRoot} is a ${targetStat.isDirectory() ? 'directory' : targetStat.isFile() ? 'file' : 'special file'}.`,
+    'Pass a regular file or directory.'
+  );
+
+  let configResult;
+  try {
+    configResult = loadConfig({ configPath, root: absoluteRoot, presets });
+    addCheck(
+      checks,
+      'ok',
+      'Configuration',
+      configResult.path
+        ? `Loaded ${path.relative(process.cwd(), configResult.path) || configResult.path}.`
+        : 'No config file found; using defaults and CLI presets.',
+      `Add "$schema": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/${schemaPath}" to awguard.config.json for editor validation.`
+    );
+  } catch (error) {
+    addCheck(checks, 'fail', 'Configuration', error.message, 'Fix the config file or run without --config.');
+    return finish(checks);
+  }
+
+  addCheck(
+    checks,
+    fs.existsSync(path.join(packageRoot, schemaPath)) ? 'ok' : 'warn',
+    'Config schema',
+    `Schema path: ${schemaPath}`,
+    'Publish package files with the schemas directory included.'
+  );
+
+  let result;
+  try {
+    result = scanWorkflows({ root: absoluteRoot, config: configResult.config });
+  } catch (error) {
+    addCheck(checks, 'fail', 'Scanner smoke test', error.message, 'Check file permissions and scan target contents.');
+    return finish(checks);
+  }
+
+  if (result.scannedFiles.length === 0) {
+    addCheck(
+      checks,
+      'warn',
+      'Scanner smoke test',
+      'No GitHub Actions workflow, agent instruction, or MCP config files were found.',
+      'Run AWGuard again after adding agent workflows, AGENTS.md-style files, or MCP configs.'
+    );
+  } else {
+    const findingText =
+      result.findings.length === 0
+        ? 'no findings'
+        : `${result.findings.length} finding(s), highest severity ${result.summary.highest}`;
+    addCheck(
+      checks,
+      result.findings.length === 0 ? 'ok' : 'warn',
+      'Scanner smoke test',
+      `Scanned ${result.scannedFiles.length} file(s); ${findingText}.`,
+      'Use --format score, --format inventory, or --format sarif for CI-ready reports.'
+    );
+  }
+
+  if (env.GITHUB_ACTIONS === 'true') {
+    addCheck(
+      checks,
+      env.GITHUB_STEP_SUMMARY ? 'ok' : 'warn',
+      'GitHub Actions summary',
+      env.GITHUB_STEP_SUMMARY
+        ? 'GITHUB_STEP_SUMMARY is available for job summary output.'
+        : 'GITHUB_STEP_SUMMARY is not available in this environment.',
+      'Run inside a modern GitHub Actions job to receive the Markdown job summary.'
+    );
+  }
+
+  return finish(checks);
+}
+
+export function renderDoctorReport(report) {
+  const lines = [
+    '# Agentic Workflow Guard Doctor',
+    '',
+    `Status: **${report.status.toUpperCase()}**`,
+    '',
+    '| Check | Status | Detail |',
+    '| --- | --- | --- |'
+  ];
+
+  for (const check of report.checks) {
+    lines.push(`| ${escapeMarkdown(check.title)} | ${statusLabel(check.status)} | ${escapeMarkdown(check.detail)} |`);
+  }
+
+  const nextSteps = report.checks.filter((check) => check.status !== 'ok' && check.nextStep);
+  if (nextSteps.length > 0) {
+    lines.push('', '## Next Steps', '');
+    for (const check of nextSteps) {
+      lines.push(`- ${check.title}: ${check.nextStep}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function addCheck(checks, status, title, detail, nextStep = '') {
+  checks.push({ status, title, detail, nextStep });
+}
+
+function finish(checks) {
+  return {
+    status: checks.some((check) => check.status === 'fail')
+      ? 'fail'
+      : checks.some((check) => check.status === 'warn')
+        ? 'warn'
+        : 'ok',
+    checks
+  };
+}
+
+function nodeMajor(version) {
+  const match = String(version).match(/^v?(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+function readPackageInfo() {
+  const packageFile = path.join(getPackageRoot(), 'package.json');
+  try {
+    return JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function getPackageRoot() {
+  const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(sourceDir, '..');
+}
+
+function statusLabel(status) {
+  if (status === 'ok') return 'OK';
+  if (status === 'warn') return 'WARN';
+  return 'FAIL';
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+}

package/src/explain.js

@@ -0,0 +1,147 @@
+import { ruleCatalog } from './scanner.js';
+
+const ruleDetails = {
+  AWG001: {
+    detects: 'User-controlled GitHub issue, pull request, comment, branch, or event text reaching an AI prompt.',
+    why: 'The model may treat attacker-supplied text as instructions and use privileged tools or repository context.',
+    safePattern: 'Delimit untrusted text, keep the job read-only, and require human review before any write action.'
+  },
+  AWG002: {
+    detects: 'Untrusted GitHub context interpolated directly into shell scripts.',
+    why: 'Shell interpolation can turn event text into command execution or argument injection.',
+    safePattern: 'Move values into environment variables and reference them with shell quoting.'
+  },
+  AWG003: {
+    detects: 'pull_request_target workflows that check out pull request head code.',
+    why: 'Untrusted fork code can run with base-repository privileges.',
+    safePattern: 'Use pull_request for untrusted code or keep pull_request_target limited to metadata-only work.'
+  },
+  AWG004: {
+    detects: 'Agent jobs with broad write-capable GitHub token permissions.',
+    why: 'Prompt injection becomes much more damaging when the agent can write repository state.',
+    safePattern: 'Use contents: read by default and isolate write actions behind a reviewed apply job.'
+  },
+  AWG005: {
+    detects: 'Secrets exposed to workflows driven by untrusted agent input.',
+    why: 'An attacker can steer the agent or scripts into revealing credentials.',
+    safePattern: 'Keep secrets out of untrusted event workflows and use a separate approved privileged workflow.'
+  },
+  AWG006: {
+    detects: 'Agent command flags that skip approvals or permission prompts.',
+    why: 'Autonomous execution removes the human gate that normally stops unsafe tool use.',
+    safePattern: 'Require confirmation for file writes, command execution, and repository changes.'
+  },
+  AWG007: {
+    detects: 'Model or agent output flowing into eval, shell, or pipe-to-shell execution.',
+    why: 'Model output is data, not trusted code.',
+    safePattern: 'Validate structured output with a narrow parser before using it.'
+  },
+  AWG008: {
+    detects: 'Agent workflows without explicit permissions.',
+    why: 'Default permissions are easy to misunderstand and can drift as repository settings change.',
+    safePattern: 'Declare the minimum required permissions in every agent workflow.'
+  },
+  AWG009: {
+    detects: 'workflow_run jobs that consume artifacts before scripts execute.',
+    why: 'Artifacts can carry untrusted content from an earlier workflow into a more privileged job.',
+    safePattern: 'Verify artifact provenance, names, checksums, and expected schema before use.'
+  },
+  AWG010: {
+    detects: 'Third-party actions that are not pinned to commit SHAs in sensitive agent workflows.',
+    why: 'Mutable tags can change behavior after review.',
+    safePattern: 'Pin third-party actions to reviewed commit SHAs.'
+  },
+  AWG011: {
+    detects: 'Suppression comments that are malformed, unjustified, or disallowed by config.',
+    why: 'Weak suppressions can hide real agentic workflow risk.',
+    safePattern: 'Use narrow rule IDs and a clear reviewed false-positive reason.'
+  },
+  AWG012: {
+    detects: 'Persistent agent instructions that weaken approval, permission, or secret boundaries.',
+    why: 'Instruction files are durable context that can affect future agent runs.',
+    safePattern: 'Keep repository instructions conservative and explicit about human review.'
+  },
+  AWG013: {
+    detects: 'MCP configs that start mutable packages, unpinned containers, or shell wrappers.',
+    why: 'MCP servers expand agent tool authority before runtime scanners can inspect behavior.',
+    safePattern: 'Pin packages/images and avoid shell wrappers for project-scoped MCP servers.'
+  },
+  AWG014: {
+    detects: 'MCP configs that hardcode credentials or authorization material.',
+    why: 'Committed secrets can be used by anyone with repository access and may be exposed by agents.',
+    safePattern: 'Move credentials into prompts, environment variables, or a secret manager.'
+  },
+  AWG015: {
+    detects: 'Agentic files, MCP servers, packages, or commands outside configured policy allowlists.',
+    why: 'New agent surfaces should be visible in review before they gain trust.',
+    safePattern: 'Approve only reviewed files, servers, packages, and commands.'
+  },
+  AWG016: {
+    detects: 'actions/checkout credentials persisting in elevated agent workflows.',
+    why: 'Persisted checkout credentials can give later agent or shell steps repository write access.',
+    safePattern: 'Use persist-credentials: false and keep writeback in a separate reviewed job.'
+  },
+  AWG017: {
+    detects: 'Agent jobs with write permissions that commit, tag, publish, or push without a reviewable boundary.',
+    why: 'Autonomous writeback can change protected repository state before a maintainer reviews the result.',
+    safePattern: 'Push to an isolated branch, open a draft pull request, or upload artifacts for a human apply step.'
+  },
+  AWG018: {
+    detects: 'Untrusted GitHub event text flowing into MCP tool arguments or environment variables.',
+    why: 'MCP tools can bridge prompt input into external systems, so injected text can become tool instructions.',
+    safePattern: 'Treat event text as untrusted data, sanitize it, and require review before passing it to MCP tools.'
+  },
+  AWG019: {
+    detects: 'MCP package specs outside configured trusted package scopes.',
+    why: 'Project-scoped MCP packages expand agent capability, so publisher reputation should be reviewed before trust is granted.',
+    safePattern: 'Keep trusted package scopes narrow, pin approved packages, and document the review in policy.'
+  }
+};
+
+export function renderRuleExplanation(ruleId = '') {
+  const normalizedRuleId = String(ruleId || '').toUpperCase();
+  if (!normalizedRuleId) return renderRuleIndex();
+
+  const rule = ruleCatalog[normalizedRuleId];
+  if (!rule) {
+    throw new Error(`unknown rule id: ${normalizedRuleId}. Use awguard explain to list available rules.`);
+  }
+
+  const details = ruleDetails[normalizedRuleId] || {};
+  return [
+    `# ${normalizedRuleId}: ${rule.title}`,
+    '',
+    `Severity: **${rule.severity}**`,
+    '',
+    `Remediation code: \`${rule.remediationCode}\``,
+    '',
+    `Detects: ${details.detects || rule.title}`,
+    '',
+    `Why it matters: ${details.why || 'This pattern can increase agentic workflow risk.'}`,
+    '',
+    `Safe pattern: ${details.safePattern || rule.suggestion}`,
+    '',
+    `Suggested fix: ${rule.suggestion}`,
+    '',
+    'Useful commands:',
+    '',
+    '```bash',
+    'npx awguard@latest . --format inventory',
+    'npx awguard@latest . --fix-dry-run',
+    'npx awguard@latest . --format sarif --output awguard.sarif --fail-on none',
+    '```'
+  ].join('\n');
+}
+
+function renderRuleIndex() {
+  const lines = ['# Agentic Workflow Guard Rules', '', '| Rule | Severity | Remediation Code | Title |', '| --- | --- | --- | --- |'];
+  for (const [ruleId, rule] of Object.entries(ruleCatalog)) {
+    lines.push(`| ${ruleId} | ${rule.severity} | \`${rule.remediationCode}\` | ${escapeMarkdown(rule.title)} |`);
+  }
+  lines.push('', 'Run `awguard explain AWG001` for details about one rule.');
+  return lines.join('\n');
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}

package/src/graph.js

@@ -14,7 +14,8 @@ const impactByRule = {
   AWG011: 'Suppression policy can hide real risk',
   AWG012: 'Persistent agent instructions can weaken CI guardrails',
   AWG013: 'Mutable MCP tool server can change agent capabilities',
-  AWG014: 'Committed MCP credential can expose external tools or data'
+  AWG014: 'Committed MCP credential can expose external tools or data',
+  AWG015: 'Unapproved agentic surface can drift outside policy'
 };
 
 export function buildAttackGraphs(result) {
@@ -218,6 +219,7 @@ function inferSource(finding) {
   if (finding.ruleId === 'AWG012') return 'persistent agent instruction file';
   if (finding.ruleId === 'AWG013') return 'project-scoped MCP server config';
   if (finding.ruleId === 'AWG014') return 'committed MCP credential material';
+  if (finding.ruleId === 'AWG015') return 'repository policy';
   return 'workflow configuration';
 }
 
@@ -228,6 +230,7 @@ function inferBoundary(finding) {
   if (finding.ruleId === 'AWG007') return 'command execution sink';
   if (finding.ruleId === 'AWG012') return 'agent instruction context';
   if (finding.ruleId === 'AWG013' || finding.ruleId === 'AWG014') return 'MCP tool boundary';
+  if (finding.ruleId === 'AWG015') return 'policy allowlist boundary';
   return 'workflow execution';
 }
 
@@ -238,6 +241,7 @@ function inferCapability(finding) {
   if (finding.ruleId === 'AWG012') return 'persistent prompt steering';
   if (finding.ruleId === 'AWG013') return 'MCP server startup';
   if (finding.ruleId === 'AWG014') return 'credentialed MCP tool access';
+  if (finding.ruleId === 'AWG015') return 'agentic surface drift';
   return 'CI runner and agent tools';
 }
 
@@ -248,6 +252,7 @@ function inferAuthority(finding) {
   if (finding.ruleId === 'AWG012') return 'agent policy context';
   if (finding.ruleId === 'AWG013') return 'developer machine or CI tool process';
   if (finding.ruleId === 'AWG014') return 'MCP server secrets';
+  if (finding.ruleId === 'AWG015') return 'repository policy approval';
   return 'workflow permissions';
 }
 

package/src/init.js

@@ -0,0 +1,84 @@
+export function renderInitGuide({ actionRef = 'v0' } = {}) {
+  return [
+    '# Agentic Workflow Guard Setup',
+    '',
+    'Create `.github/workflows/awguard.yml`:',
+    '',
+    '```yaml',
+    `name: Agentic Workflow Guard`,
+    '',
+    'on:',
+    '  pull_request:',
+    '  workflow_dispatch:',
+    '  schedule:',
+    "    - cron: '17 4 * * 1'",
+    '',
+    'permissions:',
+    '  contents: read',
+    '  security-events: write',
+    '',
+    'jobs:',
+    '  scan:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v6',
+    `      - uses: Mughal-Baig/agentic-workflow-guard@${actionRef}`,
+    '        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',
+    '```',
+    '',
+    'Create `awguard.config.json`:',
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        $schema:
+          'https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json',
+        extends: ['strict'],
+        policy: {
+          approvedFiles: ['AGENTS.md', '.github/workflows/*'],
+          approvedMcpServers: [],
+          approvedMcpPackages: [],
+          approvedMcpPackageScopes: ['@modelcontextprotocol/'],
+          approvedMcpCommands: ['npx', 'node', 'uvx', 'docker']
+        },
+        suppressions: {
+          minimumReasonLength: 20
+        }
+      },
+      null,
+      2
+    ),
+    '```',
+    '',
+    'Adopt without breaking existing CI:',
+    '',
+    '```bash',
+    'npx awguard@latest . --write-baseline awguard.baseline.json --fail-on none',
+    'npx awguard@latest . --baseline awguard.baseline.json --fail-on high',
+    '```',
+    '',
+    'Generate useful reports:',
+    '',
+    '```bash',
+    'npx awguard@latest . --format inventory',
+    'npx awguard@latest . --format inventory-json --output awguard-inventory.json',
+    'npx awguard@latest . --format score',
+    'npx awguard@latest . --format badge --output docs/awguard-badge.json',
+    '```',
+    '',
+    'README badge:',
+    '',
+    '```markdown',
+    '[![AWI risk](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/docs/awguard-badge.json)](docs/awguard-badge.json)',
+    '```'
+  ].join('\n');
+}

package/src/inventory.js

@@ -105,6 +105,17 @@ export function renderInventory(result) {
   return lines.join('\n');
 }
 
+export function renderInventoryJson(result) {
+  return JSON.stringify(
+    {
+      root: result.root,
+      ...buildInventory(result)
+    },
+    null,
+    2
+  );
+}
+
 function recommendationsFor(surfaces, findings) {
   const surfaceNames = new Set(surfaces.map((surface) => surface.surface));
   const rules = new Set(findings.map((finding) => finding.ruleId));

package/src/migration.js

@@ -63,6 +63,11 @@ const ruleActions = {
     'Remove committed MCP tokens, API keys, passwords, and auth headers.',
     'Use prompted inputs, environment variables, or managed secrets for MCP credentials.',
     'Rotate credentials that were present in repository history.'
+  ],
+  AWG015: [
+    'Review the unapproved agentic surface and decide whether it belongs in the repository.',
+    'Add approved files, MCP servers, packages, and commands to policy allowlists.',
+    'Fail CI on policy drift so new agent surfaces are visible in review.'
   ]
 };
 
@@ -180,6 +185,7 @@ function riskShapeFor(findings) {
   if (rules.has('AWG012')) pieces.push('persistent agent instructions weaken review or permission boundaries');
   if (rules.has('AWG013')) pieces.push('project MCP config can change agent tool capabilities through mutable startup');
   if (rules.has('AWG014')) pieces.push('project MCP config contains committed credentials');
+  if (rules.has('AWG015')) pieces.push('agentic surface is outside the repository policy');
 
   return pieces.length > 0 ? pieces.join('; ') : 'workflow hardening issue';
 }
@@ -230,6 +236,10 @@ function allowedOperationsFor(findings) {
     operations.add('MCP credentials supplied by prompt input, environment variable, or secret manager only');
   }
 
+  if (rules.has('AWG015')) {
+    operations.add('policy approval only after reviewing the workflow, agent context, MCP server, package, and command');
+  }
+
   operations.add('noop or missing-data report when validation fails');
   return [...operations];
 }