How It Works
Architecture and scanning pipeline
Overview
brin is a security-first package gateway for AI agents. It answers one simple question: is this package sus?
Traditional package managers were built for human developers who can review code, recognize suspicious patterns, and make judgment calls. AI agents don't have these instincts. They trust what they're told and execute what they're given. This makes them uniquely vulnerable to a new class of attacks designed specifically to exploit autonomous code execution.
brin solves this by scanning every package before installation, detecting both traditional security threats and agentic-specific attacks, and providing a centralized docs index so agents know how to use packages correctly.
How brin Works
brin uses a distributed architecture where packages are pre-scanned in the cloud, so lookups are instant:
The Scanning Pipeline
When brin scans a package, it runs a comprehensive analysis pipeline:
- Metadata Fetch: Pull package info from the registry (maintainers, downloads, repository)
- Tarball Download: Fetch and extract the package contents
- Parallel Analysis: Run all scanners concurrently for speed
- Risk Calculation: Combine all signals into a final risk assessment
- Store & Serve: Cache results for instant lookups
Capability Extraction
brin performs static analysis to detect what a package can do:
| Capability | What It Detects |
|---|---|
| Network | HTTP/HTTPS requests, WebSocket connections, TCP/UDP sockets, domains accessed, protocols used |
| Filesystem | File read/write operations, paths accessed with permissions (read, write, or both) |
| Process | Child process spawning via exec/spawn/fork, specific commands extracted (npm, git, curl, etc.) |
| Environment | Environment variables accessed via process.env |
| Native | Native modules, binding.gyp presence, N-API bindings (node-addon-api, napi-rs, nan) |
This information helps agents understand what permissions a package needs and whether its capabilities match its stated purpose.
$ brin check axios
🔍 checking axios@1.6.0...
✅ not sus
capabilities:
├─ network: http, https (api calls)
├─ filesystem: none
├─ process: none
└─ environment: HTTP_PROXY, HTTPS_PROXYTrust Score
Every package gets a trust score from 0-100 based on multiple signals:
| Signal | Impact |
|---|---|
| 5+ maintainers | +20 points |
| Linked repository | +10 points |
| Has description | +5 points |
| High download count | +15 points |
| Package age (1+ year) | +10 points |
| Verified publisher | +20 points |
| Base score | 50 points |
A higher trust score doesn't mean a package is safe. It means the package has more signals of legitimacy. Even high-trust packages can have CVEs or be compromised.
Scan Priority
brin continuously monitors package registries and prioritizes scans:
| Priority | Trigger |
|---|---|
| Immediate | Known malicious patterns detected |
| High | User-requested scan via CLI or API |
| Medium | New package discovered by watcher |
| Low | Background re-scan of existing packages |
This ensures that when you run brin add, the package has likely already been scanned and results are instant.
Summary
brin protects AI agents by:
- Scanning before installing - Unlike
npm audit, brin blocks threats before they touch your system - Detecting agentic threats - Prompt injection, repo poisoning, and other attacks targeting AI
- Extracting capabilities - Understanding what packages can actually do
- Maintaining a docs index - Centralized documentation in
AGENTS.mdfor instant agent access - Calculating trust scores - Multiple signals combined into actionable risk levels
The result: AI agents can safely install packages without falling victim to attacks designed to exploit their autonomous nature.
Learn the commands and docs index for more details.
On this page