Changelog

Automatically adds package installation instructions to AGENTS.md during init, guiding agents to use brin for all package operations.

Features

• Package installation instructions — brin init now appends a "Package Installation" section to AGENTS.md, instructing agents to use brin add, brin remove, brin scan, and brin check instead of running npm/yarn/pnpm/pip directly
• Idempotent patching — Instructions are only added once, detected via a ## Package Installation marker. Running brin init multiple times won't duplicate the section
• Auto-create AGENTS.md — If no AGENTS.md exists, one is created with the installation instructions included

Technical Changes

• New INSTALL_INSTRUCTIONS_MARKER constant for idempotent detection
• add_install_instructions() and add_install_instructions_at_path() functions in agents_md.rs
• Called automatically at the end of brin init after the docs index update
• Three new tests covering: append to existing file, idempotency, and creation of new file

Secure scanning for Agent Skills from skills.sh with chain-loading detection.

Features

• Skills registry support — Scan Agent Skills (SKILL.md) from GitHub repos via brin skills check owner/repo/skill
• Chain-loading detection — Flags skills that instruct agents to install other skills or packages, a supply-chain risk unique to the agent ecosystem
• Nested dependency scanning — Automatically queues scans for skills referenced by other skills
• Skill-specific CLI output — Tailored display showing repo, trust score, and threats instead of CVEs and download counts

Technical Changes

• New SkillsAdapter implementing the RegistryAdapter trait for GitHub-hosted skills
• Initial scans now use Fireworks minimax-m2p5 for faster threat detection
• Opus-verified threats marked as Verified and affect risk level
• JSON salvage fallback for malformed LLM output
• OpenCode scans run sequentially to avoid SQLite lock contention

CLI Usage

# Scan a skill from the skills.sh registry
brin skills check owner/repo/skill
 
# Scan all skills in a repository
brin skills check owner/repo

Complete rebrand from "sus" to "brin" across the entire codebase, infrastructure, and npm package.

Changes

• New name — CLI binary, npm package, and all services renamed from sus to brin
• New domain — brin.sh / api.brin.sh
• New npm package — npm install -g brin
• Updated CLI — all commands now use brin (brin add, brin check, brin scan, etc.)
• Updated env vars — BRIN_API_URL, BRIN_INSTALL_DIR, BRIN_VERSION
• Updated config — brin.json, .brin-docs/, [brin Docs Index] markers in AGENTS.md
• Updated infrastructure — Cloud Run services redeployed as brin-api, brin-worker, brin-watcher, brin-cve
• Fixed API startup race — health server socket now releases cleanly before main server binds

Migration from sus

1. Run brin init to regenerate config (replaces sus.json with brin.json)
2. Update any SUS_API_URL env vars to BRIN_API_URL
3. Rename .sus-docs/ to .brin-docs/
4. AGENTS.md index markers update automatically on next brin add

Features

• Threat verification workflow - Added verification_status column to agentic threats with three states: pending, in_progress, verified. Only verified threats affect package risk level.
• Refined risk calculation - Risk level now based solely on CVEs and verified agentic threats. Capabilities and trust score are informational only.
• Cautious CLI wording - Updated all threat messages to use factual language ("possible threat", "patterns consistent with") instead of accusatory terms.

Technical Changes

• New migration adds verification_status column with constraint check and index
• API only returns verified threats in package responses
• calculate_risk() ignores unverified threats regardless of confidence

Why This Matters

• Reduces false positives - Human review required before flagging packages as risky
• Fair to maintainers - Packages aren't penalized by unverified automated scans
• Legal safety - Factual language avoids defamation risk

Features

• Registry Adapter Architecture - New RegistryAdapter trait defines a standard interface for registry-specific logic (metadata fetching, package downloading, trust scoring, CVE ecosystem mapping)
• Unified Package Types - Introduced ExtractedPackage and PackageMetadata types that work across all registries, eliminating duplicate code paths
• Adapter Registry - Central AdapterRegistry manages multiple adapters, making it easy to add new registries by implementing the trait
• Unified Scanner Methods - New scan_unified() and scan_tarball_unified() methods replace registry-specific scan functions

Technical Changes

• NpmAdapter - Refactored existing npm client into adapter pattern with fetch_metadata, download_package, extract_local, and compute_trust_score
• PypiAdapter - Refactored existing PyPI client into adapter pattern with support for both sdist and wheel formats
• Capabilities Module - Updated to detect language (Python vs JS/TS) from unified SourceFile types and apply appropriate analysis
• Simplified Worker Dispatch - Main worker loop now uses single code path for all registries

Architecture

RegistryAdapter (trait)
├── NpmAdapter → npm registry
├── PypiAdapter → PyPI registry
└── CratesAdapter → crates.io (future)

Benefits

• Extensibility - Add new registries by implementing RegistryAdapter trait
• Maintainability - Single unified scan path instead of duplicated npm/PyPI code
• Consistency - All registries produce the same ExtractedPackage format for downstream processing

Features

• brin uninstall command - Remove brin from your system with a single command. Supports --yes to skip confirmation and --all to also remove project files (.brin-docs/, brin.json, and brin section from AGENTS.md).
• brin upgrade command - Check for and install the latest version from GitHub releases. Supports --force to reinstall even if already on latest.
• Smart AGENTS.md cleanup - Uninstall with --all removes only the brin Docs Index section from AGENTS.md, preserving any other content.

CLI Usage

• brin uninstall - Uninstall with confirmation prompt
• brin uninstall --yes - Skip confirmation
• brin uninstall --all - Also remove project files
• brin upgrade - Upgrade if newer version available
• brin upgrade --force - Re-download even if on latest

Features

• PyPI seed support - Seed script now supports --registry pypi flag to seed top Python packages from PyPI alongside npm packages
• Python AI packages - Added curated list of 35 Python AI/ML ecosystem packages (openai, langchain, transformers, torch, etc.) for --include-ai flag
• Ecosystem-aware CVE fetching - CVE package fetching now queries the correct OSV ecosystem (npm vs PyPI) based on registry

Technical Changes

• Model switch - Agentic scan model changed from opencode/kimi-k2.5-free to anthropic/claude-sonnet-4-5 for improved reliability and faster scan times (~85s vs 5min+ timeouts)
• Rust 1.88 - Updated Docker images to Rust 1.88 for compatibility with latest dependencies

Seed CLI

• brin seed --count 1000 - Seed npm packages (default)
• brin seed --count 1000 --registry pypi - Seed PyPI packages
• brin seed --count 500 --registry pypi --include-ai - Seed PyPI with AI packages

Data Sources

• npm: https://unpkg.com/download-counts@latest/counts.json
• PyPI: https://hugovk.github.io/top-pypi-packages/top-pypi-packages-30-days.json

Features

• brin init command - Initialize brin in your project with optional AGENTS.md docs index. Settings stored in brin.json.
• AGENTS.md docs index - Replaces per-agent-folder skills with a compressed docs index in AGENTS.md, following Vercel's research showing passive context outperforms active skill retrieval (100% vs 79% pass rate).
• Improved search relevance - Search results now prioritize: exact match → starts with → contains. Within each tier, sorted by downloads.

How It Works

When enabled, brin add saves docs to .brin-docs/ and updates AGENTS.md with a compressed index.

CLI Changes

• brin init / brin init -y - Initialize project (use -y to skip prompts)
• brin add / brin remove - Now manage .brin-docs/ and update AGENTS.md index

Features

• Two-stage verification - Threats detected by the initial scan are now verified by Claude Opus 4.5 before being saved to the database. Unverified threats are discarded, reducing false positives.
• Expanded threat categories - Added 28+ new threat types covering LLM safety, secrets management, injection vulnerabilities, authentication issues, and supply chain attacks
• Improved threat parsing - Prompts now specify exact allowed threat type values, ensuring consistent snake_case output from AI models

New Threat Categories

• LLM Safety: prompt_injection, improper_output_handling, insecure_tool_usage, instruction_override
• Secrets: hardcoded_secrets
• Data Handling: weak_crypto, sensitive_data_logging, pii_violations, insecure_deserialization
• Injection: xss, sqli, command_injection, ssrf, ssti, code_injection
• Auth & Session: auth_bypass, weak_session_tokens, insecure_password_reset
• Supply Chain: malicious_install_scripts, dependency_confusion, typosquatting, obfuscated_code
• Other: path_traversal, prototype_pollution, backdoor, crypto_miner, data_exfiltration, social_engineering

Technical Changes

• Initial scan uses opencode/kimi-k2.5-free for fast threat detection
• Verification step uses anthropic/claude-opus-4-5 for high-accuracy confirmation
• Only threats confirmed by both models are persisted to the database

Features

• Auto-generate AGENTS.md - Running sus add now automatically creates an AGENTS.md file at your project root with instructions for AI agents to use sus for secure package installation
• Smart patching - If an AGENTS.md already exists, sus appends its instructions without overwriting your existing content
• Idempotent - The file is only created/patched once, detected via a ## sus Package Security marker section
• Skills folder guidance - Instructions direct agents to check .cursor/skills/, .claude/skills/, etc. for package-specific usage guidance

Bug Fixes

• Backwards compatibility fix - Resolved an issue where older scan jobs in the queue failed to deserialize due to missing registry field. Jobs now default to npm registry when the field is absent.

Features

• Registry tracking - All packages now include a registry field in API responses (npm, pypi, crates)
• Updated unique constraint - Packages are now uniquely identified by (name, version, registry) to support same package names across different registries
• Scan request registry - API scan requests now accept an optional registry parameter (defaults to npm)

API Changes

• GET /v1/packages/:name - Response now includes "registry": "npm"
• GET /v1/packages/:name/:version - Response now includes "registry": "npm"
• POST /v1/bulk - Response items now include "registry": "npm"
• POST /v1/scan - Request body accepts optional "registry" field

Coming Soon

• PyPI package scanning
• Crates.io package scanning

Features

• Package security scanning for npm, yarn, pnpm, and bun
• CVE detection with real-time vulnerability alerts
• Malware detection for known malicious packages
• Install script analysis to catch suspicious post-install hooks
• Typosquatting detection to prevent dependency confusion attacks

Agent Skills

• Automatic generation of SKILL.md files for installed packages
• AGENT.md support for project-level agent instructions
• Integration with Cursor, Claude Code, OpenCode, Gemini CLI, and Codex