GitHub Action

The middleBrick GitHub Action runs API security scans as part of your CI/CD pipeline. Set a score threshold to fail builds when security regresses.

Requires Pro plan or above.

Quick Start

Add this to .github/workflows/security.yml:

name: API Security Scan
on: [pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: middlebrick/scan-action@v1
        with:
          url: https://api.example.com/v1/users
          api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
          fail-under: 75

This scans your API on every pull request and fails the check if the security score drops below 75.

Inputs

Input	Required	Default	Description
url	Yes	—	API endpoint to scan
api-key	Yes	—	middleBrick API key (use GitHub Secrets)
spec-url	No	—	OpenAPI/Swagger spec URL for deeper analysis
context	No	—	API context: financial, medical, public, internal
fail-under	No	0	Minimum score threshold — the step fails if the score is below this value

Choosing a fail-under threshold

• 75: good starting point. Catches critical and high severity issues while allowing minor findings.
• 85: strict. Requires a well-secured API with no significant vulnerabilities.
• 60: lenient. Only fails on serious security regressions. Good for legacy APIs being improved incrementally.
• 0: never fails (default). The scan runs and reports results without blocking the PR.

Start lenient and tighten over time as your team fixes existing issues.

Outputs

Output	Description
score	Overall security score (0–100)
grade	Letter grade (A–F)
findings-count	Total number of findings
report-url	Link to the full scan report in your dashboard

Use outputs in subsequent steps:

- uses: middlebrick/scan-action@v1
  id: scan
  with:
    url: https://api.example.com/v1/users
    api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}

- name: Log results
  run: |
    echo "Score: ${{ steps.scan.outputs.score }}"
    echo "Grade: ${{ steps.scan.outputs.grade }}"
    echo "Findings: ${{ steps.scan.outputs.findings-count }}"
    echo "Report: ${{ steps.scan.outputs.report-url }}"

Examples

PR check with results summary

Scan on every PR and always post the results, even if the check passes:

name: API Security
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: middlebrick/scan-action@v1
        id: scan
        with:
          url: https://staging-api.example.com/v1/users
          api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
          fail-under: 75

      - name: Post results
        if: always()
        run: |
          echo "### API Security Scan" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Score:** ${{ steps.scan.outputs.score }}/100 (${{ steps.scan.outputs.grade }})" >> $GITHUB_STEP_SUMMARY
          echo "**Findings:** ${{ steps.scan.outputs.findings-count }}" >> $GITHUB_STEP_SUMMARY
          echo "**Report:** ${{ steps.scan.outputs.report-url }}" >> $GITHUB_STEP_SUMMARY

This writes the scan results to the GitHub Actions job summary, visible directly in the PR checks.

Post-deploy scan with OpenAPI spec

Scan after deploying to production to verify the live API:

name: Post-deploy Security Scan
on:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: middlebrick/scan-action@v1
        with:
          url: https://api.example.com/v1/users
          api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
          spec-url: https://api.example.com/openapi.json
          context: financial
          fail-under: 80

Scheduled weekly scan

Run a security scan on a schedule, independent of deploys:

name: Weekly Security Scan
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am UTC

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: middlebrick/scan-action@v1
        id: scan
        with:
          url: https://api.example.com/v1/users
          api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
          fail-under: 70

      - name: Notify on failure
        if: failure()
        run: |
          echo "Security score dropped to ${{ steps.scan.outputs.score }}"
          # Add Slack/email notification here

Multiple endpoints (matrix strategy)

Scan several endpoints in parallel:

name: API Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        endpoint:
          - url: https://api.example.com/v1/users
            context: public
          - url: https://api.example.com/v1/payments
            context: financial
          - url: https://api.example.com/v1/chat
            context: public
    steps:
      - uses: middlebrick/scan-action@v1
        with:
          url: ${{ matrix.endpoint.url }}
          api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
          context: ${{ matrix.endpoint.context }}
          fail-under: 75

Staging environment with dynamic URL

Use your staging URL from a previous deploy step:

- name: Deploy to staging
  id: deploy
  run: echo "url=https://staging-${{ github.sha }}.example.com" >> $GITHUB_OUTPUT

- uses: middlebrick/scan-action@v1
  with:
    url: ${{ steps.deploy.outputs.url }}/v1/users
    api-key: ${{ secrets.MIDDLEBRICK_API_KEY }}
    fail-under: 75

API Key Setup

1. Generate an API key from your dashboard
2. In your repository: Settings → Secrets and variables → Actions → New repository secret
3. Name: MIDDLEBRICK_API_KEY, Value: your API key
4. Reference it in workflows as ${{ secrets.MIDDLEBRICK_API_KEY }}

Organization-wide key

If you have multiple repos, add the secret at the Organization level (Settings → Secrets → Actions) to avoid duplicating the key in every repository.

Troubleshooting

Problem	Cause	Fix
”Unauthorized” error	Invalid or missing API key	Verify the secret name matches MIDDLEBRICK_API_KEY
Scan timeout	Endpoint unreachable from GitHub runners	Ensure the URL is publicly accessible (not behind VPN)
Score is 0	Endpoint returned an error	Check that the URL returns a valid response
Action not found	Wrong action reference	Use middlebrick/scan-action@v1 (exact name)