Agentic Workflow Guard

Static analysis for AI automation workflows. Find prompt-injection paths, overpowered tools, and write-capable agent jobs before they run.

Agentic Workflow Guard is a Semgrep-style scanner for agentic workflows: unsafe GitHub Actions, Bitbucket Pipelines, GitLab CI, Travis CI, Drone CI, TeamCity, Harness CI/CD, Tekton Pipelines, Argo Workflows, AWS CodeBuild, Google Cloud Build, CircleCI, Azure Pipelines, Jenkins, and Buildkite agent jobs; risky n8n, Dify, Flowise, Langflow, and low-code workflow side effects; browser automation traces; and MCP permission leaks.

Six-command demo:

npx agentic-workflow-guard init .
npx agentic-workflow-guard doctor .
npx agentic-workflow-guard scan examples/unsafe-ai-pr-bot --format markdown
npx agentic-workflow-guard scan examples/unsafe-ai-pr-bot --format sarif --output awg.sarif
npx agentic-workflow-guard fix examples/unsafe-ai-pr-bot --patch
npx agentic-workflow-guard skillpack > skillpack.yaml

The exported skillpack.yaml can be compiled by Skillpack Forge into AGENTS.md, Claude Skills, Codex Skills, Cursor rules, and Copilot instructions. The package also ships portable Gemini, OpenClaw, and Hermes skill bundles through agents install.

Public docs and stable schema URLs are available on GitHub Pages at https://guorunjie.github.io/agentic-workflow-guard/.

Start with Demo Playbook when you want a quick story for the risk: untrusted input -> AI decision -> write-capable side effect.

Agentic Workflow Guard is a static security scanner for AI automation workflows. It scans repositories and workflow exports for risky paths such as:

• untrusted GitHub issue, Bitbucket pull request, GitLab merge request, Travis pull request, Drone pull request, TeamCity branch, Harness codebase or trigger context, Tekton params, Argo workflow parameters, CodeBuild webhook context, Cloud Build trigger substitutions, CircleCI branch, Azure Pipelines pull request, Jenkins change request, Buildkite branch or commit message, or commit text entering an agent prompt;
• model output flowing into shell commands;
• AI jobs with write permissions;
• Bitbucket Pipelines, GitLab CI, Travis CI, Drone CI, TeamCity, Harness CI/CD, Tekton Pipelines, Argo Workflows, AWS CodeBuild, Google Cloud Build, CircleCI, Azure Pipelines, Jenkins, and Buildkite agent jobs that execute model output or expose CI tokens, secrets, credentials, contexts, service connections, deployments, OIDC tokens, Kubernetes secret refs, or variable groups;
• n8n webhook or email triggers flowing through AI nodes into HTTP, code, or command nodes;
• broad MCP filesystem, shell, browser, or GitHub tools;
• low-code automation flows that chain AI steps into side effects;
• Dify, Flowise, Langflow, Node-RED, Make, Pipedream, and Airflow workflows where LLM output reaches HTTP, tools, shell, or deployment actions;
• browser-use, Skyvern, Playwright, and Puppeteer traces where AI decisions reach browser side effects.

Why This Can Win Stars

High-star automation projects show the pattern:

• n8n and Activepieces prove workflow automation plus AI/MCP integrations is a large developer category.
• Dify proves agentic workflow development is a production platform category.
• browser-use, Skyvern, and Playwright MCP prove browser/tool automation for agents is sticky.
• Anthropic Skills, AGENTS.md, Gemini CLI context files, and awesome-copilot show that agent instructions and skills are becoming a distribution layer.

The crowded side is building more automation. The open wedge is guarding automation before it runs. Agentic Workflow Guard is built for that gap: a local, CI-friendly, no-LLM scanner that gives security teams and maintainers concrete findings before an agent gets write access.

Use Cases

Agentic Workflow Guard is useful when automation touches external input, credentials, or write-capable tools.

Quick Start

Initialize a repository with .awg.yml and a GitHub Actions workflow:

node ./bin/agentic-workflow-guard.js init .
node ./bin/agentic-workflow-guard.js doctor .

Run against the unsafe AI PR bot demo:

node ./bin/agentic-workflow-guard.js scan examples/unsafe-ai-pr-bot --format markdown

Run against a repository:

node ./bin/agentic-workflow-guard.js scan . --format markdown

Fail CI on medium and high findings:

node ./bin/agentic-workflow-guard.js scan . --profile strict --format sarif > awg.sarif

Emit SARIF for GitHub Code Scanning:

node ./bin/agentic-workflow-guard.js scan . --format sarif --output awg.sarif

Print stable JSON schemas:

node ./bin/agentic-workflow-guard.js schema report
node ./bin/agentic-workflow-guard.js schema fix
node ./bin/agentic-workflow-guard.js schema config
node ./bin/agentic-workflow-guard.js schema rule-pack
node ./bin/agentic-workflow-guard.js schema benchmark-corpus
node ./bin/agentic-workflow-guard.js schema benchmark-report

Explain a rule:

node ./bin/agentic-workflow-guard.js explain AWI001

Preview remediation:

node ./bin/agentic-workflow-guard.js fix . --dry-run
node ./bin/agentic-workflow-guard.js fix . --format json
node ./bin/agentic-workflow-guard.js fix . --format json --output awg-fix.json

Generate a reviewable patch without editing files:

node ./bin/agentic-workflow-guard.js fix . --patch

Apply low-risk automatic fixes:

node ./bin/agentic-workflow-guard.js fix . --apply

Create a baseline for existing findings:

node ./bin/agentic-workflow-guard.js baseline create .
node ./bin/agentic-workflow-guard.js scan . --baseline .awg-baseline.json

Verify the bundled benchmark fixtures:

node ./bin/agentic-workflow-guard.js benchmark
node ./bin/agentic-workflow-guard.js benchmark --format json

Export the public benchmark corpus metadata:

node ./bin/agentic-workflow-guard.js benchmark corpus --format json

Export the MCP resource pack:

node ./bin/agentic-workflow-guard.js mcp resources --format json

Inspect and install focused rule packs:

node ./bin/agentic-workflow-guard.js rules registry --format json
node ./bin/agentic-workflow-guard.js rules install github-actions-hardening .
node ./bin/agentic-workflow-guard.js rules install ci-pipeline-hardening .
node ./bin/agentic-workflow-guard.js rules install mcp-tool-governance .

Initialize config and CI scaffolding:

node ./bin/agentic-workflow-guard.js init . --profile balanced
node ./bin/agentic-workflow-guard.js init . --ci none
node ./bin/agentic-workflow-guard.js init . --force
node ./bin/agentic-workflow-guard.js doctor .

Export a Skillpack Forge manifest:

node ./bin/agentic-workflow-guard.js skillpack > skillpack.yaml
npx skillpack-forge compile . --dry-run
npx skillpack-forge compile .
npx skillpack-forge doctor .
npx skillpack-forge diff .

Confirm mainstream agent support:

node ./bin/agentic-workflow-guard.js agents
node ./bin/agentic-workflow-guard.js agents install claude .
node ./bin/agentic-workflow-guard.js agents install gemini .
node ./bin/agentic-workflow-guard.js agents install mcp-resources .

Commands

Agent Compatibility

Agentic Workflow Guard now covers the mainstream agent context surfaces used by AI coding tools.

Claude, Codex, Cursor, Copilot, AGENTS.md, and Gemini use repository-local instruction files directly. OpenClaw and Hermes support is shipped as portable SKILL.md bundles so teams can use the shared skills/ package, a namespaced project copy, or their runtime-specific skill install directory. The MCP resource pack uses stable awg:// URIs so an MCP server or agent runtime can expose the core rules, benchmark fixtures, benchmark corpus, report schemas, auditor skill, and remediation playbooks as contextual resources.

Rule Catalog

Configuration

Add .awg.yml to tune CI behavior:

ignore:
  - node_modules/**
  - dist/**
profile: balanced
severityThreshold: high
rules:
  AWI007: off

profile controls rollout mode: advisory reports without blocking normal findings, balanced fails on high severity findings, and strict fails on medium and high findings. severityThreshold can override the profile default. rules can disable noisy checks for a repository, while ignore removes generated files or fixture directories from scanning. Use .awg-baseline.json when adopting the scanner in an existing repository and you want CI to fail only on newly introduced findings.

The config format is documented by a stable schema:

node ./bin/agentic-workflow-guard.js schema config

The public schema URL is https://guorunjie.github.io/agentic-workflow-guard/schemas/config.schema.json.

After editing config or workflow setup, run:

node ./bin/agentic-workflow-guard.js doctor .

For reviewed exceptions, use inline suppressions with a reason:

# awg-ignore AWI001: issue body is copied from an internal release form
prompt: "Summarize ${{ github.event.issue.body }}"

Suppression comments without a reason are ignored. See Policy Profiles and Suppressions for rollout guidance.

JSON and Markdown reports include a Suppressed findings audit trail so reviewed exceptions remain visible in CI logs and security reviews.

GitHub Action

Use this repository as a GitHub Action and upload SARIF to GitHub Code Scanning:

node ./bin/agentic-workflow-guard.js init .

name: agentic workflow guard

on:
  pull_request:
  push:
    branches: [main]

jobs:
  guard:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v6
      - uses: guorunjie/agentic-workflow-guard@v1.0.0
        with:
          path: .
          format: sarif
          profile: balanced
          output: awg.sarif
          fix-format: json
          fix-output: awg-fix.json
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: awg.sarif
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: agentic-workflow-guard-fix-report
          path: awg-fix.json

For GitHub Marketplace, use a release tag, for example guorunjie/agentic-workflow-guard@v1.0.0. The optional fix-output input writes a structured remediation artifact for PR bots, review comments, or follow-up agent loops.

Examples

node ./bin/agentic-workflow-guard.js scan examples/unsafe-ai-pr-bot --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-github-action --format json
node ./bin/agentic-workflow-guard.js scan examples/safe-github-action --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-bitbucket-pipelines --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-gitlab-ci --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-travis-ci --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-drone-ci --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-teamcity --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-harness --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-tekton --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-argo-workflows --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-aws-codebuild --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-google-cloud-build --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-circleci --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-azure-pipelines --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-buildkite --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-jenkins --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-n8n --format sarif
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-mcp --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-dify --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-flowise --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-langflow --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-node-red --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-make --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-pipedream --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-zapier --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-airflow --format markdown
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-browser-trace --format markdown
node ./bin/agentic-workflow-guard.js scan examples/safe-browser-trace --format markdown
node ./bin/agentic-workflow-guard.js fix examples/unsafe-ai-pr-bot --format json
node ./bin/agentic-workflow-guard.js benchmark
node ./bin/agentic-workflow-guard.js benchmark --format json
node ./bin/agentic-workflow-guard.js benchmark corpus --format json
node ./bin/agentic-workflow-guard.js mcp resources

Evolution Roadmap

The goal is to become the safety skill for mainstream automation platforms.

See ROADMAP.md for the full path to mainstream platform coverage, docs/v1-readiness.md for the remaining 1.0 release gates, and docs/use-cases-and-growth.md for the high-star growth strategy.

Contributing And Security

• Read CONTRIBUTING.md before adding platform scanners, rule packs, benchmark fixtures, fix recipes, or agent outputs.
• Use SECURITY.md for scanner bypasses, unsafe automatic fixes, package integrity issues, and private vulnerability reporting guidance.
• Follow CODE_OF_CONDUCT.md in public issues, reviews, and security-sensitive discussions.
• Pull requests should use the checklist in .github/pull_request_template.md; issue templates cover bug reports, platform coverage requests, and rule-pack proposals.

Development

npm test
node ./bin/agentic-workflow-guard.js scan examples/vulnerable-github-action --format json
node ./bin/agentic-workflow-guard.js benchmark --format json
node ./bin/agentic-workflow-guard.js benchmark corpus --format json
node ./bin/agentic-workflow-guard.js mcp resources --format json
npm run docs:build
npm run smoke:package
npm run release:prepare -- --version 1.0.1 --dry-run
npm run release:status -- --version 1.0.0 --dry-run
npm run release:publish -- --version 1.0.0 --plan
npm run release:verify -- --version 1.0.0 --dry-run
npm run release:sync:check
npm run release:check
npm pack --dry-run

Agentic Workflow Guard is intentionally deterministic: no LLM call, no API key, no hosted service.