awguard 1.6.0 → 1.7.0

package/src/remediation.js

@@ -73,10 +73,30 @@ const fixCatalog = {
     'Review the new agentic surface before approving it in policy.',
     'Add reviewed files to policy.approvedFiles and reviewed MCP tools to the MCP policy allowlists.',
     'Remove or quarantine unapproved workflows, agent instructions, prompts, skills, and MCP configs.'
+  ],
+  AWG016: [
+    'Set actions/checkout persist-credentials: false in agent jobs.',
+    'Use read-only permissions for analysis jobs.',
+    'Move writeback to a separate reviewed job with an explicit branch or pull request boundary.'
+  ],
+  AWG017: [
+    'Push agent changes to a short-lived branch instead of main.',
+    'Open a draft pull request for maintainer review.',
+    'Use artifacts for generated patches when the workflow should not write to the repository.'
+  ],
+  AWG018: [
+    'Move untrusted event text into a reviewed input file before MCP tool use.',
+    'Sanitize issue, PR, comment, branch, and workflow_dispatch input text before passing it to MCP tools.',
+    'Keep MCP tool calls read-only unless a maintainer approves the request.'
+  ],
+  AWG019: [
+    'Review MCP package publisher, repository, release cadence, and install scripts before approval.',
+    'Add trusted package scopes to policy.approvedMcpPackageScopes after review.',
+    'Prefer pinned packages from reviewed organizations or local audited servers.'
   ]
 };
 
-export function renderFixDryRun(result) {
+export function renderFixDryRun(result, { autofixPlan = null } = {}) {
   const lines = ['Agentic Workflow Guard Fix Dry Run', ''];
 
   if (result.findings.length === 0) {
@@ -105,6 +125,15 @@ export function renderFixDryRun(result) {
     lines.push('');
   }
 
+  if (autofixPlan?.changes > 0) {
+    lines.push('Autofix plan:');
+    for (const file of autofixPlan.files) {
+      lines.push(`- ${file.file}: ${file.changes.length} safe change(s) available`);
+    }
+    lines.push('Apply these narrow workflow hardening edits with `awguard --fix` and review git diff before committing.');
+    lines.push('');
+  }
+
   return lines.join('\n');
 }
 
@@ -194,11 +223,54 @@ run: |
     "approvedFiles": ["AGENTS.md", ".github/workflows/*", ".github/agents/*"],
     "approvedMcpServers": ["github"],
     "approvedMcpPackages": ["@modelcontextprotocol/server-github@1.2.3"],
+    "approvedMcpPackageScopes": ["@modelcontextprotocol/"],
     "approvedMcpCommands": ["npx", "node"]
   }
 }`
     };
   }
 
+  if (finding.ruleId === 'AWG016') {
+    return {
+      language: 'yaml',
+      text: `- uses: actions/checkout@v6
+  with:
+    persist-credentials: false`
+    };
+  }
+
+  if (finding.ruleId === 'AWG017') {
+    return {
+      language: 'yaml',
+      text: `run: |
+  git switch -c awguard/agent-output
+  git commit -am "Propose agent changes"
+  git push origin HEAD:awguard/agent-output
+  gh pr create --draft --fill`
+    };
+  }
+
+  if (finding.ruleId === 'AWG018') {
+    return {
+      language: 'yaml',
+      text: `env:
+  UNTRUSTED_TEXT: \${{ github.event.comment.body }}
+run: |
+  printf '%s\\n' "$UNTRUSTED_TEXT" > untrusted-input.txt
+  codex mcp run github --input reviewed-request.json`
+    };
+  }
+
+  if (finding.ruleId === 'AWG019') {
+    return {
+      language: 'json',
+      text: `{
+  "policy": {
+    "approvedMcpPackageScopes": ["@modelcontextprotocol/"]
+  }
+}`
+    };
+  }
+
   return null;
 }

package/src/reporters.js

@@ -61,8 +61,10 @@ export function renderJson(result) {
         severity: finding.severity,
         file: finding.file,
         line: finding.line,
+        column: finding.column,
         message: finding.message,
         evidence: finding.evidence,
+        remediationCode: finding.remediationCode,
         suggestion: finding.suggestion,
         fingerprint: finding.fingerprint,
         baselineState: finding.baselineState
@@ -88,6 +90,7 @@ export function renderSarif(result) {
               rules: Object.entries(ruleCatalog).map(([id, rule]) => ({
                 id,
                 name: id,
+                helpUri: 'https://github.com/Mughal-Baig/agentic-workflow-guard#rule-reference',
                 shortDescription: {
                   text: rule.title
                 },
@@ -101,8 +104,10 @@ export function renderSarif(result) {
                   level: sarifSeverity[rule.severity].level
                 },
                 properties: {
-                  tags: ['security', 'github-actions', 'ai-agent', 'prompt-injection', 'mcp'],
+                  tags: ruleTags(id),
                   precision: 'medium',
+                  'awguard.ruleId': id,
+                  'awguard.category': ruleCategory(id),
                   'problem.severity': sarifSeverity[rule.severity].level,
                   'security-severity': sarifSeverity[rule.severity].score
                 }
@@ -122,17 +127,28 @@ export function renderSarif(result) {
                     uri: toSarifUri(finding.file)
                   },
                   region: {
-                    startLine: finding.line
+                    startLine: finding.line,
+                    startColumn: finding.column || 1,
+                    snippet: finding.evidence
+                      ? {
+                          text: finding.evidence
+                        }
+                      : undefined
                   }
                 }
               }
             ],
             partialFingerprints: {
-              primaryLocationLineHash: finding.fingerprint || findingFingerprint(finding)
+              primaryLocationLineHash: finding.fingerprint || findingFingerprint(finding),
+              awguardStableFindingId: finding.fingerprint || findingFingerprint(finding)
+            },
+            fingerprints: {
+              'awguard/v1': finding.fingerprint || findingFingerprint(finding)
             },
             properties: {
               severity: finding.severity,
               baselineState: finding.baselineState,
+              remediationCode: finding.remediationCode,
               evidence: finding.evidence
             }
           }))
@@ -222,6 +238,73 @@ export function renderGithubAnnotations(result) {
   return result.findings.map((finding) => formatAnnotation(finding)).join('\n');
 }
 
+export function renderGithubStepSummary(result, { format = 'github', failOn = 'high', outputFile = '' } = {}) {
+  const lines = [
+    '## Agentic Workflow Guard',
+    '',
+    '| Metric | Value |',
+    '| --- | --- |',
+    `| Scanned files | ${result.scannedFiles.length} |`,
+    `| Findings | ${result.summary.total} |`,
+    `| Highest severity | ${escapeMarkdown(result.summary.highest)} |`,
+    `| Output format | ${escapeMarkdown(format)} |`,
+    `| Fail threshold | ${escapeMarkdown(failOn)} |`
+  ];
+
+  if (result.summary.baseline) {
+    lines.push(`| Baseline | ${result.summary.baseline.new} new, ${result.summary.baseline.known} known |`);
+  }
+
+  if (outputFile) {
+    lines.push(`| Report file | \`${escapeMarkdown(outputFile)}\` |`);
+  }
+
+  lines.push('');
+
+  if (result.scannedFiles.length === 0) {
+    lines.push('No GitHub Actions workflow, agent instruction, or MCP config files were found.');
+  } else if (result.findings.length === 0) {
+    lines.push('No findings. The scanned agentic surfaces are clean for the enabled rules.');
+  } else {
+    lines.push('### Top Findings', '');
+    lines.push('| Severity | Rule | Location | Finding |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const finding of result.findings.slice(0, 10)) {
+      lines.push(
+        `| ${escapeMarkdown(finding.severity)} | ${escapeMarkdown(finding.ruleId)} | \`${escapeMarkdown(
+          `${finding.file}:${finding.line}`
+        )}\` | ${escapeMarkdown(finding.title)} |`
+      );
+    }
+    if (result.findings.length > 10) {
+      lines.push('', `Showing 10 of ${result.findings.length} findings.`);
+    }
+  }
+
+  lines.push(
+    '',
+    '### Useful Follow-Ups',
+    '',
+    '- Run `npx awguard@latest . --format inventory` to map agentic surfaces.',
+    '- Run `npx awguard@latest . --format score` to generate an AWI scorecard.',
+    '- Run `npx awguard@latest . --fix-dry-run` for remediation guidance.'
+  );
+
+  return lines.join('\n');
+}
+
+function ruleCategory(ruleId) {
+  if (['AWG001', 'AWG002', 'AWG018'].includes(ruleId)) return 'prompt-injection';
+  if (['AWG003', 'AWG004', 'AWG005', 'AWG008', 'AWG016', 'AWG017'].includes(ruleId)) return 'github-actions-permissions';
+  if (['AWG013', 'AWG014', 'AWG015', 'AWG019'].includes(ruleId)) return 'mcp-governance';
+  if (ruleId === 'AWG012') return 'agent-instructions';
+  return 'workflow-hardening';
+}
+
+function ruleTags(ruleId) {
+  return ['security', 'github-actions', 'ai-agent', ruleCategory(ruleId)];
+}
+
 function formatAnnotation(finding) {
   const command = finding.severity === 'low' || finding.severity === 'medium' ? 'warning' : 'error';
   const title = `${finding.ruleId} ${finding.title}`;

package/src/scanner.js

@@ -40,7 +40,7 @@ const mcpConfigFiles = new Set([
 ]);
 
 const untrustedFieldPattern =
-  /\${{\s*github\.(?:event\.[\w.-]+\.)?(?:body|default_branch|email|head_ref|label|message|name|page_name|ref|title)\s*}}|github\.(?:event\.[\w.-]+\.)?(?:body|default_branch|email|head_ref|label|message|name|page_name|ref|title)/i;
+  /\${{\s*(?:github\.(?:event\.[\w.-]+\.)?(?:body|default_branch|email|head_ref|label|message|name|page_name|ref|title)|github\.event\.inputs\.[\w-]+|inputs\.[\w-]+)\s*}}|(?:github\.(?:event\.[\w.-]+\.)?(?:body|default_branch|email|head_ref|label|message|name|page_name|ref|title)|github\.event\.inputs\.[\w-]+|inputs\.[\w-]+)/i;
 
 const agentPattern =
   /\b(aider|anthropic|claude|codex|copilot|cursor|gemini|langchain|litellm|llm|mistral|ollama|openai|openrouter)\b|AI_API_KEY|ANTHROPIC_API_KEY|GEMINI_API_KEY|OPENAI_API_KEY/i;
@@ -57,6 +57,18 @@ const commandSinkPattern =
 const modelOutputPattern =
   /\b(agent|ai|completion|llm|model|output|patch|plan|response|result)\b/i;
 
+const mcpWorkflowPattern =
+  /\b(?:mcp|modelcontextprotocol|mcpServers|MCP_[A-Z0-9_]+|claude\s+mcp|codex\s+mcp|cursor\s+mcp)\b|@modelcontextprotocol\//i;
+
+const mcpInputKeyPattern =
+  /^\s*(?:MCP_[A-Z0-9_]+|(?:tool|mcp|server|args?|payload|request)[\w-]*)\s*[:=]/i;
+
+const repositoryWritePattern =
+  /\b(?:git\s+(?:commit|push|tag)|gh\s+(?:api|release|repo|workflow|pr\s+merge|issue\s+(?:close|edit)|label\s+)|npm\s+publish)\b/i;
+
+const safeWriteBoundaryPattern =
+  /\b(?:create-pull-request|gh\s+pr\s+create|pull-request|actions\/upload-artifact|upload-artifact|artifact-only)\b/i;
+
 const suppressionPattern = /#\s*awguard-disable-(next-line|line)\b(.*)$/i;
 
 const riskyAgentInstructionPattern =
@@ -95,99 +107,142 @@ export const ruleCatalog = {
   AWG001: {
     title: 'Untrusted text reaches an AI agent prompt',
     severity: 'high',
+    remediationCode: 'prompt.isolate-untrusted-text',
     suggestion:
       'Keep issue, PR, comment, and branch text out of privileged agent prompts unless it is reviewed, delimited, and sanitized. Run the agent with read-only permissions by default.'
   },
   AWG002: {
     title: 'Untrusted GitHub context is interpolated in a shell script',
     severity: 'high',
+    remediationCode: 'shell.quote-github-context',
     suggestion:
       'Move the expression into an env variable and reference the shell variable with quotes, or pass the value to a JavaScript action as an argument.'
   },
   AWG003: {
     title: 'pull_request_target checks out untrusted pull request code',
     severity: 'critical',
+    remediationCode: 'checkout.avoid-pr-head',
     suggestion:
       'Use pull_request for untrusted builds, or keep pull_request_target limited to base-repository metadata work without checking out head SHA/ref.'
   },
   AWG004: {
     title: 'AI agent workflow has broad token permissions',
     severity: 'high',
+    remediationCode: 'permissions.tighten-token',
     suggestion:
       'Set permissions to read-all or the smallest write scope required. Add manual approval before any agent can write code, comments, labels, or releases.'
   },
   AWG005: {
     title: 'Secrets are exposed in an untrusted agent workflow',
     severity: 'high',
+    remediationCode: 'secrets.split-privileged-workflow',
     suggestion:
       'Do not provide repository, cloud, or model-provider secrets to workflows driven by untrusted issue/PR/comment text. Split privileged work into a separate approved workflow.'
   },
   AWG006: {
     title: 'Autonomous agent runs with unsafe approval flags',
     severity: 'high',
+    remediationCode: 'agent.require-approval',
     suggestion:
       'Remove full-auto or skip-permission flags in CI. Require a human approval gate before tool use, file writes, command execution, or repository changes.'
   },
   AWG007: {
     title: 'Model or agent output may be executed by a script',
     severity: 'high',
+    remediationCode: 'output.validate-before-exec',
     suggestion:
       'Treat model output as data. Write it to a file, validate it, and apply narrow parsers instead of eval, bash -c, sh -c, or pipe-to-shell patterns.'
   },
   AWG008: {
     title: 'Agent workflow does not declare permissions',
     severity: 'medium',
+    remediationCode: 'permissions.declare-readonly',
     suggestion:
       'Declare explicit permissions, usually contents: read for analysis workflows. Escalate write scopes only in a separate, reviewed job.'
   },
   AWG009: {
     title: 'workflow_run consumes artifacts before script execution',
     severity: 'medium',
+    remediationCode: 'artifact.verify-provenance',
     suggestion:
       'Treat artifacts from earlier workflows as untrusted. Verify provenance and contents before using them in privileged workflow_run jobs.'
   },
   AWG010: {
     title: 'Third-party action is not pinned to a commit SHA',
     severity: 'low',
+    remediationCode: 'actions.pin-sha',
     suggestion:
       'Pin third-party actions to a full commit SHA in security-sensitive agent workflows, and review the action before updating the pin.'
   },
   AWG011: {
     title: 'Invalid suppression comment',
     severity: 'medium',
+    remediationCode: 'suppression.add-justification',
     suggestion:
       'Use awguard-disable-next-line or awguard-disable-line with rule ids and a clear reason after --, for example: # awguard-disable-next-line AWG001 -- reviewed false positive.'
   },
   AWG012: {
     title: 'Agent instruction file weakens review or permission boundaries',
     severity: 'high',
+    remediationCode: 'instructions.harden-agent-boundary',
     suggestion:
       'Keep AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions, and other persistent agent instruction files conservative. Do not tell agents to bypass approvals, follow untrusted issue/PR text as commands, or expose secrets.'
   },
   AWG013: {
     title: 'MCP config starts mutable or shell-based tool servers',
     severity: 'high',
+    remediationCode: 'mcp.pin-server',
     suggestion:
       'Pin MCP server packages to exact versions or container digests, avoid shell wrappers, and review project-scoped MCP servers before agents can use them.'
   },
   AWG014: {
     title: 'MCP config hardcodes secrets or auth material',
     severity: 'critical',
+    remediationCode: 'mcp.prompt-secrets',
     suggestion:
       'Move MCP credentials into input prompts, environment variables, or a secret manager. Do not commit bearer tokens, API keys, passwords, or auth headers in MCP config files.'
   },
   AWG015: {
     title: 'Agentic surface is not approved by policy',
     severity: 'medium',
+    remediationCode: 'policy.allowlist-reviewed-surface',
     suggestion:
       'Add the workflow, agent context file, MCP config, MCP server, package, or command to the policy allowlist only after review. Otherwise remove or harden it.'
+  },
+  AWG016: {
+    title: 'Checkout credentials persist into an agent workflow',
+    severity: 'high',
+    remediationCode: 'checkout.disable-persisted-credentials',
+    suggestion:
+      'Set actions/checkout persist-credentials: false in agent jobs with write tokens, or split checkout and writeback into separate reviewed jobs.'
+  },
+  AWG017: {
+    title: 'Agent writeback lacks branch or PR containment',
+    severity: 'critical',
+    remediationCode: 'writeback.use-pr-branch',
+    suggestion:
+      'Write agent changes to an isolated branch, draft pull request, or artifact. Do not let autonomous agent jobs push directly to protected branches.'
+  },
+  AWG018: {
+    title: 'Untrusted event text reaches MCP tool inputs or environment',
+    severity: 'high',
+    remediationCode: 'mcp.sanitize-untrusted-input',
+    suggestion:
+      'Keep issue, PR, branch, comment, and workflow_dispatch input text out of MCP tool arguments and environment variables unless it is reviewed and sanitized.'
+  },
+  AWG019: {
+    title: 'MCP package is outside trusted package scopes',
+    severity: 'medium',
+    remediationCode: 'mcp.review-package-reputation',
+    suggestion:
+      'Review MCP package publisher, source repository, release cadence, and install scripts before approving it. Add reviewed scopes to policy.approvedMcpPackageScopes.'
   }
 };
 
 export function scanWorkflows({ root = process.cwd(), config = {} } = {}) {
   const absoluteRoot = path.resolve(root);
   const relativeBase = fs.statSync(absoluteRoot).isFile() ? path.dirname(absoluteRoot) : absoluteRoot;
-  const files = discoverScanFiles(absoluteRoot);
+  const files = enforceScanLimits(filterScanFiles(discoverScanFiles(absoluteRoot), relativeBase, config.scan || {}), config.scan || {});
   const findings = files.flatMap((file) => scanFile(file, relativeBase, config));
 
   findings.sort((a, b) => {
@@ -245,6 +300,9 @@ export function scanWorkflowText(text, file = 'workflow.yml', root = process.cwd
   detectSecretsInAgentWorkflow(context);
   detectUnsafeAgentFlags(context);
   detectModelOutputSinks(context);
+  detectCheckoutCredentialPersistence(context);
+  detectUnsafeAgentWriteback(context);
+  detectUntrustedMcpInputs(context);
   detectMissingPermissions(context);
   detectWorkflowRunArtifacts(context);
   detectUnpinnedActions(context);
@@ -320,6 +378,12 @@ export function classifyScanFile(file, root = process.cwd()) {
 }
 
 function scanFile(file, root, config) {
+  const maxFileBytes = config.scan?.maxFileBytes;
+  if (maxFileBytes && fs.statSync(file).size > maxFileBytes) {
+    const relativeFile = path.relative(root, file).split(path.sep).join('/') || path.basename(file);
+    throw new Error(`${relativeFile} is larger than scan.maxFileBytes (${maxFileBytes}). Exclude it or raise the limit.`);
+  }
+
   const text = fs.readFileSync(file, 'utf8');
   let findings;
   if (isAgentInstructionFile(file, root)) {
@@ -359,6 +423,28 @@ function discoverScanFiles(root) {
   return [...new Set(files)].sort();
 }
 
+function filterScanFiles(files, root, scan) {
+  const include = scan.include || [];
+  const exclude = scan.exclude || [];
+
+  return files.filter((file) => {
+    const relativeFile = path.relative(root, file).split(path.sep).join('/') || path.basename(file);
+    const included = include.length === 0 || matchesAnyWildcardPattern(relativeFile, include);
+    const excluded = exclude.length > 0 && matchesAnyWildcardPattern(relativeFile, exclude);
+    return included && !excluded;
+  });
+}
+
+function enforceScanLimits(files, scan) {
+  if (scan.maxFiles && files.length > scan.maxFiles) {
+    throw new Error(
+      `scan matched ${files.length} files, above scan.maxFiles (${scan.maxFiles}). Narrow scan.include/scan.exclude or raise the limit.`
+    );
+  }
+
+  return files;
+}
+
 function walk(dir) {
   return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
     const fullPath = path.join(dir, entry.name);
@@ -389,7 +475,7 @@ function detectPromptToAgent(context) {
 function detectScriptInjection(context) {
   context.lines.forEach((line, index) => {
     if (!untrustedFieldPattern.test(line)) return;
-    if (!context.runBlocks.has(index) && !/^\s*run\s*:/.test(line)) return;
+    if (!context.runBlocks.has(index) && !/^\s*(?:-\s*)?run\s*:/.test(line)) return;
 
     addFinding(context, 'AWG002', index + 1, {
       evidence: line.trim(),
@@ -472,6 +558,66 @@ function detectModelOutputSinks(context) {
   });
 }
 
+function detectCheckoutCredentialPersistence(context) {
+  if (!context.hasAgent || (!context.hasBroadPermission && !context.triggers.has('pull_request_target'))) return;
+
+  context.lines.forEach((line, index) => {
+    if (!/uses\s*:\s*actions\/checkout@/i.test(line)) return;
+
+    const checkoutBlock = windowAfter(context.lines, index, 10);
+    const persistIndex = checkoutBlock.findIndex((candidate) => /^\s*persist-credentials\s*:/i.test(candidate));
+    const hasPersistFalse =
+      persistIndex !== -1 && /^\s*persist-credentials\s*:\s*false\s*(?:#.*)?$/i.test(checkoutBlock[persistIndex]);
+
+    if (hasPersistFalse) return;
+
+    const lineOffset = persistIndex === -1 ? 0 : persistIndex;
+    const evidence = persistIndex === -1 ? line.trim() : checkoutBlock[persistIndex].trim();
+    const message =
+      persistIndex === -1
+        ? 'actions/checkout persists the GitHub token by default in an agent workflow with elevated authority.'
+        : 'actions/checkout explicitly persists credentials in an agent workflow with elevated authority.';
+
+    addFinding(context, 'AWG016', index + lineOffset + 1, {
+      evidence,
+      message
+    });
+  });
+}
+
+function detectUnsafeAgentWriteback(context) {
+  if (!context.hasAgent || !context.hasBroadPermission) return;
+
+  context.lines.forEach((line, index) => {
+    if (!context.runBlocks.has(index) && !/^\s*(?:-\s*)?run\s*:/.test(line)) return;
+    if (!repositoryWritePattern.test(line)) return;
+
+    const windowText = windowAround(context.lines, index, 8).join('\n');
+    if (safeWriteBoundaryPattern.test(windowText) && !isProtectedBranchPush(line)) return;
+
+    addFinding(context, 'AWG017', index + 1, {
+      evidence: line.trim(),
+      message: 'An agent job with write-capable permissions appears to write back without a branch, PR, or artifact boundary.'
+    });
+  });
+}
+
+function detectUntrustedMcpInputs(context) {
+  context.lines.forEach((line, index) => {
+    if (!untrustedFieldPattern.test(line)) return;
+
+    const windowText = windowAround(context.lines, index, 8).join('\n');
+    if (!mcpWorkflowPattern.test(windowText) && !mcpInputKeyPattern.test(line)) return;
+
+    const severity = context.hasBroadPermission || context.hasSecret ? 'critical' : ruleCatalog.AWG018.severity;
+    addFinding(context, 'AWG018', index + 1, {
+      severity,
+      evidence: line.trim(),
+      message: 'User-controlled GitHub event text appears to reach MCP tool arguments or environment variables.'
+    });
+  });
+}
+
 function detectMissingPermissions(context) {
   if (!context.hasAgent || context.hasPermissionBlock) return;
 
@@ -488,7 +634,7 @@ function detectWorkflowRunArtifacts(context) {
   if (!context.triggers.has('workflow_run')) return;
   if (!/actions\/download-artifact@|download-artifact/i.test(context.lines.join('\n'))) return;
 
-  const firstRunLine = context.lines.findIndex((line) => /^\s*run\s*:/.test(line));
+  const firstRunLine = context.lines.findIndex((line) => /^\s*(?:-\s*)?run\s*:/.test(line));
   if (firstRunLine === -1) return;
 
   addFinding(context, 'AWG009', firstRunLine + 1, {
@@ -645,6 +791,18 @@ function detectMcpPolicy(context, server) {
       message: `MCP server "${server.name}" uses a package not listed in policy.approvedMcpPackages.`
     });
   }
+
+  const packageName = packageNameFromSpec(packageSpec);
+  if (
+    policy.approvedMcpPackageScopes?.length > 0 &&
+    packageName &&
+    !matchesTrustedPackageScope(packageName, policy.approvedMcpPackageScopes)
+  ) {
+    addFinding(context, 'AWG019', locateMcpLine(context, server, packageSpec), {
+      evidence: `MCP server "${server.name}" package: ${packageSpec}`,
+      message: `MCP package "${packageName}" is not in policy.approvedMcpPackageScopes.`
+    });
+  }
 }
 
 function detectFilePolicy(file, root, config) {
@@ -700,8 +858,10 @@ function addFinding(context, ruleId, line, overrides = {}) {
     file: context.relativeFile,
     absoluteFile: context.file,
     line,
+    column: overrides.column || findEvidenceColumn(context.lines[line - 1], overrides.evidence),
     message: overrides.message || docs.title,
     evidence: overrides.evidence || '',
+    remediationCode: docs.remediationCode,
     suggestion: overrides.suggestion || docs.suggestion
   };
 
@@ -721,6 +881,12 @@ function addFinding(context, ruleId, line, overrides = {}) {
   });
 }
 
+function findEvidenceColumn(sourceLine = '', evidence = '') {
+  if (!evidence) return 1;
+  const index = sourceLine.indexOf(evidence);
+  return index === -1 ? 1 : index + 1;
+}
+
 function collectSuppressions(lines, rawSuppressionConfig = {}) {
   const suppressionConfig = {
     allow: rawSuppressionConfig.allow !== false,
@@ -870,7 +1036,7 @@ function markRunBlocks(lines) {
 
   lines.forEach((line, index) => {
     const indent = leadingSpaces(line);
-    const startsRun = /^\s*run\s*:/.test(line);
+    const startsRun = /^\s*(?:-\s*)?run\s*:/.test(line);
 
     if (startsRun) {
       runBlocks.add(index);
@@ -899,6 +1065,12 @@ function isBroadPermissionLine(line) {
   );
 }
 
+function isProtectedBranchPush(line) {
+  if (!/\bgit\s+push\b/i.test(line)) return false;
+  if (/\b(?:main|master|production|release)\b/i.test(line)) return true;
+  return !/\bHEAD:(?!main\b|master\b|production\b|release\b)[\w./-]+\b/i.test(line);
+}
+
 function discoverAgentInstructionFiles(root) {
   const files = [];
 
@@ -1132,6 +1304,29 @@ function findMcpPackageSpec(baseCommand, args) {
   return '';
 }
 
+function packageNameFromSpec(packageSpec = '') {
+  if (!packageSpec || packageSpec.startsWith('.') || packageSpec.startsWith('/') || packageSpec.startsWith('${')) return '';
+  const withoutAlias = packageSpec.startsWith('npm:') ? packageSpec.slice('npm:'.length) : packageSpec;
+  if (/^(?:https?|git\+?ssh|git\+?https?):/i.test(withoutAlias)) return withoutAlias;
+
+  if (withoutAlias.startsWith('@')) {
+    const match = withoutAlias.match(/^(@[^/]+\/[^@/]+)/);
+    return match ? match[1] : withoutAlias;
+  }
+
+  return withoutAlias.split('@')[0];
+}
+
+function matchesTrustedPackageScope(packageName, scopes) {
+  return scopes.some((scope) => {
+    const normalized = String(scope).trim();
+    if (!normalized) return false;
+    if (normalized.endsWith('/')) return packageName.startsWith(normalized);
+    if (normalized.startsWith('@') && !normalized.includes('/')) return packageName.startsWith(`${normalized}/`);
+    return packageName === normalized || packageName.startsWith(normalized);
+  });
+}
+
 function isMutablePackageSpec(spec) {
   if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('${')) return false;
   if (/^(?:https?|git\+?ssh|git\+?https?):/i.test(spec)) return true;
@@ -1282,6 +1477,10 @@ function isPlainObject(value) {
 }
 
 function matchesAnyPolicyPattern(value, patterns) {
+  return matchesAnyWildcardPattern(value, patterns);
+}
+
+function matchesAnyWildcardPattern(value, patterns) {
   return patterns.some((pattern) => wildcardToRegExp(pattern).test(value));
 }