GitHub Actions integration

shadowaudit is available as a GitHub Marketplace Action. Add it to your workflow to scan for shadow API routes on every pull request.

Quick start

Create .github/workflows/security.yml in your repo:

name: shadowaudit API Security Scan

on:
  pull_request:
    branches: [main]

jobs:
  shadowaudit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run shadowaudit
        uses: darkmaster0345/shadow-Audit@v0.3.0
        with:
          dir: './src'
          spec: './openapi.json'
          fail-on: 'critical'
          post-comment: 'true'

Inputs

Input	Description	Required	Default
dir	Directory to scan	No	'.'
spec	Path to OpenAPI/Swagger spec file	No	''
format	Output format: table, json, sarif	No	'table'
fail-on	Fail on: critical, high, info	No	'critical'
framework	Framework: express, fastapi, django, auto	No	'auto'
post-comment	Post findings as PR comment (true/false)	No	'true'
github-token	GitHub token for PR comments	No	${{ github.token }}

Outputs

Output	Description
findings-count	Total number of findings
critical-count	Number of critical findings
high-count	Number of high findings

PR comment bot

When post-comment: 'true' (default) and running on a pull_request event, shadowaudit posts a markdown summary directly on the PR:

## 🔍 shadowaudit Scan Results

⚠️ **2 undocumented route(s) detected**

| Severity | Method | Path | File | Line | Auth |
|----------|--------|------|------|------|------|
| 🔴 CRITICAL | GET | /api/debug/reset | routes.js | 21 | ❌ |
| 🟡 HIGH | POST | /api/shadow | routes.js | 33 | ✅ |

**Summary**
- Total routes scanned: 18
- Documented: 16
- Undocumented: 2
- 🔴 Critical: 1
- 🟡 High: 1

> ⛔ **Pipeline will fail** — undocumented unauthenticated routes detected.

SARIF + GitHub Code Scanning

For native GitHub Security tab integration, use format: sarif:

- name: Run shadowaudit (SARIF)
  uses: darkmaster0345/shadow-Audit@v0.3.0
  with:
    dir: './src'
    spec: './openapi.json'
    format: 'sarif'
    fail-on: 'critical'
  continue-on-error: true

- name: Upload SARIF to GitHub
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: shadowaudit.sarif

Findings will appear in your repo's Security → Code scanning alerts tab.

Exit codes

Condition	Exit code
No findings	0
Findings below fail-on threshold	0
Findings at or above fail-on threshold	1

fail-on value	Fails when
critical (default)	Any CRITICAL finding
high	Any CRITICAL or HIGH finding
info	Any finding at all