Skip to main content

​
What this gives you

A single uses: line that installs agent-guardian, runs a scan, writes SARIF, and uploads it to GitHub Code Scanning. Use this in place of the longhand workflow in GitHub Actions when you want the shortest possible adoption path.

​
Wire it up

Grant permissions

The calling workflow must grant security-events: write so SARIF upload succeeds, and pull-requests: write so the sticky PR comment can be upserted. Composite actions cannot declare repository-level permissions, so the caller owns this.
permissions:
  contents: read
  pull-requests: write     # required for the sticky AgentGuardian comment
  security-events: write   # required for codeql-action/upload-sarif

Add the action

.github/workflows/agent-guardian.yml
name: AgentGuardian
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: glacien-technologies/agent-guardian/.github/actions/agentguardian-scan@v1
        with:
          framework: langgraph
          framework-ref: my_app.graph:graph
          model: gemini:gemini-2.5-flash
          mode: full
          fail-under: "70"
          max-critical: "0"
          comment: "true"
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Confirm the run

Open a PR. The scan check appears in the PR conversation, the SARIF artifact is attached to the workflow run, and findings show up under Security → Code scanning keyed by the agentguardian category.

​
Inputs

NameDefaultDescription
target""Positional dotted path (MODULE:ATTR). Mutually exclusive with the other target inputs.
system-prompt""Path to a system prompt file.
endpoint""Hosted HTTP endpoint URL.
framework""adk, autogen, crewai, langgraph, openai_agents, strands.
framework-ref""MODULE:ATTR for the framework-native object.
modelstubLLM spec (e.g. gemini:gemini-2.5-flash).
modefullfast, smart, or full.
budget-usd""Runtime USD cap. Empty disables the cap.
fail-under70Minimum AIVSS for exit-0. Empty skips the gate.
max-critical0CRITICAL-finding ceiling (--max-critical). Exceeding it fails the gate. Empty disables this ceiling.
max-high""HIGH-finding ceiling (--max-high). Empty disables this ceiling.
max-medium""MEDIUM-finding ceiling (--max-medium). Empty disables this ceiling.
max-low""LOW-finding ceiling (--max-low). Empty disables this ceiling.
commenttrueOn a pull_request event, upsert a sticky AgentGuardian summary comment via agent-guardian comment. Set false to skip.
output-pathagentguardian-scan.sarifWhere the SARIF is written.
upload-sariftrueSet false to skip the Code Scanning upload.
categoryagentguardianSARIF category used for Code Scanning grouping.
agent-guardian-version""pip install version specifier. Empty = latest.
python-version3.12Python runtime.
extra-args""Extra flags appended verbatim.

​
Outputs

NameDescription
sarif-pathPath of the SARIF report.
exit-codeRaw scan exit code (see exit codes).

​
Severity gates

fail-under gates on the numeric AIVSS floor. The max-* inputs add per-severity ceilings on top of it, AND-combined: the gate fails if AIVSS drops below fail-under or any severity count exceeds its ceiling. The default max-critical: "0" means a single CRITICAL finding fails the build even when the AIVSS still clears the floor. 
with:
  fail-under: "70"   # AIVSS floor
  max-critical: "0"  # zero CRITICAL findings tolerated
  max-high: "0"      # zero HIGH findings tolerated
  max-medium: "5"    # up to 5 MEDIUM findings allowed
Set any of these to an empty string ("") to disable that individual ceiling.

​
Sticky PR comment

When comment is true (default) and the workflow is triggered by a pull_request event, the action runs agent-guardian comment --platform github after the scan. It upserts a single summary comment on the PR — keyed by a hidden HTML marker so re-runs edit the existing comment in place rather than posting a new one on every push. The comment embeds the same fail-under / max-* verdict as the gate, so a green/red comment always matches the CI exit code. The comment step is advisory: if it cannot post (for example a fork PR whose GITHUB_TOKEN lacks write scope) it logs a warning and the job continues — it never changes the scan’s pass/fail outcome. See PR comments for a rendered sample and the marker details.

​
Sample report

A static reference report generated from a real scan: sample-report.pdf.

​
When to use the longhand form instead

Use the longhand workflow when you need to:
  • Run on a self-hosted runner without internet access (you supply your own install step).
  • Run the scan inside a services: container that the composite action would not see.
  • Compose multiple scans against the same target across the same job (the composite action assumes one scan per step).