awguard 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 1.1.1
+
+- Add npm package metadata for the public `awguard` package.
+- Update README install wording now that the package is ready for npm publishing.
+
+## 1.1.0
+
+- Rename the npm package target to `awguard` to avoid the already-taken `agentic-workflow-guard` npm name.
+- Add `--format migration` for safe-output migration plans.
+- Add migration guidance that converts unsafe agent jobs into read-only proposal jobs plus validated safe outputs or approved apply jobs.
+- Document the migration report in the README and GitHub Action metadata.
+
+## 1.0.0
+
+- Add `graph` output with Mermaid attack-chain diagrams.
+- Add standalone `html` attack graph reports.
+- Add `--fix-dry-run` remediation guidance.
+- Add built-in presets: `strict`, `claude-code`, `codex`, `aider`, and `triage-bot`.
+- Add README launch polish with badges and an attack graph hook.
+
+## 0.4.0
+
+- Add `awguard.config.json` and `.awguard.json` auto-discovery.
+- Add `--config` and GitHub Action `config` input.
+- Support rule severity overrides and disabled rules.
+- Support suppression policies with allowed rule ids and minimum reason length.
+
+## 0.3.0
+
+- Add inline suppression comments with required justifications.
+- Add `AWG011` for invalid suppressions.
+- Support same-line and next-line suppressions for specific rule ids.
+- Document audited suppression usage.
+
+## 0.2.0
+
+- Add baseline files with `--write-baseline`.
+- Add `--baseline` so CI can fail only on findings that are not already known.
+- Add stable finding fingerprints to text, JSON, and SARIF output.
+- Add GitHub Action inputs for baseline workflows.
+
+## 0.1.0
+
+- Initial CLI and GitHub Action.
+- Add rules for AI-agent prompt injection, unsafe permissions, secrets, shell interpolation, `pull_request_target`, workflow artifacts, unsafe autonomous-agent flags, and unpinned third-party actions.
+- Add text, JSON, Markdown, GitHub annotation, and SARIF output.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Workflow Guard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# Agentic Workflow Guard
+
+[![Test](https://github.com/Mughal-Baig/agentic-workflow-guard/actions/workflows/test.yml/badge.svg)](https://github.com/Mughal-Baig/agentic-workflow-guard/actions/workflows/test.yml)
+[![Code Scanning](https://github.com/Mughal-Baig/agentic-workflow-guard/actions/workflows/code-scanning.yml/badge.svg)](https://github.com/Mughal-Baig/agentic-workflow-guard/actions/workflows/code-scanning.yml)
+[![GitHub release](https://img.shields.io/github/v/release/Mughal-Baig/agentic-workflow-guard)](https://github.com/Mughal-Baig/agentic-workflow-guard/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+`agentic-workflow-guard` is a small, zero-dependency scanner for GitHub Actions workflows that use AI coding agents, LLMs, or automated review bots.
+
+It looks for a new class of CI/CD risk: untrusted issue, pull request, comment, or branch text flowing into an AI agent prompt, then into write-capable tools, secrets, or shell scripts.
+
+Its unique output is an **Agentic Workflow Injection attack graph**:
+
+```mermaid
+flowchart LR
+  s["GitHub issue/comment/PR text"] --> p["AI agent prompt"]
+  p --> c["agent tools or shell"]
+  c --> a["secrets / write token"]
+  a --> i["repo modification or secret exposure"]
+```
+
+## Why This Project Can Reach People
+
+Developers want AI speed, but they also want a safety net. Stack Overflow's 2025 Developer Survey found that agent users report productivity gains, while 81% of respondents still worry about security and data privacy for AI agents. GitHub's Octoverse 2025 says AI is now standard in development, with more than 1.1 million public repositories using an LLM SDK and 80% of new developers using Copilot in their first week.
+
+The missing piece is a tool that is easy enough for maintainers to add before they fully understand the security problem. This project gives them one command and one GitHub Action.
+
+## Install
+
+For local development:
+
+```bash
+npm test
+node ./bin/awguard.js .
+```
+
+Install from npm:
+
+```bash
+npx awguard .
+```
+
+## Use In GitHub Actions
+
+After you upload this repository to GitHub, users can add:
+
+```yaml
+name: Agentic Workflow Guard
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  scan-agent-workflows:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Mughal-Baig/agentic-workflow-guard@v0
+        with:
+          config: awguard.config.json
+          preset: strict
+          fail-on: high
+```
+
+To adopt the scanner without breaking CI on old findings, commit a baseline file and use:
+
+```yaml
+      - uses: Mughal-Baig/agentic-workflow-guard@v0
+        with:
+          baseline: awguard.baseline.json
+          fail-on: high
+```
+
+## Use With GitHub Code Scanning
+
+Generate SARIF and upload it with GitHub's official CodeQL SARIF upload action:
+
+```yaml
+name: Agentic Workflow Guard Code Scanning
+
+on:
+  push:
+  schedule:
+    - cron: '22 5 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Mughal-Baig/agentic-workflow-guard@v0
+        with:
+          format: sarif
+          output: awguard.sarif
+          fail-on: none
+      - uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: awguard.sarif
+          category: agentic-workflow-guard
+```
+
+## CLI
+
+```bash
+awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fail-on none|low|medium|high|critical]
+```
+
+Examples:
+
+```bash
+node ./bin/awguard.js examples/unsafe-agent.yml
+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 . --fix-dry-run
+node ./bin/awguard.js . --format markdown --fail-on medium
+node ./bin/awguard.js . --format sarif --output awguard.sarif --fail-on none
+node ./bin/awguard.js . --write-baseline awguard.baseline.json
+node ./bin/awguard.js . --baseline awguard.baseline.json --fail-on high
+node ./bin/awguard.js . --format github --fail-on high
+```
+
+## Baseline Mode
+
+Baseline mode lets a project start using the scanner without failing CI for already-known issues.
+
+Create a baseline:
+
+```bash
+node ./bin/awguard.js . --write-baseline awguard.baseline.json --fail-on none
+```
+
+Then fail only on findings that are not in the baseline:
+
+```bash
+node ./bin/awguard.js . --baseline awguard.baseline.json --fail-on high
+```
+
+The baseline stores stable finding fingerprints, not secrets or workflow contents.
+
+## Configuration
+
+Agentic Workflow Guard automatically loads `awguard.config.json` or `.awguard.json` from the scan root. You can also pass `--config`.
+
+```json
+{
+  "rules": {
+    "AWG010": "off",
+    "AWG008": "low",
+    "AWG004": {
+      "severity": "critical"
+    }
+  },
+  "suppressions": {
+    "allowedRules": ["AWG001", "AWG002"],
+    "minimumReasonLength": 20
+  }
+}
+```
+
+Rule values can be `"off"`, `"low"`, `"medium"`, `"high"`, or `"critical"`.
+See `examples/awguard.config.example.json` for a complete template.
+
+Built-in presets:
+
+- `strict`
+- `claude-code`
+- `codex`
+- `aider`
+- `triage-bot`
+
+Use them with `--preset strict` or in config with `"extends": ["strict"]`.
+
+## Attack Graph And HTML Reports
+
+Generate a Mermaid attack graph:
+
+```bash
+node ./bin/awguard.js examples/unsafe-agent.yml --format graph
+```
+
+Generate a standalone HTML report:
+
+```bash
+node ./bin/awguard.js examples/unsafe-agent.yml --format html --output awguard-report.html
+```
+
+The report maps source, prompt boundary, capability, authority, and impact for each finding.
+
+## Safe-Output Migration Plans
+
+Generate a migration checklist for converting unsafe agent workflows into read-only agent jobs plus validated safe outputs or approved apply jobs:
+
+```bash
+node ./bin/awguard.js examples/unsafe-agent.yml --format migration --output awguard-migration.md
+```
+
+The migration report groups findings by workflow file, explains the risk shape, suggests allowed GitHub operations, and gives a reference two-stage pattern:
+
+```text
+untrusted GitHub event text
+  -> read-only agent job
+  -> structured proposal artifact
+  -> schema and policy validation
+  -> safe outputs or approved apply job
+```
+
+## Fix Dry Run
+
+Print remediation guidance without editing files:
+
+```bash
+node ./bin/awguard.js examples/unsafe-agent.yml --fix-dry-run
+```
+
+## Inline Suppressions
+
+Suppressions are for reviewed false positives. They must include a reason after `--`.
+
+```yaml
+# awguard-disable-next-line AWG001,AWG002 -- Reviewed: this workflow only runs after maintainer approval.
+- run: openai --prompt "${{ github.event.comment.body }}"
+
+permissions: write-all # awguard-disable-line AWG004 -- Reviewed: release job needs tag write access.
+```
+
+If you omit rule ids, the suppression applies to all findings on the target line. Suppression comments without a clear reason are reported as `AWG011`.
+
+## What It Detects
+
+| Rule | Severity | What it finds |
+| --- | --- | --- |
+| AWG001 | High/Critical | Untrusted GitHub event text passed into an AI agent prompt |
+| AWG002 | High | Untrusted GitHub context interpolated in a shell script |
+| AWG003 | Critical | `pull_request_target` checking out PR head code |
+| AWG004 | High | AI-agent workflows with broad write permissions |
+| AWG005 | High | Secrets exposed to untrusted agent workflows |
+| AWG006 | High | Agent flags such as `--dangerously-skip-permissions` or `--yolo` |
+| AWG007 | High | Model/agent output names flowing into command execution |
+| AWG008 | Medium | Agent workflow missing explicit `permissions` |
+| AWG009 | Medium | `workflow_run` consuming artifacts before scripts |
+| AWG010 | Low | Third-party actions in agent workflows not pinned to a SHA |
+| AWG011 | Medium | Invalid suppression comments |
+
+## Example Finding
+
+```text
+[CRITICAL] AWG001 Untrusted text reaches an AI agent prompt
+  .github/workflows/ai-triage.yml:24
+  User-controlled GitHub event text appears to be used as prompt/input for an AI agent.
+  Fix: Keep issue, PR, comment, and branch text out of privileged agent prompts unless it is reviewed, delimited, and sanitized.
+```
+
+## Roadmap
+
+- Safe autofix for low-risk permission changes.
+- Safe-output migration patch previews for common triage and review bots.
+- 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.
+
+## Research Backing
+
+See [docs/market-analysis.md](docs/market-analysis.md) for the demand analysis, gap, audience, and launch plan.

package/action.yml

@@ -0,0 +1,46 @@
+name: Agentic Workflow Guard
+description: Scan GitHub Actions workflows for AI-agent injection and unsafe permission patterns.
+author: agentic-workflow-guard
+inputs:
+  path:
+    description: Repository path or workflow file to scan.
+    required: false
+    default: .
+  format:
+    description: Output format: github, text, json, markdown, sarif, graph, html, or migration.
+    required: false
+    default: github
+  fail-on:
+    description: Minimum severity that fails the check: none, low, medium, high, or critical.
+    required: false
+    default: high
+  output:
+    description: Optional file path for json, markdown, sarif, graph, html, or migration output.
+    required: false
+    default: ''
+  baseline:
+    description: Optional Agentic Workflow Guard baseline file. Matching findings are treated as known and do not fail the check.
+    required: false
+    default: ''
+  write-baseline:
+    description: Optional path to write a baseline file for the current scan.
+    required: false
+    default: ''
+  config:
+    description: Optional path to an Agentic Workflow Guard JSON config file.
+    required: false
+    default: ''
+  preset:
+    description: Optional comma-separated presets such as strict, claude-code, codex, aider, or triage-bot.
+    required: false
+    default: ''
+  fix-dry-run:
+    description: Print remediation guidance instead of the normal report.
+    required: false
+    default: 'false'
+runs:
+  using: node20
+  main: bin/awguard.js
+branding:
+  icon: shield
+  color: blue

package/bin/awguard.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2), process.env).catch((error) => {
+  console.error(`awguard: ${error.message}`);
+  process.exitCode = 2;
+});

package/docs/launch-plan.md

@@ -0,0 +1,52 @@
+# Launch Plan
+
+## Positioning
+
+Agentic Workflow Guard should be described as an Agentic Workflow Injection mapper, not just a GitHub Actions scanner.
+
+Short pitch:
+
+> Find where untrusted GitHub issue, PR, comment, branch, or artifact text can steer AI agents inside CI.
+
+## Star-Worthy Demo
+
+1. Show `examples/unsafe-agent.yml`.
+2. Run:
+
+   ```bash
+   node ./bin/awguard.js examples/unsafe-agent.yml --format graph
+   ```
+
+3. Show the generated Mermaid chain.
+4. Run:
+
+   ```bash
+   node ./bin/awguard.js examples/unsafe-agent.yml --fix-dry-run
+   ```
+
+5. Show the safe remediation steps.
+6. Run:
+
+   ```bash
+   node ./bin/awguard.js examples/unsafe-agent.yml --format migration
+   ```
+
+7. Show the migration from unsafe agent job to read-only proposal job plus safe outputs or an approved apply job.
+
+## Release Checklist
+
+- Publish GitHub release notes for `v1.0.0`.
+- Add the action to GitHub Marketplace from the release UI.
+- Publish the npm package as `awguard`; do not use `agentic-workflow-guard` because that npm name is already controlled by another maintainer.
+- Pin the README demo to the attack graph, not the rule table.
+- Post with the headline: "I built a scanner that maps and migrates Agentic Workflow Injection in GitHub Actions."
+- Include the AWI attack chain screenshot in social posts.
+- Include the migration report screenshot after the graph screenshot.
+
+## Distribution Targets
+
+- Hacker News: Show HN.
+- Reddit: `r/github`, `r/devsecops`, `r/cybersecurity`.
+- GitHub Community Discussions.
+- OWASP GenAI / LLM app security communities.
+- Maintainers of AI triage, AI review, and coding-agent GitHub Actions.

package/docs/market-analysis.md

@@ -0,0 +1,162 @@
+# Market Analysis
+
+## The Opportunity
+
+The public GitHub project with the best reach right now is not another general AI wrapper. The stronger opportunity is a safety tool for teams adopting AI coding agents inside GitHub Actions.
+
+Why:
+
+- GitHub's Octoverse 2025 says AI is now standard in development, more than 1.1 million public repositories use an LLM SDK, and 80% of new GitHub developers use Copilot in their first week.
+- Stack Overflow's 2025 Developer Survey reports that AI agents help developers move faster, but 81% of respondents are concerned about security and privacy of data when using AI agents.
+- OWASP's GenAI Security Project exists because LLM and agentic systems created a new security category, not just a new developer convenience.
+- GitHub's own Actions security docs warn that attacker-controlled `github` context values such as issue bodies, PR titles, branch names, and comments must be treated as untrusted.
+- A 2026 paper on Agentic Workflow Injection found real GitHub Actions workflows where untrusted event text entered agent prompts or downstream scripts, with hundreds of exploitable cases.
+
+## What Is Missing
+
+Existing GitHub Actions security tools tend to focus on broad CI/CD issues: unpinned actions, `pull_request_target`, dangerous permissions, and secrets. Existing AI safety tools tend to focus on app prompts, RAG pipelines, or runtime model behavior.
+
+The gap is the intersection:
+
+```text
+untrusted GitHub event text -> AI agent prompt -> privileged GitHub Actions environment
+```
+
+Maintainers need a tool that explains this specific risk in their workflow files, without asking them to adopt a full enterprise scanner.
+
+## Who Wants It
+
+- Open-source maintainers adding AI issue triage, PR review, or coding agents.
+- Small teams experimenting with Claude Code, Codex, Copilot, Gemini, Aider, or custom LLM scripts in CI.
+- DevSecOps engineers who need a quick control before allowing AI agents in repositories.
+- Security researchers looking for a small, readable rule engine they can improve.
+
+## Product Shape
+
+The first version should be:
+
+- Zero dependency, so people trust and inspect it quickly.
+- CLI first, because developers can test it locally before adding CI.
+- GitHub Action ready, because maintainers want one copy-paste workflow step.
+- Text, JSON, Markdown, GitHub annotation, and SARIF output.
+- Conservative rules with useful explanations, not a noisy wall of generic warnings.
+
+## Second-Pass Improvement: SARIF
+
+The strongest improvement after the MVP is SARIF output. GitHub code scanning can ingest third-party SARIF files, which means findings can appear as native security alerts instead of only terminal logs. GitHub's SARIF upload workflow requires `security-events: write`, `contents: read`, and the official `github/codeql-action/upload-sarif` action.
+
+This makes the project more valuable to maintainers because:
+
+- It meets teams where they already review security alerts.
+- It makes the scanner useful on a schedule, not only during PR checks.
+- It allows future severity, fingerprint, and suppression workflows.
+- It positions the tool next to existing static analyzers instead of as a one-off script.
+
+## Third-Pass Improvement: Baselines
+
+The next strongest adoption feature is baseline mode. Mature scanners invest heavily in triage, ignore states, deduplication, and separating new findings from known findings because teams rarely enable a new security gate if it immediately blocks work on historical issues.
+
+Agentic Workflow Guard now supports:
+
+- `--write-baseline awguard.baseline.json` to record current findings.
+- `--baseline awguard.baseline.json` to mark matching findings as known.
+- CI failure based only on findings that are not already in the baseline.
+- Stable fingerprints based on rule, file, and normalized evidence.
+
+This improves public reach because a maintainer can add the tool to a real repository with risk already present, keep visibility into the existing risk, and still block new high-severity agent-workflow mistakes.
+
+## Fourth-Pass Improvement: Auditable Suppressions
+
+Baseline mode helps teams start. Inline suppressions help them stay. Mature scanners support local suppressions because false positives and intentionally accepted risks happen, but the useful pattern is to require a reason so the exception is reviewable later.
+
+Agentic Workflow Guard now supports:
+
+- `# awguard-disable-next-line AWG001 -- reason` for the next reported line.
+- `# awguard-disable-line AWG004 -- reason` for same-line findings.
+- Multiple rule ids separated by spaces or commas.
+- `AWG011` findings when suppression comments omit a clear justification or reference unknown rules.
+
+This makes the project safer to adopt publicly because it gives maintainers a practical false-positive escape hatch without normalizing silent ignores.
+
+## Fifth-Pass Improvement: Project Configuration
+
+The next adoption layer is project configuration. ESLint and Semgrep both normalize the idea that teams should tune rule severity, disable specific rules, and define policy in a checked-in file. Agentic Workflow Guard now supports the same shape for this narrower security domain.
+
+Agentic Workflow Guard now supports:
+
+- `awguard.config.json` and `.awguard.json` auto-discovery from the scan root.
+- `--config path/to/config.json` for explicit config.
+- Rule severity overrides such as `"AWG004": "critical"`.
+- Disabled rules such as `"AWG010": "off"`.
+- Suppression policy such as allowed suppression rule ids and minimum reason length.
+
+This improves public reach because teams can adopt the scanner without forking it or arguing with one-size-fits-all severity choices.
+
+## V1 Improvement: Attack Graph Reports
+
+The strongest unique hook is the attack graph report. Existing GitHub Actions scanners focus on workflow hygiene or supply-chain risk. Agentic Workflow Guard should own the Agentic Workflow Injection path:
+
+```text
+untrusted GitHub event text -> agent prompt -> tool capability -> authority -> impact
+```
+
+This is what makes the project easy to screenshot, explain, and share. It also follows the shape of AWI research more closely than a flat list of findings.
+
+The v1 release adds:
+
+- `--format graph` for Mermaid attack chains.
+- `--format html --output awguard-report.html` for a standalone report.
+- `--fix-dry-run` for safe remediation guidance.
+- Built-in presets for strict mode and common agent stacks.
+
+## Deep Research Refresh: Unique Angle After V1
+
+The stronger post-v1 position is not to become a broad AI security scanner. Popular neighboring projects already own the broad categories:
+
+- `zizmorcore/zizmor` and `rhysd/actionlint` own general GitHub Actions static analysis and linting.
+- `ossf/scorecard` owns open-source security health scoring.
+- `step-security/harden-runner` owns runner runtime hardening and egress visibility.
+- `affaan-m/agentshield`, `splx-ai/agentic-radar`, and `cisco-ai-defense/skill-scanner` own broader AI-agent, MCP, and skill-scanning surfaces.
+- `github/gh-aw` owns the emerging GitHub Agentic Workflows ecosystem.
+
+The gap Agentic Workflow Guard can still own is narrower and more memorable:
+
+```text
+find Agentic Workflow Injection -> explain the attack path -> migrate to safe outputs
+```
+
+This is why v1.1 adds `--format migration`. The output turns findings into a practical plan for moving unsafe agent jobs into a two-stage architecture:
+
+```text
+untrusted GitHub event text -> read-only agent job -> structured proposal -> validation -> safe outputs or approved apply job
+```
+
+This makes the project more distinctive because maintainers do not only get a red finding. They get a path from "my AI triage bot is risky" to "my bot can only perform allowed GitHub operations after validation."
+
+## Discovery Risk Found During Research
+
+The unscoped npm package name `agentic-workflow-guard` is already published by another maintainer and points to a different GitHub repository. Keeping that name in this repository would confuse users and could send `npx agentic-workflow-guard` traffic to the wrong code.
+
+The v1.1 package target is now `awguard`, matching the existing CLI binary and leaving the GitHub Action name unchanged.
+
+## Distribution Plan
+
+1. Publish the repo with a short demo GIF or screenshot.
+2. Add topics: `github-actions`, `ai-agents`, `prompt-injection`, `security`, `devsecops`, `llm`.
+3. Post a concrete example: "Your AI triage workflow may be letting issue comments steer an agent with write tokens."
+4. Submit to security and GitHub communities with before/after workflow snippets.
+5. Add a short terminal demo and code-scanning screenshot after the first public run.
+
+## Sources
+
+- Stack Overflow 2025 Developer Survey, AI section: https://survey.stackoverflow.co/2025/ai
+- GitHub Octoverse 2025: https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/
+- GitHub Actions script injection docs: https://docs.github.com/en/actions/concepts/security/script-injections
+- GitHub SARIF upload docs: https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github
+- GitHub Actions secure use reference: https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/secure-use
+- GitHub Agentic Workflows security architecture: https://github.github.com/gh-aw/
+- OpenSSF Scorecard dangerous workflow check: https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow
+- Semgrep inline ignore docs: https://semgrep.dev/docs/ignoring-files-folders-code
+- ESLint configuration comment descriptions: https://eslint.org/docs/latest/use/configure/rules#configuration-comment-descriptions
+- OWASP Top 10 for Large Language Model Applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/
+- Agentic Workflow Injection paper: https://arxiv.org/abs/2605.07135

package/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+- `unsafe-agent.yml`: intentionally vulnerable AI triage workflow.
+- `safe-agent.yml`: quieter workflow with read-only permissions and bounded prompt file.
+- `suppressed-agent.yml`: demonstrates audited inline suppressions.
+- `pull-request-target.yml`: demonstrates privileged PR checkout risk.
+- `awguard.config.example.json`: sample config with a strict preset and overrides.
+
+Try:
+
+```bash
+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 unsafe-agent.yml --fix-dry-run
+```

package/examples/awguard.config.example.json

@@ -0,0 +1,14 @@
+{
+  "extends": ["strict"],
+  "rules": {
+    "AWG010": "off",
+    "AWG008": "low",
+    "AWG004": {
+      "severity": "critical"
+    }
+  },
+  "suppressions": {
+    "allowedRules": ["AWG001", "AWG002"],
+    "minimumReasonLength": 20
+  }
+}

package/examples/pull-request-target.yml

@@ -0,0 +1,16 @@
+name: Unsafe PR target
+
+on:
+  pull_request_target:
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - run: npm test