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
- Save the file as
.github/workflows/webmcp-audit.ymland commit it. It runs on pushes tomain, on pull requests, on demand and, unless you untick it, once a day on the default branch. - 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.
- The job summary shows the full report. The
webmcp-auditartifact keeps the JSON and Markdown report, the SARIF, the badge and the contract fingerprints for 30 days.
What fails the job
- A critical finding, by default: the scanner caps such a score at 49/F. Choose “a high or critical finding” for a stricter gate.
- A score below the minimum: a score of 49 or less can also come from several non-critical findings, so this check is separate. 0 disables it.
- No WebMCP tool observed, only if you tick the box: a page without tools has no score.
- A contract that differs from your committed file, when you set one: see below.
- No report (quota, capacity, browser challenge, error page): a warning by default. Nothing is uploaded then, so earlier alerts stay open. An address the scanner refuses (private network, credentials) always fails.
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:
- Run the workflow once and take
webmcp-contracts.jsonfrom thewebmcp-auditartifact, 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. - Review it and commit it, for example as
.github/webmcp-contracts.json, then enter that path above. - 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.
- 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
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
- Public pages only: the scanner refuses private networks, logins and credentials in URLs. To check a pull request, point
WEBMCP_PAGEat a public preview deployment; otherwise the run scans the live page. - One page: initial load, then one passive pointer movement and scroll; no click, typing or tool invocation. Tools behind a login, after a click or typing, or inside frames are not inventoried.
- API quotas per runner network: 2 fresh scans per minute and 10 per day, and one scan per target site per minute.
- Code scanning on private repositories requires GitHub Code Security. Pull requests from forks get a read-only token: the workflow skips the upload for them.
- The daily run uses the workflow file of the default branch, at a fixed minute chosen from your page's host name. In a public repository GitHub turns scheduled workflows off after 60 days without activity; any push turns them on again.