awguard 1.6.0 → 1.7.0

package/schemas/awguard.config.schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json",
+  "title": "Agentic Workflow Guard configuration",
+  "description": "Configuration for AWGuard rule severities, presets, suppression policy, and reviewed agentic surface allowlists.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "extends": {
+      "description": "Built-in preset name or list of preset names to merge before local settings.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/preset"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/preset"
+          },
+          "uniqueItems": true
+        }
+      ]
+    },
+    "rules": {
+      "type": "object",
+      "description": "Rule severity overrides. Use \"off\" to disable a rule.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^AWG(00[1-9]|01[0-9])$": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/ruleSeverity"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["severity"],
+              "properties": {
+                "severity": {
+                  "$ref": "#/$defs/ruleSeverity"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "suppressions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allow": {
+          "type": "boolean",
+          "description": "Set false to report every awguard-disable comment as invalid."
+        },
+        "allowedRules": {
+          "type": "array",
+          "description": "Optional list of rule IDs that may be suppressed inline.",
+          "items": {
+            "$ref": "#/$defs/ruleId"
+          },
+          "uniqueItems": true
+        },
+        "minimumReasonLength": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum characters required after the suppression reason separator."
+        }
+      }
+    },
+    "scan": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "$ref": "#/$defs/stringList",
+          "description": "Optional glob-style file patterns that narrow discovered AWGuard scan files."
+        },
+        "exclude": {
+          "$ref": "#/$defs/stringList",
+          "description": "Optional glob-style file patterns removed from discovered AWGuard scan files."
+        },
+        "maxFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional cap on the number of discovered scan files."
+        },
+        "maxFileBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional cap on the byte size of each scanned file."
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "approvedFiles": {
+          "$ref": "#/$defs/stringList",
+          "description": "Reviewed workflow, instruction, prompt, skill, and MCP config files. Glob-style * suffixes are supported by AWGuard."
+        },
+        "approvedMcpServers": {
+          "$ref": "#/$defs/stringList",
+          "description": "Reviewed MCP server names."
+        },
+        "approvedMcpPackages": {
+          "$ref": "#/$defs/stringList",
+          "description": "Reviewed MCP package or container specs, preferably pinned to exact versions or digests."
+        },
+        "approvedMcpPackageScopes": {
+          "$ref": "#/$defs/stringList",
+          "description": "Reviewed npm package scopes or prefixes for optional offline MCP package reputation checks, for example @modelcontextprotocol/."
+        },
+        "approvedMcpCommands": {
+          "$ref": "#/$defs/stringList",
+          "description": "Reviewed MCP launch commands such as node, npx, uvx, or docker."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "preset": {
+      "type": "string",
+      "enum": ["strict", "claude-code", "codex", "aider", "triage-bot"]
+    },
+    "ruleId": {
+      "type": "string",
+      "enum": [
+        "AWG001",
+        "AWG002",
+        "AWG003",
+        "AWG004",
+        "AWG005",
+        "AWG006",
+        "AWG007",
+        "AWG008",
+        "AWG009",
+        "AWG010",
+        "AWG011",
+        "AWG012",
+        "AWG013",
+        "AWG014",
+        "AWG015",
+        "AWG016",
+        "AWG017",
+        "AWG018",
+        "AWG019"
+      ]
+    },
+    "ruleSeverity": {
+      "type": "string",
+      "enum": ["off", "low", "medium", "high", "critical"]
+    },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  }
+}

package/schemas/awguard.inventory.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.inventory.schema.json",
+  "title": "Agentic Workflow Guard inventory report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["root", "summary", "surfaces", "files", "recommendations"],
+  "properties": {
+    "root": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scannedFiles", "surfaces", "findings", "highest"],
+      "properties": {
+        "scannedFiles": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "surfaces": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "findings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "highest": {
+          "$ref": "#/$defs/severity"
+        }
+      }
+    },
+    "surfaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/surface"
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/file"
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "severity": {
+      "type": "string",
+      "enum": ["none", "low", "medium", "high", "critical"]
+    },
+    "surfaceName": {
+      "type": "string",
+      "enum": ["github-workflow", "agent-context", "mcp-config", "other"]
+    },
+    "ruleIdList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^AWG[0-9]{3}$"
+      },
+      "uniqueItems": true
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surface", "label", "files", "findings", "highest", "rules"],
+      "properties": {
+        "surface": {
+          "$ref": "#/$defs/surfaceName"
+        },
+        "label": {
+          "type": "string"
+        },
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "findings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "highest": {
+          "$ref": "#/$defs/severity"
+        },
+        "rules": {
+          "$ref": "#/$defs/ruleIdList"
+        }
+      }
+    },
+    "file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "surface", "label", "findings", "highest", "rules"],
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "surface": {
+          "$ref": "#/$defs/surfaceName"
+        },
+        "label": {
+          "type": "string"
+        },
+        "findings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "highest": {
+          "$ref": "#/$defs/severity"
+        },
+        "rules": {
+          "$ref": "#/$defs/ruleIdList"
+        }
+      }
+    }
+  }
+}

package/schemas/awguard.report.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.report.schema.json",
+  "title": "Agentic Workflow Guard JSON report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["root", "scannedFiles", "summary", "findings"],
+  "properties": {
+    "root": {
+      "type": "string"
+    },
+    "scannedFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
+    }
+  },
+  "$defs": {
+    "severity": {
+      "type": "string",
+      "enum": ["none", "low", "medium", "high", "critical"]
+    },
+    "ruleId": {
+      "type": "string",
+      "pattern": "^AWG[0-9]{3}$"
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["total", "highest"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "highest": {
+          "$ref": "#/$defs/severity"
+        },
+        "bySeverity": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "baseline": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["new", "known"],
+          "properties": {
+            "new": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "known": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "title", "severity", "file", "line", "message", "suggestion"],
+      "properties": {
+        "ruleId": {
+          "$ref": "#/$defs/ruleId"
+        },
+        "title": {
+          "type": "string"
+        },
+        "severity": {
+          "$ref": "#/$defs/severity"
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "message": {
+          "type": "string"
+        },
+        "evidence": {
+          "type": ["string", "null"]
+        },
+        "remediationCode": {
+          "type": ["string", "null"],
+          "pattern": "^[a-z][a-z0-9.-]*$"
+        },
+        "suggestion": {
+          "type": "string"
+        },
+        "fingerprint": {
+          "type": ["string", "null"]
+        },
+        "baselineState": {
+          "type": ["string", "null"],
+          "enum": ["new", "known", null]
+        }
+      }
+    }
+  }
+}

package/src/autofix.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const fixableRules = new Set(['AWG004', 'AWG008', 'AWG016']);
+
+export function buildAutofixPlan(result) {
+  const byFile = new Map();
+
+  for (const finding of result.findings) {
+    if (finding.baselineState === 'known') continue;
+    if (!fixableRules.has(finding.ruleId)) continue;
+    if (!isWorkflowFile(finding.absoluteFile || finding.file)) continue;
+
+    const absoluteFile = finding.absoluteFile || path.join(result.root, finding.file);
+    const existing = byFile.get(absoluteFile) || [];
+    existing.push(finding);
+    byFile.set(absoluteFile, existing);
+  }
+
+  const files = [];
+  for (const [absoluteFile, findings] of byFile.entries()) {
+    const plan = buildFilePlan(absoluteFile, findings, result.root);
+    if (plan.changes.length > 0) files.push(plan);
+  }
+
+  return {
+    files,
+    changes: files.reduce((count, file) => count + file.changes.length, 0)
+  };
+}
+
+export function applyAutofixPlan(plan) {
+  for (const file of plan.files) {
+    fs.writeFileSync(file.absoluteFile, file.nextText);
+  }
+
+  return plan;
+}
+
+export function renderAutofixPlan(plan, { applied = false } = {}) {
+  const lines = [applied ? 'Agentic Workflow Guard Autofix Applied' : 'Agentic Workflow Guard Autofix Plan', ''];
+
+  if (plan.changes === 0) {
+    lines.push('No safe autofixes available for the current findings.');
+    lines.push('Run with --fix-dry-run for remediation guidance on findings that require human review.');
+    return lines.join('\n');
+  }
+
+  lines.push(`${applied ? 'Applied' : 'Would apply'} ${plan.changes} change(s) in ${plan.files.length} file(s).`, '');
+
+  for (const file of plan.files) {
+    lines.push(`## ${file.file}`);
+    for (const change of file.changes) {
+      lines.push(`- ${change.ruleId}: ${change.description}`);
+    }
+    lines.push('');
+  }
+
+  if (applied) {
+    lines.push('Rollback: review git diff, then revert the edited hunks if needed.');
+  } else {
+    lines.push('Apply: rerun with --fix. Review git diff before committing.');
+  }
+
+  return lines.join('\n');
+}
+
+function buildFilePlan(absoluteFile, findings, root) {
+  const originalText = fs.readFileSync(absoluteFile, 'utf8');
+  const newline = originalText.includes('\r\n') ? '\r\n' : '\n';
+  const hadFinalNewline = originalText.endsWith('\n');
+  const lines = originalText.replace(/\r?\n$/, '').split(/\r?\n/);
+  const changes = [];
+
+  const lineSpecificFindings = findings
+    .filter((finding) => finding.ruleId === 'AWG004' || finding.ruleId === 'AWG016')
+    .sort((a, b) => b.line - a.line);
+
+  for (const finding of lineSpecificFindings) {
+    if (finding.ruleId === 'AWG004') {
+      applyWriteAllFix(lines, finding, changes);
+    } else if (finding.ruleId === 'AWG016') {
+      applyCheckoutCredentialsFix(lines, finding, changes);
+    }
+  }
+
+  if (findings.some((finding) => finding.ruleId === 'AWG008')) {
+    applyMissingPermissionsFix(lines, changes);
+  }
+
+  const nextText = `${lines.join(newline)}${hadFinalNewline ? newline : ''}`;
+
+  return {
+    file: path.relative(root, absoluteFile).split(path.sep).join('/') || path.basename(absoluteFile),
+    absoluteFile,
+    changes,
+    nextText
+  };
+}
+
+function applyWriteAllFix(lines, finding, changes) {
+  const index = finding.line - 1;
+  const line = lines[index] || '';
+  const match = line.match(/^(\s*)permissions\s*:\s*write-all\s*(?:#.*)?$/i);
+  if (!match) return;
+
+  const indent = match[1];
+  lines.splice(index, 1, `${indent}permissions:`, `${indent}  contents: read`);
+  changes.push({
+    ruleId: 'AWG004',
+    description: `replace write-all permissions at line ${finding.line} with contents: read`
+  });
+}
+
+function applyCheckoutCredentialsFix(lines, finding, changes) {
+  const checkoutIndex = findCheckoutLine(lines, finding.line - 1);
+  if (checkoutIndex === -1) return;
+
+  const checkoutLine = lines[checkoutIndex];
+  const checkoutIndent = leadingSpaces(checkoutLine);
+  const childIndent = `${checkoutIndent}  `;
+  const valueIndent = `${childIndent}  `;
+  const blockEnd = findStepBlockEnd(lines, checkoutIndex, checkoutIndent.length);
+  const persistIndex = findKeyInRange(lines, checkoutIndex + 1, blockEnd, 'persist-credentials');
+
+  if (persistIndex !== -1) {
+    if (/:\s*false\s*(?:#.*)?$/i.test(lines[persistIndex])) return;
+    lines[persistIndex] = `${leadingSpaces(lines[persistIndex])}persist-credentials: false`;
+    changes.push({
+      ruleId: 'AWG016',
+      description: `set actions/checkout persist-credentials: false at line ${persistIndex + 1}`
+    });
+    return;
+  }
+
+  const withIndex = findKeyInRange(lines, checkoutIndex + 1, blockEnd, 'with');
+  if (withIndex !== -1) {
+    lines.splice(withIndex + 1, 0, `${leadingSpaces(lines[withIndex])}  persist-credentials: false`);
+  } else {
+    lines.splice(checkoutIndex + 1, 0, `${childIndent}with:`, `${valueIndent}persist-credentials: false`);
+  }
+
+  changes.push({
+    ruleId: 'AWG016',
+    description: `add actions/checkout persist-credentials: false after line ${checkoutIndex + 1}`
+  });
+}
+
+function applyMissingPermissionsFix(lines, changes) {
+  if (hasTopLevelPermissions(lines)) return;
+  const jobsIndex = lines.findIndex((line) => /^jobs\s*:\s*(?:#.*)?$/i.test(line));
+  if (jobsIndex === -1) return;
+
+  lines.splice(jobsIndex, 0, 'permissions:', '  contents: read', '');
+  changes.push({
+    ruleId: 'AWG008',
+    description: 'add top-level permissions: contents: read before jobs'
+  });
+}
+
+function findCheckoutLine(lines, index) {
+  for (let cursor = index; cursor >= Math.max(0, index - 8); cursor -= 1) {
+    if (/uses\s*:\s*actions\/checkout@/i.test(lines[cursor] || '')) return cursor;
+  }
+  return -1;
+}
+
+function findStepBlockEnd(lines, startIndex, startIndentWidth) {
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim()) continue;
+    const indentWidth = leadingSpaces(line).length;
+    if (indentWidth <= startIndentWidth && /^\s*-\s+/.test(line)) return index;
+    if (indentWidth < startIndentWidth) return index;
+  }
+  return lines.length;
+}
+
+function findKeyInRange(lines, start, end, key) {
+  const pattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*:`, 'i');
+  for (let index = start; index < end; index += 1) {
+    if (pattern.test(lines[index])) return index;
+  }
+  return -1;
+}
+
+function hasTopLevelPermissions(lines) {
+  return lines.some((line) => /^permissions\s*:/i.test(line));
+}
+
+function leadingSpaces(line) {
+  return line.match(/^\s*/)[0];
+}
+
+function isWorkflowFile(file) {
+  return ['.yml', '.yaml'].includes(path.extname(file || '').toLowerCase());
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/badges.js

@@ -0,0 +1,63 @@
+export function renderBadgeSnippets({
+  repo = 'OWNER/REPO',
+  branch = 'main',
+  badgeFile = 'docs/awguard-badge.json',
+  site = ''
+} = {}) {
+  const rawBadgeUrl = `https://raw.githubusercontent.com/${repo}/${branch}/${badgeFile}`;
+  const badgeEndpoint = `https://img.shields.io/endpoint?url=${rawBadgeUrl}`;
+  const lines = [
+    '# AWGuard Badge Snippets',
+    '',
+    'Copy the snippets that match your repository setup.',
+    '',
+    '## AWI Risk',
+    '',
+    '```markdown',
+    `[![AWI risk](${badgeEndpoint})](${badgeFile})`,
+    '```',
+    '',
+    'Generate the badge JSON with:',
+    '',
+    '```bash',
+    `npx awguard@latest . --format badge --output ${badgeFile}`,
+    '```',
+    '',
+    '## GitHub Action',
+    '',
+    '```markdown',
+    `[![AWGuard](https://github.com/${repo}/actions/workflows/awguard.yml/badge.svg)](https://github.com/${repo}/actions/workflows/awguard.yml)`,
+    '```',
+    '',
+    '## Code Scanning',
+    '',
+    '```markdown',
+    `[![Code Scanning](https://github.com/${repo}/actions/workflows/code-scanning.yml/badge.svg)](https://github.com/${repo}/actions/workflows/code-scanning.yml)`,
+    '```',
+    '',
+    '## npm',
+    '',
+    '```markdown',
+    '[![npm](https://img.shields.io/npm/v/awguard)](https://www.npmjs.com/package/awguard)',
+    '```',
+    '',
+    '## Release',
+    '',
+    '```markdown',
+    `[![GitHub release](https://img.shields.io/github/v/release/${repo})](https://github.com/${repo}/releases)`,
+    '```'
+  ];
+
+  if (site) {
+    lines.push(
+      '',
+      '## Project Site',
+      '',
+      '```markdown',
+      `[![Project site](https://img.shields.io/badge/site-live-0f766e)](${site})`,
+      '```'
+    );
+  }
+
+  return lines.join('\n');
+}