How it works, and why
An agent that needs a tool finds a package name and has to decide: will this start, what will it want from me, and what will it do on my machine? Today the only way to know is to run a stranger's code and see.
The idea
Bragproof runs it first, somewhere that does not matter, and publishes what happened. Each server gets a run report: not a review, not a score, and nothing the maker wrote about themselves. Only what a neutral machine saw.
If you are choosing a tool
See whether it starts with no setup, which settings it asks for, what it contacts, and what its tool descriptions will say to your agent, before any of its code runs near you.
If you made one
Type its name. It is listed where agents search, with a report of whether it starts and what it needs, without a launch post or a following. Get listed
What a report records
- Whether it starts with no arguments, no environment and no input, and how long that took.
- What it said when it did not, and the settings that output names.
- Every tool and description it listed, with a hash so a later change is noticed.
- Wording in those descriptions that talks about the user, other tools or private files, uses hidden characters, or gives orders, quoted as written.
- Addresses it looked up, recorded outside its sandbox where it cannot hide them.
- Files it wrote.
- Whether a tool answers when called with nothing: up to five tools that take no input and look read-only are tried, and what the server first contacts during those calls is recorded apart.
You do not have to trust this site
A report is made by a public job on a machine GitHub hosts, running this project's open workflow. When it finishes, GitHub signs a token that names the workflow, the commit it ran from, and the hash of the report's exact text. The site stores the text and the token and serves both.
- Fetch
https://bragproof.smaverk.com/v1/reports/<package>?raw=1. You get the report text and the token. - Hash the text with SHA-256. The token's
audmust bebragproof-report:followed by that hash. - Check the token's signature against GitHub's public keys, and that it names
itsHaddad/bragproof/.github/workflows/report.yml@refs/heads/mainon a GitHub-hosted machine. - Read that workflow at the commit the token names, and the run's public log.
Or let the open-source tool do all four: bragproof check <package> from the repository. What you end up trusting is GitHub and code you can read. GitHub retires its signing keys after a while; an old token then no longer checks, and the report should be run again.
What a report does not tell you
- What most tools do when called. Only a few tools that take no input and look read-only are called. A server that starts quietly can still do anything once used.
- That it is safe. The wording rules are simple patterns. A clean report is not a security review.
- That it is good. Starting is the lowest bar there is.
- Anything about tomorrow. A report is about one version on one day. New versions need new reports.
- How it behaves elsewhere. One machine: Linux x64, Node 24, install scripts not run, and a sandbox that holds Node and little else: a server that needs another program (Python, Java, tar, a browser) will not find it there.
"Needs setup" is not a fault. Many good servers need a key. It is there so you know before you try.
Proven calls
A second, stronger kind of evidence, with three levels
Separately from reports, a maker can prove that specific calls return specific results. Those proven calls carry a receipt at one of three levels.
| Level | What vouches for the run | What you are trusting |
|---|---|---|
| Attested | A confidential machine (for example Intel TDX): the hardware signs what ran. | The chip maker, the cloud host, and that nobody had physical access. |
| Witnessed | GitHub: it signs that this project's check workflow ran on its machine. | GitHub. No hardware evidence underneath. |
| Self-reported | Nothing. | Whoever ran it. Not shown unless you ask. |
Proven N times by N accounts counts passing runs and the different GitHub accounts or cloud projects that asked for them, the maker's own included. Accounts are cheap to make: read two or more as "someone besides the maker checked", not as a vote.