Trust badges
Display your agent's trust score and trust level as a badge in your README.
What trust badges show
Trust badges are dynamic shields.io-style images that display two pieces of information:
- Trust score (0-100): a composite measure of your agent's security posture
- Trust level (discovered, scanned, claimed, verified, certified or blocked): the registry returns
blockedfor a package it has blocked, such as one whose scan failed
The badge color reflects the score range:
| Score | Color | Meaning |
|---|---|---|
80-100 | Green | Strong security posture. Scans pass. |
60-79 | Yellow-green | Moderate posture. Some findings remain. |
40-59 | Yellow | Baseline posture. Scans run but significant findings. |
0-39 | Red | Minimal data. Package discovered but not yet scanned. |
Add a badge manually
Add the following Markdown to your README. Replace PACKAGE_NAME with your package name (URL-encoded if it contains slashes).
[](https://opena2a.org/trust/PACKAGE_NAME)
Automate with GitHub Actions
Use the opena2a-org/trust-badge-action GitHub Action to automatically update your trust badge on a weekly schedule. The action looks the package up in the OpenA2A Registry and adds the trust badge to your README, or updates the badge that is there when its Markdown differs.
name: Trust Badge
on:
schedule:
- cron: '0 0 * * 1' # Every Monday at midnight UTC
workflow_dispatch: # Manual trigger
jobs:
badge:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- uses: opena2a-org/trust-badge-action@v1
with:
package-name: ${{ github.event.repository.name }}
registry-url: https://api.oa2a.org
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}The registry-url line is required with v1: that tag's default registry host, registry.opena2a.org, has no DNS record, so a step without the line fails with Failed to connect to registry and writes no badge.
The action commits to the branch the workflow ran on when the badge changes, using the token the step sets in GITHUB_TOKEN: the default branch for a scheduled run, or the branch you chose for a manual run. If you use branch protection, configure the action to open a pull request into that branch instead by adding create-pr: true to the action inputs and granting the job pull-requests: write.
The v1 tag the workflow above pins does not have this behavior yet. It is the v1.1.0 release (commit 216064e), which writes the badge commit to the default branch and opens the create-pr pull request into the default branch, whichever branch the workflow ran on. Until v1 moves to a newer release, pin a commit of the action's main branch from 8d1608f onward in place of v1, as in uses: opena2a-org/trust-badge-action@<commit-sha>. The action's v1 tag page describes pinning a commit of main and lists other behavior the tag does not have yet.
Badge placement
Place the badge at the top of your README alongside other status badges (CI, coverage, npm version). Trust badges work in any Markdown renderer that supports image URLs: GitHub, GitLab, Bitbucket, npm package pages, and documentation sites.