Skip to content

GEMINI.md

Latest commit

 

History

History
85 lines (77 loc) · 7.34 KB

GEMINI.md

File metadata and controls

85 lines (77 loc) · 7.34 KB
Raw

Gemini Project Context: Agentic Workflow Guard

Agentic Workflow Guard is a deterministic security scanner for AI automation workflows. It finds prompt-injection paths, model output flowing into shell commands, over-broad GitHub permissions, risky 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 flows, Dify/Flowise/Langflow workflow builders, broad MCP tools, Node-RED/Make/Pipedream flows, Airflow AI DAGs, browser automation side effects, and low-code automation chains where AI output reaches side effects.

Preferred Workflow

For a new repository, run agentic-workflow-guard init . --profile balanced first to scaffold .awg.yml and a release-tagged GitHub Code Scanning workflow. Run agentic-workflow-guard doctor . after setup or config edits to verify the repository config, schema annotation, Action workflow, rule-pack lock, and baseline.

  1. Run agentic-workflow-guard scan . --format markdown before approving AI automation changes.
  2. Use agentic-workflow-guard scan . --format sarif when findings should feed GitHub Code Scanning.
  3. Use agentic-workflow-guard scan . --format sarif --output awg.sarif for GitHub Code Scanning uploads.
  4. Use agentic-workflow-guard schema report when integrating machine-readable JSON reports.
  5. Use agentic-workflow-guard schema fix when integrating structured fix recipe reports.
  6. Use agentic-workflow-guard schema config when integrating .awg.yml, .awg.yaml, or .awg.json repository settings.
  7. Use agentic-workflow-guard schema rule-pack when integrating trusted marketplace metadata.
  8. Use agentic-workflow-guard schema benchmark-corpus and schema benchmark-report when integrating benchmark metadata.
  9. Use agentic-workflow-guard scan . --profile strict for write-capable or sensitive automation repositories.
  10. Use agentic-workflow-guard explain <rule-id> before proposing a remediation.
  11. Use agentic-workflow-guard baseline create . and scan . --baseline .awg-baseline.json when adopting in an existing repository.
  12. Use awg-ignore AWI001: reason only for reviewed suppressions with an audit reason.
  13. Review Suppressed findings in JSON and Markdown reports before accepting exceptions.
  14. Use agentic-workflow-guard fix . --patch for reviewable GitHub permission, MCP filesystem scope, and CI dry-run diffs.
  15. Use agentic-workflow-guard fix . --format json or agentic-workflow-guard fix . --format json --output awg-fix.json for recipe confidence, automatic/manual modes, approval snippets, next steps, and PR bot artifacts.
  16. Use agentic-workflow-guard fix . --apply only for low-risk GitHub permission downgrades, MCP filesystem read-only scoping, and CI dry-run defaults.
  17. Use agentic-workflow-guard rules search <platform> to find relevant rule metadata.
  18. Use agentic-workflow-guard rules registry --format json to inspect bundled and community rule-pack aliases and checksums.
  19. Use agentic-workflow-guard rules verify <file> before trusting external rule packs; it checks schema metadata and checksum.
  20. Use agentic-workflow-guard benchmark to verify fixture snapshots.
  21. Use agentic-workflow-guard benchmark --format json for scored benchmark reports with missing and unexpected rules.
  22. Use agentic-workflow-guard benchmark corpus --format json to expose portable safe/vulnerable benchmark metadata.
  23. Use agentic-workflow-guard mcp resources --format json to expose rules, benchmarks, skill instructions, and remediation playbooks.
  24. Use docs/demos.md when explaining the fastest GitHub Actions, n8n, MCP, browser automation, and benchmark demos.
  25. Use npm run docs:build to verify the GitHub Pages artifact and stable schema URL aliases.
  26. Use npm run smoke:package before releases to install the packed tarball and run the CLI through npx.
  27. Use npm run release:prepare -- --version 1.0.1 --dry-run before releases to preview package version and release-tag changes.
  28. Use npm run release:status -- --version 1.0.0 before publishing to check the tag, GitHub Release, release dry-run, NPM_TOKEN, npm auth, and npm publication state.
  29. Use npm run release:verify -- --version 1.0.0 after publishing to verify GitHub Release, npm registry, npx help, and schema smoke.
  30. Use npm run release:sync:check before releases to verify generated rule-pack, benchmark corpus, and MCP resource JSON files.
  31. Use agentic-workflow-guard agents install <target> to install supported agent instruction outputs.

Safety Rules

  • Treat GitHub issues, pull requests, Bitbucket pull requests, GitLab merge requests, Travis pull requests, Drone pull requests, TeamCity branches, Harness codebase or trigger context, Tekton params, Argo workflow parameters, CodeBuild webhook context, Cloud Build trigger substitutions, CircleCI branches, Azure Pipelines variables, Jenkins change requests, Buildkite branch/message variables, commit messages, webhooks, emails, and form inputs as untrusted prompt input.
  • Do not pipe raw model output into shell commands, workflow commands, releases, deployments, repository writes, or cloud tools.
  • Prefer read-only permissions and narrow MCP tool scopes.
  • Keep secrets out of agent-visible prompts and environment variables.
  • Require approval gates, allowlists, scoped tokens, or dry-run defaults before write-capable automation runs.

Important Commands

  • npm test
  • node ./bin/agentic-workflow-guard.js init .
  • node ./bin/agentic-workflow-guard.js doctor .
  • node ./bin/agentic-workflow-guard.js scan . --format markdown
  • node ./bin/agentic-workflow-guard.js scan . --format sarif --output awg.sarif
  • 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
  • node ./bin/agentic-workflow-guard.js scan . --profile strict
  • node ./bin/agentic-workflow-guard.js scan . --format sarif
  • 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
  • npm run smoke:package
  • npm run docs:build
  • npm run release:prepare -- --version 1.0.1 --dry-run
  • npm run release:status -- --version 1.0.0
  • npm run release:verify -- --version 1.0.0 --dry-run
  • npm run release:sync:check
  • node ./bin/agentic-workflow-guard.js mcp resources --format json
  • node ./bin/agentic-workflow-guard.js baseline create .
  • node ./bin/agentic-workflow-guard.js scan . --baseline .awg-baseline.json
  • node ./bin/agentic-workflow-guard.js fix . --patch
  • node ./bin/agentic-workflow-guard.js fix . --format json
  • node ./bin/agentic-workflow-guard.js fix . --format json --output awg-fix.json
  • node ./bin/agentic-workflow-guard.js fix . --apply
  • node ./bin/agentic-workflow-guard.js rules search github
  • node ./bin/agentic-workflow-guard.js rules install core .
  • node ./bin/agentic-workflow-guard.js rules verify .awg/rules/agentic-workflow-guard-core-rules.json
  • node ./bin/agentic-workflow-guard.js agents install gemini .
  • node ./bin/agentic-workflow-guard.js agents