superagent-ai/brin/brin-check

brin Security Check

Scan any external resource for security threats using the brin API before installing, visiting, or using it.

Usage

When the user asks to check or scan a resource, when you need to verify the safety of an external dependency, or when you encounter unfamiliar URLs or domains:

1. Identify the resource type and name
2. Call the appropriate brin API endpoint
3. Report the verdict, score, and any detected threats

API Reference

The brin API requires no authentication. Make a GET request to:

https://api.brin.sh/<origin>/<name>

Supported Origins

Response Format

The API returns JSON with these fields:

Response headers also provide quick access: x-brin-verdict, x-brin-score, and x-brin-confidence.

Step-by-Step

1. Determine the origin and identifier

Parse the user's request to determine what type of resource they want to check. Examples:

• "Check if lodash is safe" → npm/lodash
• "Scan the requests Python package" → pypi/requests
• "Is github.com/owner/repo safe?" → repo/owner/repo
• "Check this MCP server: owner/server" → mcp/owner/server
• "Is example.com safe?" → domain/example.com
• "Check this URL: https://example.com/path" → page/example.com/path
• "Scan the domains from my web search results" → domain/<each-domain>

2. Query the API

curl -s https://api.brin.sh/npm/lodash
curl -s https://api.brin.sh/domain/example.com
curl -s https://api.brin.sh/page/example.com/some/path

3. Interpret the results

Report the following to the user:

• Verdict: The overall safety assessment
• Score: The numerical score (0–100)
• Confidence: How confident brin is in the result

4. Recommend action

Example Output

When reporting results, format them clearly:

brin scan: express (npm)
━━━━━━━━━━━━━━━━━━━━━━━━
Score:      84/100
Verdict:    safe ✓
Confidence: medium

For a caution result:

brin scan: requests (pypi)
━━━━━━━━━━━━━━━━━━━━━━━━
Score:      65/100
Verdict:    caution ⚠
Confidence: medium

For a malicious resource:

brin scan: malicious-pkg (npm)
━━━━━━━━━━━━━━━━━━━━━━━━
Score:      12/100
Verdict:    malicious ✗
Confidence: high
 
⚠ Do NOT install this package.

Batch Scanning

When multiple packages are being installed, scan each one individually and provide a summary table:

brin scan summary
━━━━━━━━━━━━━━━━━━━━━━━━
Package     Score  Verdict
express     84     safe ✓
lodash      88     safe ✓
requests    65     caution ⚠

Web Search and URL Scanning

When web search results return URLs or the user provides links, scan the domains before visiting:

Scanning domains from web search

curl -s https://api.brin.sh/domain/example.com

Scanning a specific page

curl -s https://api.brin.sh/page/example.com/docs/guide

Example output for a domain scan

brin scan: example.com (domain)
━━━━━━━━━━━━━━━━━━━━━━━━
Score:      90/100
Verdict:    safe ✓
Confidence: high

For a dangerous domain:

brin scan: malicious-site.xyz (domain)
━━━━━━━━━━━━━━━━━━━━━━━━
Score:      8/100
Verdict:    malicious ✗
Confidence: high
 
⚠ Do NOT visit this domain.

When to scan URLs

• After a web search returns results with unfamiliar domains
• Before following links from external documentation or READMEs
• When a user asks you to visit or read content from a URL
• Before scraping or extracting data from any web page
• When evaluating third-party API documentation links

Batch URL scanning

For multiple URLs from search results, scan each domain and provide a summary:

brin domain scan summary
━━━━━━━━━━━━━━━━━━━━━━━━
Domain              Score  Verdict
docs.example.com    95     safe ✓
blog.trusted.io     88     safe ✓
free-tools.xyz      15     suspicious ⚠