GitHub Action
Integrate Inkog security scanning into your CI/CD pipeline with zero configuration. The GitHub Action automatically scans your AI agents on every push and pull request.
Quick Start
Add this workflow to your repository:
name: AI Agent Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
permissions:
security-events: write
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: inkog-io/inkog@v1
with:
api-key: ${{ secrets.INKOG_API_KEY }}
path: '.'
policy: 'balanced'Add your API key to repository secrets: Settings → Secrets → Actions → New secret → Name it INKOG_API_KEY
This will:
- Scan your codebase on every push and PR
- Post results as a PR comment
- Upload findings to GitHub’s Security tab (SARIF)
- Fail the workflow if critical/high findings are detected
Inputs
| Input | Default | Description |
|---|---|---|
path | . | Path to scan (file or directory) |
policy | balanced | Security policy (see Policies) |
severity | low | Minimum severity: critical, high, medium, low |
diff | false | Compare against baseline (for CI/CD regression detection) |
baseline | .inkog-baseline.json | Path to baseline file |
update-baseline | false | Update baseline after scan (use on main branch) |
fail-on-findings | true | Fail workflow if findings detected |
comment-on-pr | true | Post scan results as PR comment |
sarif-upload | true | Upload SARIF to GitHub Security tab |
api-key | - | Required. Your Inkog API key (from app.inkog.io ) |
version | latest | Inkog CLI version to use |
Outputs
| Output | Description |
|---|---|
findings-count | Total number of security findings |
critical-count | Number of critical severity findings |
high-count | Number of high severity findings |
medium-count | Number of medium severity findings |
low-count | Number of low severity findings |
risk-score | Overall risk score (0-100) |
sarif-file | Path to SARIF output file |
is-regression | True if new critical/high findings detected (diff mode) |
exit-code | Scan exit code (0=clean, 1=findings, 2=error) |
Security Policies
Choose a policy based on your needs:
| Policy | Description | Best For |
|---|---|---|
low-noise | Only proven exploitable vulnerabilities | CI/CD pipelines, blocking builds |
balanced | Vulnerabilities + risk patterns (default) | Most teams, code review |
comprehensive | All findings including recommendations | Security audits |
governance | Human oversight, authorization, audit trails | Article 14 compliance |
eu-ai-act | EU AI Act Articles 12, 14, 15 | Regulatory compliance |
Diff Mode (Recommended)
For established projects, use diff mode to only fail on new findings. This prevents breaking PRs due to pre-existing issues while still catching regressions.
How It Works
- Main branch: Scan and update the baseline file
- Pull requests: Compare against baseline, fail only on new critical/high findings
Setup
name: AI Agent Security (Diff Mode)
on:
push:
branches: [main]
pull_request:
permissions:
contents: write
security-events: write
pull-requests: write
jobs:
# Update baseline on main branch
update-baseline:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: inkog-io/inkog@v1
with:
update-baseline: 'true'
fail-on-findings: 'false'
- name: Commit Baseline
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .inkog-baseline.json
git diff --cached --quiet || git commit -m "chore: update security baseline"
git push
# Check for regressions on PRs
check-regression:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download baseline
run: |
git fetch origin main
git show origin/main:.inkog-baseline.json > .inkog-baseline.json 2>/dev/null || echo '{"findings":[]}' > .inkog-baseline.json
- uses: inkog-io/inkog@v1
with:
diff: 'true'
fail-on-findings: 'true'Exit Codes in Diff Mode
| Exit Code | Condition | Description |
|---|---|---|
0 | No new findings OR only medium/low severity | Success |
1 | New critical or high severity findings | Regression detected |
2 | Scan error | Error |
EU AI Act Compliance
Generate compliance evidence for EU AI Act Articles 12-15:
name: EU AI Act Compliance
on:
schedule:
- cron: '0 9 * * 1' # Weekly audit
pull_request:
jobs:
compliance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: inkog-io/inkog@v1
with:
policy: 'eu-ai-act'
fail-on-findings: 'false'
- name: Save Report
run: inkog -path . -policy eu-ai-act -output html > compliance-report.html
- uses: actions/upload-artifact@v4
with:
name: eu-ai-act-compliance
path: compliance-report.html
retention-days: 90Using Outputs
Access scan results in subsequent workflow steps:
- uses: inkog-io/inkog@v1
id: scan
with:
path: '.'
- name: Check Results
run: |
echo "Total findings: ${{ steps.scan.outputs.findings-count }}"
echo "Risk score: ${{ steps.scan.outputs.risk-score }}"
if [ "${{ steps.scan.outputs.critical-count }}" -gt 0 ]; then
echo "::error::Critical vulnerabilities detected!"
fiPR Comment Format
When comment-on-pr: true, Inkog posts a summary to your PR:
## ⚠️ Inkog Security Scan
| Metric | Value |
|--------|-------|
| **Status** | 2 high severity issues found |
| **Risk Score** | 65/100 |
| 🔴 Critical | 0 |
| 🟠 High | 2 |
| 🟡 Medium | 1 |
| 🟢 Low | 0 |
### Top Findings
- 🟠 **User input flows to LLM prompt** - `agent.py:42`
- 🟠 **Unbounded loop in tool call** - `tools.py:89`GitHub Security Tab Integration
With sarif-upload: true, findings appear in the Security tab of your repository under Code scanning alerts. This provides:
- Centralized view of all security findings
- Historical tracking across PRs
- Integration with GitHub’s security features
- Automatic dismissal of fixed issues
Permissions
The action requires these permissions:
permissions:
security-events: write # For SARIF upload
pull-requests: write # For PR comments
contents: write # For baseline commits (diff mode)Troubleshooting
Action fails to download CLI
If the action can’t download the Inkog binary, check:
- Network connectivity to GitHub releases
- Try specifying a version:
version: 'v1.0.0'
SARIF upload fails
Ensure security-events: write permission is set and GitHub Advanced Security is enabled (for private repos).
PR comment not appearing
Verify pull-requests: write permission and that the workflow is running on a pull request event.