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 | Origin | Name | Example | |--------|------|---------| | `npm` | package name | `https://api.brin.sh/npm/express` | | `pypi` | package name | `https://api.brin.sh/pypi/requests` | | `crate` | crate name | `https://api.brin.sh/crate/serde` | | `domain` | domain | `https://api.brin.sh/domain/example.com` | | `page` | domain/path | `https://api.brin.sh/page/example.com/path` | | `repo` | owner/repo | `https://api.brin.sh/repo/facebook/react` | | `mcp` | owner/repo | `https://api.brin.sh/mcp/modelcontextprotocol/servers` | | `skill` | owner/repo | `https://api.brin.sh/skill/owner/skill-name` | ### Response Format The API returns JSON with these fields: | Field | Type | Description | |-------|------|-------------| | `origin` | string | Source type (e.g. `npm`, `pypi`, `domain`) | | `name` | string | Resource name | | `score` | integer | 0–100 safety score (higher is safer) | | `confidence` | string | `low`, `medium`, or `high` | | `verdict` | string | `safe`, `caution`, `suspicious`, or `malicious` | | `tolerance` | string | Scan tolerance level | | `scanned_at` | string | ISO 8601 timestamp | | `url` | string | API endpoint URL for this resource | 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 ```bash 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 | Verdict | Recommendation | |---------|---------------| | `safe` | Safe to use. Proceed with installation. | | `caution` | Generally safe but review the flagged concerns before proceeding. | | `suspicious` | Significant risk detected. Recommend finding an alternative. | | `malicious` | Do NOT install. This resource contains known threats. | ## 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 ```bash curl -s https://api.brin.sh/domain/example.com ``` ### Scanning a specific page ```bash 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 ⚠ ```