GitHub code scanning

WebMCP contract audit in your CI.

One workflow file per page. Each run scans the page with this scanner, uploads the findings to Security › Code scanning, writes the full report to the job summary and fails the job by the rules you set here.

# WebMCP contract audit for one public page, from https://webmcp.corsen.ai/ci/
# Save as .github/workflows/webmcp-audit.yml. On each run the WebMCP Scanner loads the page once
# (no tool is called, no form is submitted), the findings go to Security > Code scanning, the full
# report goes to the job summary, and the job fails according to the settings below.
# The scanner refuses private networks, logins and credentials in URLs: scan a public page or a
# public preview deployment. Reports expire one hour after the scan; the artifact keeps a copy.
name: WebMCP contract audit

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  # Once a day (UTC), on the default branch. A script that is not in this repository can change a
  # tool without any commit: only a scheduled run sees it. In a public repository GitHub turns
  # scheduled workflows off after 60 days without activity.
  schedule:
    - cron: '8 23 * * *'

permissions:
  contents: read

jobs:
  webmcp-audit:
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      contents: read
      security-events: write   # upload the findings to code scanning
      actions: read            # needed by the upload in private repositories
    env:
      # The public page to scan.
      WEBMCP_PAGE: 'https://www.example.com/'
      # Fail on a critical finding (critical), on a high or critical finding (high), or never.
      WEBMCP_FAIL_ON: 'critical'
      # Fail below this provisional score, from 0 to 100; 0 disables the check.
      WEBMCP_MIN_SCORE: '50'
      # Fail when no WebMCP tool is observed at load: true or false.
      WEBMCP_FAIL_NOT_EXPOSED: 'false'
      # No report (quota, capacity, browser challenge, error page): warn or fail.
      WEBMCP_ON_UNAVAILABLE: 'warn'
      # Optional: a contracts file committed in this repository, for example
      # .github/webmcp-contracts.json (take it from this workflow's artifact). When set, each run
      # compares the page's contract fingerprints with it. Empty disables the comparison.
      WEBMCP_CONTRACT_LOCK: ''
      # A contract that differs from the committed file, or a tool that is not in it: fail or warn.
      WEBMCP_ON_DRIFT: 'fail'
      WEBMCP_API: https://webmcp.corsen.ai
    steps:
      - name: Scan the page
        id: scan
        shell: bash
        run: |
          case "$WEBMCP_PAGE" in http://*|https://*) ;; *) echo "::error title=WebMCP contract audit::WEBMCP_PAGE must be a public http(s) address."; exit 1 ;; esac
          # Results are anchored to this workflow file, which exists in the repository.
          anchor="${GITHUB_WORKFLOW_REF#*/*/}"
          anchor="${anchor%%@*}"
          body=$(jq -cn --arg url "$WEBMCP_PAGE" '{url: $url, fresh: true}')
          scan() {
            curl -sS -o scan.json -D scan.headers -w '%{http_code}' --max-time 180 \
              -H 'content-type: application/json' --data "$body" "$WEBMCP_API/api/scan" || true
          }
          code=$(scan)
          if [ "$code" = 429 ]; then
            wait=$(tr -d '\r' < scan.headers | awk 'tolower($1) == "retry-after:" { print $2; exit }')
            if [[ "$wait" =~ ^[0-9]+$ ]] && [ "$wait" -le 60 ]; then
              sleep "$wait"
              code=$(scan)
            fi
          fi
          if [ "$code" = 400 ]; then
            echo "status=refused" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          id=$(jq -r '.id // empty' scan.json 2>/dev/null || true)
          if [ "$code" != 200 ] || ! [[ "$id" =~ ^[a-z0-9]{8,32}$ ]]; then
            { echo "status=unavailable"; echo "http=${code:-000}"; } >> "$GITHUB_OUTPUT"
            exit 0
          fi
          report="$WEBMCP_API/api/report/$id"
          curl -sS --fail --max-time 60 -o webmcp-report.json "$report"
          curl -sS --fail --max-time 60 -o webmcp.sarif -G --data-urlencode "anchor=$anchor" "$report/export.github.sarif.json"
          curl -sS --fail --max-time 60 -o webmcp-report.md "$report/export.md"
          curl -sS --fail --max-time 60 -o webmcp-badge.svg "$report/export.badge.svg"
          curl -sS --fail --max-time 60 -o webmcp-contracts.json "$report/export.contracts.json"
          cat webmcp-report.md >> "$GITHUB_STEP_SUMMARY"
          status=$(jq -r '.status' webmcp-report.json)
          case "$status" in observed|not-exposed) ;; *) status=unavailable ;; esac
          { echo "status=$status"; echo "sarif=webmcp.sarif"; echo "report=true"; } >> "$GITHUB_OUTPUT"

      # The committed contracts file is read at the commit under test, so a pull request that
      # updates it is compared with its own version. Tool names are checked before they are printed.
      - name: Compare contracts with the committed file
        id: contracts
        if: steps.scan.outputs.report == 'true' && env.WEBMCP_CONTRACT_LOCK != ''
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          case "$WEBMCP_CONTRACT_LOCK" in
            /*|*..*|*[!A-Za-z0-9._/-]*) echo "::error title=WebMCP contract audit::WEBMCP_CONTRACT_LOCK must be a file path inside the repository."; exit 1 ;;
          esac
          code=$(curl -sS -o webmcp-contracts.lock.json -w '%{http_code}' --max-time 60 \
            -H "authorization: Bearer $GH_TOKEN" -H 'accept: application/vnd.github.raw+json' \
            "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/contents/$WEBMCP_CONTRACT_LOCK?ref=$GITHUB_SHA" || true)
          if [ "$code" = 404 ]; then
            echo "state=absent" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ "$code" != 200 ] || ! jq -e '.format == "webmcp-contracts/1" and (.tools | type == "array")' webmcp-contracts.lock.json > /dev/null 2>&1; then
            echo "state=unreadable" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          jq -n --slurpfile base webmcp-contracts.lock.json --slurpfile now webmcp-contracts.json '
            def entries: reduce (.[0].tools[]? | select(type == "object" and (.name | type == "string" and test("^[A-Za-z0-9_.-]{1,128}$"))
                and (.contract | type == "string" and test("^[0-9a-f]{64}$")))) as $t ({}; if has($t.name) then . else .[$t.name] = $t end);
            ($base | entries) as $a | ($now | entries) as $b
            | { added: [$b | keys[] | select($a[.] == null)],
                missing: [$a | keys[] | select($b[.] == null)],
                changed: [$b | keys[] | select($a[.] != null and $a[.].contract != $b[.].contract) | . as $n
                  | { name: $n, parts: [("description", "schema", "annotations") | select(($a[$n][.] // "") != "" and ($b[$n][.] // "") != "" and $a[$n][.] != $b[$n][.])] }] }
          ' > webmcp-contract-drift.json
          added=$(jq '.added | length' webmcp-contract-drift.json)
          changed=$(jq '.changed | length' webmcp-contract-drift.json)
          missing=$(jq '.missing | length' webmcp-contract-drift.json)
          { echo "state=compared"; echo "added=$added"; echo "changed=$changed"; } >> "$GITHUB_OUTPUT"
          {
            echo
            echo "## Contracts compared with $WEBMCP_CONTRACT_LOCK"
            echo
            echo "Changed: $changed, not in the file: $added, in the file but not observed: $missing."
            echo
            jq -r '.changed[] | "- changed: `\(.name)`" + (if (.parts | length) > 0 then " (" + (.parts | join(", ")) + ")" else "" end)' webmcp-contract-drift.json
            jq -r '.added[] | "- not in the file: `\(.)`"' webmcp-contract-drift.json
            jq -r '.missing[] | "- not observed: `\(.)`"' webmcp-contract-drift.json
          } >> "$GITHUB_STEP_SUMMARY"

      # Pull requests from forks get a read-only token and cannot upload.
      - name: Upload the findings to code scanning
        if: always() && steps.scan.outputs.sarif == 'webmcp.sarif' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
        uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
        with:
          sarif_file: webmcp.sarif

      - name: Keep the report and the badge
        if: always() && steps.scan.outputs.report == 'true'
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: webmcp-audit
          path: |
            webmcp-report.json
            webmcp-report.md
            webmcp-badge.svg
            webmcp.sarif
            webmcp-contracts.json
          retention-days: 30

      - name: Apply the policy
        if: always() && steps.scan.outputs.status != ''
        shell: bash
        env:
          STATUS: ${{ steps.scan.outputs.status }}
          HTTP: ${{ steps.scan.outputs.http }}
          CONTRACTS: ${{ steps.contracts.outputs.state }}
          CONTRACTS_CHANGED: ${{ steps.contracts.outputs.changed }}
          CONTRACTS_ADDED: ${{ steps.contracts.outputs.added }}
        run: |
          failed=0
          fail() { echo "::error title=WebMCP contract audit::$1"; failed=1; }
          if ! [[ "$WEBMCP_MIN_SCORE" =~ ^[0-9]+$ ]] || [ "$WEBMCP_MIN_SCORE" -gt 100 ]; then
            fail "WEBMCP_MIN_SCORE must be an integer from 0 to 100."
            exit 1
          fi
          case "$STATUS" in
            refused)
              fail "The scanner refused the address: private networks, logins and credentials in URLs are not scanned." ;;
            unavailable)
              if [ "$WEBMCP_ON_UNAVAILABLE" = fail ]; then
                fail "No report (HTTP ${HTTP:-none}): quota, capacity, a browser challenge or an error page."
              else
                echo "::warning title=WebMCP contract audit::No report (HTTP ${HTTP:-none}). Nothing was uploaded, so earlier alerts stay open."
              fi ;;
            not-exposed)
              if [ "$WEBMCP_FAIL_NOT_EXPOSED" = true ]; then
                fail "No WebMCP tool was observed at load."
              else
                echo "No WebMCP tool observed at load: no score."
              fi ;;
            observed)
              critical=$(jq -r '.bySeverity.critical // 0' webmcp-report.json)
              high=$(jq -r '.bySeverity.high // 0' webmcp-report.json)
              score=$(jq -r '.score' webmcp-report.json)
              grade=$(jq -r '.grade' webmcp-report.json)
              for n in "$critical" "$high" "$score"; do
                [[ "$n" =~ ^[0-9]+$ ]] || { fail "Unexpected report content."; exit 1; }
              done
              [[ "$grade" =~ ^[A-F]$ ]] || grade='?'
              if [ "$WEBMCP_FAIL_ON" != never ] && [ "$critical" -gt 0 ]; then fail "$critical critical finding(s): the score is capped at 49/F."; fi
              if [ "$WEBMCP_FAIL_ON" = high ] && [ "$high" -gt 0 ]; then fail "$high high finding(s)."; fi
              if [ "$WEBMCP_MIN_SCORE" -gt 0 ] && [ "$score" -lt "$WEBMCP_MIN_SCORE" ]; then fail "Provisional score $score/100 ($grade) is below $WEBMCP_MIN_SCORE."; fi
              echo "Provisional score $score/100 ($grade): $critical critical, $high high. Not a certification." ;;
            *)
              fail "Unknown scan status." ;;
          esac
          case "$CONTRACTS" in
            compared)
              [[ "$CONTRACTS_CHANGED" =~ ^[0-9]+$ ]] && [[ "$CONTRACTS_ADDED" =~ ^[0-9]+$ ]] || { fail "Unexpected contract comparison."; exit 1; }
              if [ $((CONTRACTS_CHANGED + CONTRACTS_ADDED)) -gt 0 ]; then
                message="$CONTRACTS_CHANGED contract(s) differ from the committed file and $CONTRACTS_ADDED tool(s) are not in it. Review them, then commit webmcp-contracts.json from the artifact to accept."
                if [ "$WEBMCP_ON_DRIFT" = warn ]; then echo "::warning title=WebMCP contract audit::$message"; else fail "$message"; fi
              else
                echo "Contracts match the committed file."
              fi ;;
            absent)
              echo "::notice title=WebMCP contract audit::No contracts file at the configured path yet. Commit webmcp-contracts.json from the artifact to start comparing." ;;
            unreadable)
              echo "::warning title=WebMCP contract audit::The committed contracts file could not be read or is not a contracts file; nothing was compared." ;;
          esac
          exit "$failed"

The workflow is built in your browser; nothing you type here is sent to us.

Use it

  1. Save the file as .github/workflows/webmcp-audit.yml and commit it. It runs on pushes to main, on pull requests, on demand and, unless you untick it, once a day on the default branch.
  2. Open Security › Code scanning: each finding is an alert with its rule, severity, tool and evidence. A finding keeps the same alert across runs; each scanned page is its own analysis, so several workflows never close each other's alerts.
  3. The job summary shows the full report. The webmcp-audit artifact keeps the JSON and Markdown report, the SARIF, the badge and the contract fingerprints for 30 days.

What fails the job

Catch a contract that changed after review

A tool description is what an agent reads to decide when to call the tool. A script you do not control, such as a tag manager, an A/B test or a compromised dependency, can register a tool or rewrite a description after your review. To be told when that happens:

  1. Run the workflow once and take webmcp-contracts.json from the webmcp-audit artifact, or download it from a report on this site. It lists a SHA-256 fingerprint for each observed tool: the whole contract, and its description, input schema and annotations separately.
  2. Review it and commit it, for example as .github/webmcp-contracts.json, then enter that path above.
  3. Each run compares the page with the committed file. A tool whose contract differs, or a tool that is not in the file, fails the job (or warns) and the job summary names the tool and the part that changed. Keep the daily run: a script outside your repository changes a tool without any commit, so only a scheduled run sees it, and GitHub then notifies you of the failed run. A tool in the file that is not observed is only listed: it may register later or behind a login.
  4. To accept a change, commit the new webmcp-contracts.json: the approval is a reviewed commit in your repository.

The committed file is read with the workflow's own read-only token at the commit under test; nothing else in the repository is read. Fingerprints compare between scans of this scanner only: the extension observes contracts in another form.

How results appear in GitHub

The scanner reports runtime locations: tool, origin, frame. GitHub displays an alert only on a file of the repository, so each result points at line 1 of this workflow file and keeps its runtime location in the message. The SARIF comes from GET /api/report/{id}/export.github.sarif.json (JSON API). No checkout is needed: GitHub reads the workflow file from the repository. Actions are pinned to full commit SHAs.

The badge

WebMCP contract: Grade A · audited by Corsen AI · 2026-11-21. Provisional score 92/100, ruleset 2026-11-10.2; not a security certification.WebMCP contractGrade A · audited by Corsen AI · 2026-11-21

Each report has a badge with its grade, the words “audited by Corsen AI” and the scan date; it is not a certification. Hosted badge links expire with the report; the file in the artifact is yours to publish, for example in your README.

Limits