brin
api

CLI

The brin CLI checks packages, repos, MCP servers, domains, and PRs from your terminal. One command returns a score, verdict, and threats. No auth.

a thin Rust client over the brin API. one command returns a score, verdict, and threat data. no SDK, no auth, no signup.

##install

###via npm

Bash
npm install -g brin

###via shell

Bash
curl -fsSL https://brin.sh/install.sh | sh

##usage

Bash
brin check <origin>/<identifier>

before your agent acts on any external context, one call. score, verdict, threats.

###packages

Bash
brin check npm/express
brin check npm/lodash@4.17.21
brin check pypi/requests
brin check crate/serde
JSON
{
  "origin": "npm",
  "name": "express",
  "score": 81,
  "confidence": "medium",
  "verdict": "safe",
  "tolerance": "conservative",
  "scanned_at": "2026-02-25T09:00:00Z",
  "url": "https://api.brin.sh/npm/express"
}

###repositories

Bash
brin check repo/expressjs/express

###pull requests

Bash
brin check pr/vercel/next.js/62104

###MCP servers

Bash
brin check mcp/modelcontextprotocol/servers

###agent skills

Bash
brin check skill/owner/repo

###domains and pages

Bash
brin check domain/example.com
brin check page/example.com/login

###commits

Bash
brin check commit/owner/repo@abc123def

##flags

FlagDescription
--detailsinclude sub-scores (identity, behavior, content, graph)
--webhook <url>receive tier-completion events as the deep scan progresses
--headersprint only the X-Brin-* response headers instead of the JSON body
--tolerance <level>conservative (default), lenient, or yolo — controls how the score maps to a verdict
--refreshforce a fresh scan, ignoring any cached result
--mode <mode>full to run the complete scan pipeline synchronously and return the final result
--format <format>json (default), simple, or badge

###--details

Bash
brin check npm/express --details
JSON
{
  "origin": "npm",
  "name": "express",
  "score": 81,
  "verdict": "safe",
  "sub_scores": {
    "identity": 95.0,
    "behavior": 40.0,
    "content": 100.0,
    "graph": 30.0
  }
}

###--webhook

brin runs a 3-tier analysis — the LLM tier takes 20–30s. pass a webhook URL to receive results as each tier completes rather than waiting:

Bash
brin check npm/express --webhook https://your-server.com/brin-callback

events posted to your endpoint:

EventDescription
tier1_completeIdentity + registry metadata done
tier2_completeStatic analysis done
tier3_completeLLM threat analysis done
scan_completeFinal score with graph analysis

###--headers

for fast, scriptable checks without JSON parsing:

Bash
brin check npm/express --headers
Text
X-Brin-Score: 81
X-Brin-Verdict: safe
X-Brin-Confidence: medium
X-Brin-Tolerance: conservative

###--tolerance

override the default verdict mapping. see safety tolerance for the full score-to-verdict table.

Bash
brin check npm/express --tolerance lenient
JSON
{
  "origin": "npm",
  "name": "express",
  "score": 81,
  "verdict": "safe",
  "tolerance": "lenient",
  "scanned_at": "2026-02-25T09:00:00Z",
  "url": "https://api.brin.sh/npm/express"
}

###--refresh

force a fresh scan, bypassing any cached result. useful when a package just published a new version:

Bash
brin check npm/express --refresh

###--mode

run the complete scan pipeline synchronously. without this flag, brin returns a preliminary score immediately and runs the full scan in the background. with --mode full, the request blocks until every tier finishes:

Bash
brin check npm/some-new-package --mode full

###--format

control the output format. defaults to json.

Bash
# Compact single-line output
brin check npm/express --format simple
Text
npm/express safe 81
Bash
# Markdown badge (useful in CI comments)
brin check npm/express --format badge
Text
![brin](https://api.brin.sh/npm/express?format=badge)

flags can be combined:

Bash
brin check npm/express --details --tolerance lenient --format json
brin check npm/express --refresh --mode full --webhook https://your-server.com/cb

##what we score

seven types of external context that agents consume autonomously — each with a distinct threat model and scoring pipeline.

OriginExampleThreats detected
npm / pypi / cratenpm/expressInstall-time attacks, credential harvesting, typosquatting
domain / pagedomain/example.comPrompt injection, phishing, cloaking, exfiltration via hidden content
reporepo/owner/repoAgent config injection, malicious commits, compromised dependencies
prpr/owner/repo/123Author risk, prompt injection, secret exposure, CI sabotage, suspicious diff behavior
skillskill/owner/repoDescription injection, output poisoning, instruction override
mcpmcp/owner/serverTool shadowing, schema abuse, silent capability escalation
commitcommit/owner/repo@shaPR injection, security sabotage, backdoor introduction

##how it works

before your agent acts on any external context, brin returns a score, verdict, and any detected threats. cached results come back in under 50ms — fast enough to sit in the critical path of every agent action. no queues, no cold starts.

Text
brin check npm/express
      |
      v
GET https://api.brin.sh/npm/express
      |
      v
  score · verdict · threats

if brin is unreachable, your agent keeps working as normal — zero downtime risk.

##environment variables

VariableDefaultDescription
BRIN_API_URLhttps://api.brin.shOverride the API endpoint

##local development

Bash
git clone https://github.com/superagent-ai/brin
cd brin
cargo build
cargo test