awguard 1.6.0 → 1.7.0

package/docs/npm-publishing.md

@@ -0,0 +1,68 @@
+# npm Trusted Publishing And Provenance
+
+This project publishes the `awguard` npm package. The preferred release path is npm trusted publishing from GitHub Actions, which uses OIDC instead of a long-lived npm automation token.
+
+## Why Use Trusted Publishing
+
+Trusted publishing reduces risk because npm accepts a short-lived publish identity from a specific workflow instead of requiring a saved token. npm also generates provenance automatically for public packages published through trusted publishing from a public GitHub repository.
+
+Official docs:
+
+- npm trusted publishing: <https://docs.npmjs.com/trusted-publishers/>
+- npm provenance statements: <https://docs.npmjs.com/generating-provenance-statements/>
+- npm provenance viewing: <https://docs.npmjs.com/viewing-package-provenance/>
+
+## One-time npm Setup
+
+On npmjs.com:
+
+1. Open the `awguard` package.
+2. Go to package settings.
+3. Find Trusted Publisher.
+4. Select GitHub Actions.
+5. Use these fields:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `Mughal-Baig` |
+| Repository | `agentic-workflow-guard` |
+| Workflow filename | `npm-publish.yml` |
+| Environment name | leave empty unless using a protected GitHub environment |
+| Allowed actions | `npm publish` |
+
+After the first successful trusted publish, consider setting publishing access to require 2FA and disallow tokens. Do this only after trusted publishing is verified.
+
+## Release Workflow
+
+The repository includes `.github/workflows/npm-publish.yml`.
+
+It:
+
+- Runs only on GitHub-hosted runners.
+- Uses `permissions: id-token: write`.
+- Runs tests before publishing.
+- Publishes with `npm publish --access public`.
+- Avoids storing `NPM_TOKEN`.
+
+## Maintainer Release Checklist
+
+1. Confirm `npm test` passes locally.
+2. Confirm `git status` is clean.
+3. Update `CHANGELOG.md`.
+4. Bump `package.json` version.
+5. Commit and push.
+6. Create a GitHub Release or run the workflow manually.
+7. Confirm the package appears on npm.
+8. Confirm npm shows provenance for the version.
+9. Confirm GitHub Actions, Code Scanning, and Docker image workflows pass.
+
+## Manual Fallback
+
+Manual publish is still possible for emergencies:
+
+```bash
+npm login
+npm publish --access public --provenance
+```
+
+Manual publishing may require 2FA depending on account settings. Prefer the trusted publishing workflow for normal releases.

package/docs/release-checklist.md

@@ -0,0 +1,71 @@
+# Release And Marketplace Checklist
+
+Use this checklist before cutting a public AWGuard release or updating the GitHub Marketplace listing.
+
+## Pre-release
+
+- Confirm `npm test` passes.
+- Confirm `git diff --check` passes.
+- Confirm `npm pack --dry-run` includes the intended docs, examples, schemas, action metadata, and CLI files.
+- Run `node ./bin/awguard.js . --format inventory`.
+- Run `node ./bin/awguard.js . --format score`.
+- Run `node ./bin/awguard.js examples/lab/unsafe --format html --output /tmp/awguard-report.html`.
+- Review `CHANGELOG.md`.
+- Confirm README badges render.
+- Confirm the project site loads.
+- Confirm the GitHub Marketplace draft matches current features.
+
+## Screenshots To Capture
+
+| Screenshot | Command or page |
+| --- | --- |
+| Terminal demo | `node ./bin/awguard.js demo` |
+| Inventory report | `node ./bin/awguard.js examples/lab/unsafe --format inventory` |
+| AWI score | `node ./bin/awguard.js examples/lab/unsafe --format score` |
+| SARIF / code scanning | GitHub Security tab after SARIF upload |
+| HTML attack graph | `node ./bin/awguard.js examples/lab/unsafe --format html --output awguard-report.html` |
+| Policy wizard | `node ./bin/awguard.js policy-wizard examples/lab/unsafe --dry-run` |
+| Baseline review | `node ./bin/awguard.js baseline-review . --baseline awguard.baseline.json` |
+
+## Marketplace Copy
+
+Short description:
+
+```text
+Scan GitHub Actions, agent instruction files, and MCP configs for AI-agent injection risk.
+```
+
+Recommended categories:
+
+- Security
+- Code quality
+- Utilities
+
+Primary value points:
+
+- Finds untrusted GitHub text reaching AI prompts, MCP inputs, or shell scripts.
+- Flags agent jobs with unsafe write permissions, secrets, and writeback.
+- Scans AGENTS.md, Copilot instructions, custom agents, prompts, skills, Cursor rules, and MCP configs.
+- Produces SARIF, attack graphs, migration plans, inventories, scorecards, badges, and baselines.
+
+## Release
+
+1. Bump `package.json` version.
+2. Commit with a concise release message.
+3. Push `main`.
+4. Create a GitHub tag such as `v1.7.0`.
+5. Create a GitHub Release from the tag.
+6. Confirm `npm-publish.yml` publishes `awguard`.
+7. Confirm `docker.yml` publishes GHCR images.
+8. Update the moving `v0` action tag if the Action entrypoint changed.
+9. Confirm `npx awguard@latest . --version` or `npm view awguard version`.
+10. Add release screenshots and notes to the GitHub Release.
+
+## Post-release
+
+- Check GitHub Actions.
+- Check npm package contents.
+- Check GitHub code scanning.
+- Check the GitHub Pages site.
+- Close any release tracking issues that were not closed by commit messages.
+- Post a short launch note with the new report, rule, or workflow users can copy.

package/docs/report-gallery.md

@@ -0,0 +1,166 @@
+# Report Gallery
+
+AWGuard has several report formats because different users need different entry points. The gallery below shows when to use each report and which command creates it.
+
+## Text Findings
+
+Use for local terminal review.
+
+```bash
+npx awguard@latest examples/lab/unsafe
+```
+
+Best for:
+
+- First scans.
+- Quick triage.
+- Copying a finding into an issue.
+
+## GitHub Annotations
+
+Use inside GitHub Actions.
+
+```yaml
+- uses: Mughal-Baig/agentic-workflow-guard@v0
+  with:
+    preset: strict
+    fail-on: high
+```
+
+Best for:
+
+- Pull request checks.
+- Inline workflow annotations.
+- Blocking newly introduced high-risk patterns.
+
+## SARIF
+
+Use for GitHub code scanning.
+
+```bash
+npx awguard@latest . --format sarif --output awguard.sarif --fail-on none
+```
+
+Best for:
+
+- Security tab visibility.
+- Alert tracking.
+- Teams that already use CodeQL or third-party SARIF uploads.
+
+## Inventory
+
+Use to explain the repository's agentic surface area.
+
+```bash
+npx awguard@latest . --format inventory
+npx awguard@latest . --format inventory-json --output awguard-inventory.json
+```
+
+Best for:
+
+- Security reviews before adding coding agents.
+- Finding all instruction files and MCP configs.
+- Showing non-security maintainers where agent authority lives.
+
+## Attack Graph
+
+Use to explain why a finding matters.
+
+```bash
+npx awguard@latest examples/lab/unsafe --format graph
+```
+
+Best for:
+
+- Pull request discussions.
+- Issue reports.
+- Design reviews where a table of findings is too flat.
+
+## HTML Report
+
+Use when you need a standalone shareable artifact.
+
+```bash
+npx awguard@latest examples/lab/unsafe --format html --output awguard-report.html
+```
+
+Best for:
+
+- Release assets.
+- Blog posts.
+- Marketplace screenshots.
+
+## Migration Plan
+
+Use when a project needs practical fixes.
+
+```bash
+npx awguard@latest examples/lab/unsafe --format migration --output awguard-migration.md
+```
+
+Best for:
+
+- Converting unsafe agent jobs into read-only proposal jobs.
+- Splitting privileged writeback into reviewed workflows.
+- Turning findings into task lists.
+
+## Score And Badge
+
+Use when you want a public progress signal.
+
+```bash
+npx awguard@latest . --format score
+npx awguard@latest . --format badge --output docs/awguard-badge.json
+```
+
+Best for:
+
+- README badges.
+- Tracking cleanup progress.
+- Showing an easy-to-understand risk grade.
+
+## Compare
+
+Use to show what changed between branches, releases, or scheduled scans.
+
+```bash
+npx awguard@latest . --format json --output current-awguard.json
+npx awguard@latest --compare previous-awguard.json current-awguard.json
+```
+
+Best for:
+
+- Release gates.
+- Scheduled drift monitoring.
+- Baseline cleanup work.
+
+## Dashboard POC
+
+Use to show AWI score, finding count, introduced/resolved findings, and agentic surface growth over time.
+
+```bash
+cd examples/dashboard
+python3 -m http.server 8090
+```
+
+Open `http://127.0.0.1:8090/`.
+
+Best for:
+
+- GitHub App dashboard planning.
+- GitHub Pages demos.
+- Organization-level trend conversations.
+
+## Policy Wizard
+
+Use to generate a starter allowlist for reviewed agentic surfaces.
+
+```bash
+npx awguard@latest policy-wizard . --dry-run
+```
+
+Best for:
+
+- Moving from detection to governance.
+- Reviewing newly added MCP servers or agent instruction files.
+- Making repository-specific policy explicit.

package/docs/roadmap.md

@@ -57,7 +57,36 @@ Current research points:
 - Shipped `--format inventory`.
 - Shipped `--format inventory-json`.
 - Shipped `awguard init`.
+- Shipped `awguard doctor`.
+- Shipped `awguard explain`.
+- Shipped `awguard badges`.
+- Shipped `awguard demo`.
+- Shipped `awguard templates`.
+- Shipped `awguard policy-pack`.
+- Shipped `scan.include` and `scan.exclude` config globs.
+- Shipped Node 24 action runtime readiness.
+- Shipped SARIF columns, snippets, stable AWGuard fingerprints, and rule categories.
+- Shipped `AWG016`, `AWG017`, and `AWG018` for checkout credentials, unsafe writeback, and MCP input injection.
+- Shipped machine-readable remediation codes.
+- Shipped large-repo scan guardrails.
+- Shipped end-to-end golden tests for lab, compare, inventory, and score outputs.
+- Shipped baseline review/prune command.
+- Shipped policy wizard starter config command.
+- Shipped PR comment bot example and Docker image publish workflow.
+- Shipped expanded comparison docs for `zizmor`, `actionlint`, OpenSSF Scorecard, secret scanning, and MCP runtime scanners.
+- Shipped setup recipes for Claude Code, Codex, Cursor, GitHub Copilot, and Cline.
+- Shipped report gallery, rule authoring guide, npm trusted publishing guide, and release checklist.
+- Shipped npm trusted publishing workflow for tokenless OIDC publishing.
+- Shipped real-world pattern corpus for public demos and regression coverage.
+- Shipped VS Code task problem matcher and extension proof of concept.
+- Shipped local AWI trend dashboard proof of concept with sample history data.
+- Shipped opt-in safe autofix mode for narrow workflow permission and checkout hardening edits.
+- Shipped offline MCP package reputation policy checks with trusted package scopes.
+- Shipped `awguard.config.json` schema support.
+- Shipped stable schemas for machine-readable report outputs.
+- Shipped GitHub Actions job summaries.
 - Shipped `--compare previous.json current.json`.
+- Shipped agentic surface diffs in compare reports.
 - Shipped first policy allowlists with `AWG015`.
 - Expanded `AWG012` coverage to Copilot custom agents, prompts, and skills.
 - Added Docker, GitLab CI, pre-commit, VS Code task, Marketplace, comparison, visual demo, and vulnerable lab assets.
@@ -65,11 +94,12 @@ Current research points:
 ### Next
 
 - Add agent capability SBOM export for prompts, tools, MCP servers, permissions, and write paths.
-- Add safer patch previews for common workflow permission fixes.
 - Add richer policy ownership fields for approved file owners and review cadence.
+- Add screenshot automation for the report gallery and Marketplace listing.
+- Add more public corpus fixtures for popular agent PR review and triage patterns.
+- Turn the VS Code and dashboard POCs into installable, tested integrations.
 
 ### Later
 
 - Add trend reports for "new agent surface introduced" diffs.
-- Build the vulnerable lab and screenshot-friendly walkthroughs.
 - Explore a GitHub App after the CLI and Action adoption path is stable.

package/docs/rule-authoring.md

@@ -0,0 +1,99 @@
+# Rule Authoring Guide
+
+This guide is for contributors adding new AWGuard rules or improving existing detections.
+
+## Rule Design Principles
+
+Good AWGuard rules are:
+
+- Agentic: they involve AI agents, MCP servers, persistent instructions, or automation that hands authority to a model-driven tool.
+- Boundary-focused: they explain a trust boundary, not only a style preference.
+- Reviewable: the finding should point to a specific file, line, evidence string, and remediation.
+- CI-safe: rules must not execute repository code, start MCP servers, call network services, or require secrets.
+- Low-noise: false positives should have clear suppression and configuration paths.
+
+## Add A Rule
+
+1. Add a `ruleCatalog` entry in `src/scanner.js`.
+2. Choose a stable rule id such as `AWG020`.
+3. Set `title`, default `severity`, `remediationCode`, and `suggestion`.
+4. Implement a focused detector function in `src/scanner.js`.
+5. Call the detector from the relevant scan path:
+   - `scanWorkflowText` for workflow content.
+   - `scanAgentInstructionText` for persistent instruction files.
+   - `scanMcpConfigText` for MCP configs.
+   - `scanFile` or `detectFilePolicy` for file-level policy checks.
+6. Add unit tests that cover the unsafe and safe pattern.
+7. Add an example fixture if the rule teaches a common real-world pattern.
+8. Update README rule tables and any docs that mention rule coverage.
+9. Run `npm test`.
+
+## Severity Guidance
+
+| Severity | Use when |
+| --- | --- |
+| `critical` | Untrusted input can plausibly reach secrets, write tokens, privileged checkout, protected branch writeback, or hardcoded auth material. |
+| `high` | The pattern can change repository state, guide an agent with attacker-controlled text, or weaken approval boundaries. |
+| `medium` | The pattern creates drift, missing guardrails, or review ambiguity without direct exploitability. |
+| `low` | The pattern is hardening guidance for security-sensitive agent workflows. |
+
+## Remediation Codes
+
+Every finding has a `remediationCode` because dashboards should not depend on free-text suggestions.
+
+Use this naming shape:
+
+```text
+domain.action-specific-fix
+```
+
+Examples:
+
+- `permissions.tighten-token`
+- `mcp.pin-server`
+- `prompt.isolate-untrusted-text`
+- `writeback.use-pr-branch`
+
+Do not rename existing remediation codes unless there is a compatibility reason and changelog entry.
+
+## Detector Checklist
+
+Before opening a PR, confirm:
+
+- The detector does not execute code or parse arbitrary shell with unsafe side effects.
+- The finding evidence is short and specific.
+- The detector respects inline suppressions through `addFinding`.
+- Rule severity can be overridden through config.
+- JSON, Markdown, SARIF, GitHub annotation, and text outputs still render.
+- The unsafe test fails before the detector and passes after it.
+- The safe test proves a recommended remediation avoids the finding.
+
+## Fixture Checklist
+
+Examples should be safe to publish:
+
+- No real tokens, secrets, domains, private names, or customer data.
+- Intentionally fake secrets should use obvious placeholder values.
+- Unsafe examples should be labeled as unsafe.
+- Fixed examples should show the recommended pattern, not only silence the scanner.
+- Every new fixture should be referenced from `examples/README.md`.
+
+## Documentation Checklist
+
+When adding or changing a rule, update:
+
+- `README.md` rule table.
+- `CHANGELOG.md`.
+- `docs/report-gallery.md` if the output teaches a new report shape.
+- `docs/comparison.md` only if the rule changes AWGuard's position beside other tools.
+- `schemas/` only if the machine-readable contract changes.
+
+## Review Checklist
+
+Reviewers should ask:
+
+- Does this find a real agentic workflow risk?
+- Could a maintainer understand and fix the finding in less than five minutes?
+- Does the safe example avoid the risk rather than hiding it?
+- Does the rule duplicate a better tool such as `actionlint` or a secret scanner?
+- Does this rule keep AWGuard zero-dependency and safe for pull request scans?

package/docs/schemas.md

@@ -0,0 +1,16 @@
+# AWGuard Report Schemas
+
+AWGuard publishes JSON Schema files for the outputs that are designed for automation.
+
+| Output | Command | Schema |
+| --- | --- | --- |
+| Scan report | `awguard . --format json` | [`schemas/awguard.report.schema.json`](../schemas/awguard.report.schema.json) |
+| Inventory | `awguard . --format inventory-json` | [`schemas/awguard.inventory.schema.json`](../schemas/awguard.inventory.schema.json) |
+| Compare | `awguard --compare old.json new.json --format json` | [`schemas/awguard.comparison.schema.json`](../schemas/awguard.comparison.schema.json) |
+| Baseline | `awguard . --write-baseline awguard.baseline.json` | [`schemas/awguard.baseline.schema.json`](../schemas/awguard.baseline.schema.json) |
+| Badge | `awguard . --format badge` | [`schemas/awguard.badge.schema.json`](../schemas/awguard.badge.schema.json) |
+| Config | `awguard.config.json` | [`schemas/awguard.config.schema.json`](../schemas/awguard.config.schema.json) |
+
+The SARIF output uses the official SARIF 2.1.0 schema.
+
+The comparison JSON includes both finding diffs and agentic surface diffs so dashboards can show when workflows, agent context files, or MCP configs are added or removed.

package/docs/setup-recipes.md

@@ -0,0 +1,199 @@
+# Setup Recipes For AI Coding Agent Repositories
+
+Use these recipes when a repository already has AI coding agents, prompt files, MCP configs, or GitHub Actions that call LLM tools.
+
+## Universal First Run
+
+```bash
+npx awguard@latest doctor
+npx awguard@latest . --format inventory
+npx awguard@latest policy-wizard . --dry-run
+npx awguard@latest . --preset strict --format sarif --output awguard.sarif --fail-on none
+```
+
+Review the inventory first. It shows which files give agents instructions, tools, credentials, or workflow authority.
+
+## GitHub Actions
+
+Create `.github/workflows/agentic-workflow-guard.yml`:
+
+```yaml
+name: Agentic Workflow Guard
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: Mughal-Baig/agentic-workflow-guard@v0
+        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
+```
+
+If the repository has many old findings, start with a baseline:
+
+```bash
+npx awguard@latest . --write-baseline awguard.baseline.json --fail-on none
+```
+
+Then add `baseline: awguard.baseline.json` to the Action inputs.
+
+## Claude Code
+
+Files to review:
+
+- `CLAUDE.md`
+- `AGENTS.md`
+- `.mcp.json`
+- `claude_desktop_config.json`
+- `.github/workflows/*.yml`
+
+Recommended checks:
+
+```bash
+npx awguard@latest . --preset claude-code --format inventory
+npx awguard@latest CLAUDE.md --format text
+npx awguard@latest .mcp.json --format text
+```
+
+Hardening checklist:
+
+- Keep `CLAUDE.md` conservative about approvals and command execution.
+- Do not commit MCP auth tokens.
+- Pin MCP server packages to exact versions.
+- Avoid telling agents to obey issue, PR, or comment text as commands.
+- Split read-only agent analysis from any writeback job.
+
+## Codex
+
+Files to review:
+
+- `AGENTS.md`
+- `CODEX.md`
+- `.mcp.json`
+- `.github/workflows/*.yml`
+
+Recommended checks:
+
+```bash
+npx awguard@latest . --preset codex --format inventory
+npx awguard@latest AGENTS.md --format text
+npx awguard@latest . --format migration
+```
+
+Hardening checklist:
+
+- Keep repository instructions focused on code style, testing, and review expectations.
+- Require human approval before file writes, shell execution, or privileged repository changes.
+- Do not put secrets or package tokens in MCP config.
+- Use `permissions: contents: read` for agent analysis jobs.
+
+## Cursor
+
+Files to review:
+
+- `.cursorrules`
+- `.cursor/rules/*.{md,mdc,txt}`
+- `.cursor/mcp.json`
+- `.github/workflows/*.yml`
+
+Recommended checks:
+
+```bash
+npx awguard@latest . --format inventory
+npx awguard@latest .cursor/mcp.json --format text
+```
+
+Hardening checklist:
+
+- Treat Cursor rules as persistent agent instructions.
+- Avoid global autonomy instructions such as "never ask for approval."
+- Pin project MCP packages and containers.
+- Keep workspace rules separate from secrets and credentials.
+
+## GitHub Copilot
+
+Files to review:
+
+- `.github/copilot-instructions.md`
+- `.github/instructions/*.instructions.md`
+- `.github/agents/*.md`
+- `.github/prompts/*.prompt.md`
+- `.github/skills/**/SKILL.md`
+- `.github/workflows/*.yml`
+
+Recommended checks:
+
+```bash
+npx awguard@latest . --format inventory
+npx awguard@latest .github --format text
+```
+
+Hardening checklist:
+
+- Keep reusable prompts bounded and reviewable.
+- Do not tell Copilot agents to follow PR or issue text as trusted instructions.
+- Keep skills and custom agents scoped to specific safe tasks.
+- Use branch, pull request, or artifact containment for any AI-generated patch.
+
+## Cline
+
+Files to review:
+
+- `.clinerules`
+- `cline_mcp_settings.json`
+- `.cline/mcp_settings.json`
+- `.github/workflows/*.yml`
+
+Recommended checks:
+
+```bash
+npx awguard@latest . --format inventory
+npx awguard@latest cline_mcp_settings.json --format text
+```
+
+Hardening checklist:
+
+- Keep `.clinerules` from weakening approval boundaries.
+- Do not commit tokens in Cline MCP settings.
+- Prefer pinned MCP package versions.
+- Review new MCP servers before they are available to an agent.
+
+## Safe PR Comment Bot Pattern
+
+Copy `examples/pr-comment-bot.yml` into `.github/workflows/awguard-pr-comment.yml` if you want AWGuard to comment on pull requests.
+
+The example intentionally uses:
+
+- `pull_request`, not `pull_request_target`.
+- `contents: read`.
+- `pull-requests: write` only for same-repository PR comments.
+- No secrets in forked PR execution.
+
+## Adoption Order
+
+1. Run `doctor` and `inventory`.
+2. Add the GitHub Action with `fail-on: none`.
+3. Generate and commit a baseline if needed.
+4. Enable SARIF upload.
+5. Turn on `fail-on: high`.
+6. Add a reviewed `awguard.config.json` policy.
+7. Review baseline drift weekly with `awguard baseline-review`.