Loading repository data…
Loading repository data…
GiuseppeScottoLavina / repository
🛡️ The AI-Native NPM Registry — Security-first local registry that scans every package for prompt injections, malicious code, and supply chain attacks before AI agents can install them.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
AI coding agents are transforming software development. Tools like Cursor, Windsurf, and Claude Code can write, test, and publish entire packages autonomously. But there's a critical gap: when AI agents install dependencies, they blindly trust everything from npmjs.org — including packages that contain prompt injection attacks, malicious install scripts, or supply chain exploits designed specifically to compromise AI workflows.
AgentRegistry was born from a simple question: what if your local registry could protect your AI agents the same way a firewall protects your network?
AgentRegistry is a private, local NPM registry that sits between your AI agents and the public npm ecosystem. Every package — whether published locally or fetched from upstream — is security-scanned in real time. Suspicious packages are quarantined and require human approval before any agent can use them. This creates a human-in-the-loop security boundary that prevents supply chain attacks without slowing down your workflow.
llms.txt, OpenAPI spec, structured error responses with AI directives| Pain Point | Traditional Registries | AgentRegistry |
|---|---|---|
| Dependencies | 60+ packages to install | 2 dependencies (tar, acorn) |
| Setup Time | Minutes of configuration | One command: bun run start |
| AI Integration | None | Native MCP, llms.txt, OpenAPI |
| Security |
| Afterthought (plugins) |
| Quarantine-first architecture |
| Response Time | 50-200ms | ~1ms (memory-first cache) |
| Admin UI | Static page refreshes | Real-time WebSocket dashboard |
⚠️ Alpha Software (0.1.0) — AgentRegistry is under active development. APIs may change. Contributions and feedback welcome!
# Start the server
bun run start
# Or with hot-reload for development
bun run dev
# Custom port
bun run server.ts --port 4874
AgentRegistry can run as a background daemon with automatic restart on crash.
# Start daemon in background
bun run cli.ts start
# Check status
bun run cli.ts status
# View logs
bun run cli.ts logs
# Stop daemon
bun run cli.ts stop
# Restart
bun run cli.ts restart
# Install as system service (auto-start on boot)
npm run install-service
# Remove service
npm run uninstall-service
| File | Location |
|---|---|
| PID file | ~/.agentregistry/agentregistry.pid |
| Logs | ~/.agentregistry/logs/agentregistry.log |
| launchd plist | ~/Library/LaunchAgents/com.agentregistry.daemon.plist |
Point your npm/bun client to the local registry:
# NPM
npm config set registry http://localhost:4873
# Bun
echo 'registry = "http://localhost:4873"' >> bunfig.toml
# Per-project (.npmrc)
echo "registry=http://localhost:4873" > .npmrc
# Standard npm publish
npm publish
# Or with bun
bun publish
npm install my-package
bun add my-package
npm unpublish my-package@1.0.0
Create a ready-to-publish TypeScript package:
agentregistry create my-pkg
Bump version and publish in one command:
agentregistry release patch
# or minor, major
Check for environment issues (permissions, connectivity):
agentregistry doctor
Visualize your local ecosystem at http://localhost:4873/-/admin (Graph tab).
Create a full snapshot (database + storage):
agentregistry backup
agentregistry restore <file.zip>
| Method | Endpoint | Description |
|---|---|---|
GET | / | List all packages |
GET | /-/ping | Health check |
GET | /{package} | Get package metadata |
GET | /{package}/{version} | Get specific version |
GET | /{package}/-/{tarball}.tgz | Download tarball |
PUT | /{package} | Publish package |
DELETE | /{package}/-/{tarball}/{rev} | Unpublish version |
⚠️ Authentication Required: All admin API endpoints require
X-Admin-Tokenheader. Token is auto-injected in the admin panel UI.
| Method | Endpoint | Description |
|---|---|---|
GET | /-/admin | Admin panel UI (no auth required) |
GET | /-/admin/stats | Server stats (memory, cache, etc.) |
GET | /-/admin/quarantine | List quarantined packages |
DELETE | /-/admin/quarantine | Clear all quarantine |
DELETE | /-/admin/quarantine/{file} | Delete specific file |
POST | /-/admin/quarantine/{file}/approve | Approve and cache |
GET | /-/admin/cache | List cached packages |
DELETE | /-/admin/cache/{name} | Delete package |
POST | /-/admin/cache/{name}/refresh | Force refresh from NPM |
Recommended: Use WebSocket (/-/admin/ws) for all admin operations. The admin panel uses WebSocket automatically.
Access the admin panel at http://localhost:4873/-/admin
Features:
Packages are stored locally in:
storage/packages/ - JSON metadatastorage/tarballs/ - Validated package tarballs (.tgz)storage/quarantine/ - Pending security scan (temporary)storage/backups/ - Timestamped backup copies of all published packages# First, start the server (required for tests)
bun start
# In another terminal, run tests
bun test
⚠️ Some tests (Admin Panel, Agent-First API, Documentation Site) require a running server to pass.
| Category | Tests | Status |
|---|---|---|
| Prompt Injection Scanner | 154 | ✅ |
| Server API | 72 | ✅ |
| Database Module | 54 | ✅ |
| IP Allowlist | 52 | ✅ |
| Admin Panel | 48 | ✅ |
| Security Module | 52 | ✅ |
| CVE Module | 39 | ✅ |
| Helpers & HTTP | 29 | ✅ |
| Validation | 28 | ✅ |
| Documentation Site | 26 | ✅ |
| Agent-First API | 25 | ✅ |
| Metrics Module | 25 | ✅ |
| Services (Cache & Broadcast) | 24 | ✅ |
| Package Allowlist | 21 | ✅ |
| Upstream Module | 18 | ✅ |
| Health Check | 16 | ✅ |
| Daemon | 13 | ✅ |
| Broadcast | 10 | ✅ |
| WebSocket Tests | 10 | ✅ |
| Compression | 9 | ✅ |
| Logger | 9 | ✅ |
| Allowlist | 8 | ✅ |
| CLI | 6 | ✅ |
| Unit Tests | 3 | ✅ |
| AST Scanner | 179 | ✅ |
| Total | 650+ | ✅ |
AgentRegistry automatically maintains itself:
| Feature | Interval | Details |
|---|---|---|
| Log Cleanup | Every 6 hours | Removes request logs >7 days, audit logs >30 days |
| Quarantine Auto-Approve | On startup | Re-scans quarantine, approves packages that now pass |
| Security Alerts | Kept forever | Blocked packages and security events are never deleted |
When a package is blocked by security scan, AgentRegistry returns detailed JSON with:
action_required: "HUMAN INTERVENTION REQUIRED"instructions array for resolution⚠️ LOCALHOST ONLY - This server is hardened for local use only.
| Layer | Protection |
|---|---|
| Network | Binds to 127.0.0.1 only (not 0.0.0.0) |
| Host Check | Rejects requests from non-localhost hosts (403) |
| Input Validation | Strict regex for package names and versions |
| Path Traversal | Blocks ../, null bytes, enforces basename() checks |
| XSS Protection | Output encoding via escapeHtml() on all render paths |
| Length Limits | Package names max 214 chars |
| Security Scanner | Static analysis before caching (~10-50ms) |
| Quarantine | All upstream packages scanned before cache |
All packages fetched from npmjs.org go through security scanning:
npm install lodash
↓
📥 Download from npmjs.org
↓
🔒 Write to storage/quarantine/
↓
🔍 Security scan (~10-50ms)
↓
✅ SAFE → Move to storage/tarballs/ + memory cache
🚨 BLOCKED → Stays in quarantine, returns 403
| Severity | Patterns Detected |
|---|---|
| Critical | eval(), new Function(), `curl |
| High | child_process, exec(), SSH/npmrc access, base64 payloads |
| Medium | File system writes, .env access, prototype pollution |
| Low | process.env access |
The prompt injection scanner uses a research-backed 10-pass analysis pipeline to detect LLM manipulation attempts hidden in package metadata, READMEs, and code comments:
| Pass | Technique | Catches |
|---|---|---|
| 1 | Raw content scan | Literal injection patterns in 5 languages |
| 2 | Unicode normalization + homoglyphs | Cyrillic/Greek/fullwidth character substitution |
| 3 | Leetspeak decode | 1gn0r3 4ll pr3v10us 1nstruct10ns |
| 4 | ROT13 decode | ROT13-encoded payloads |
| 5 | FlipAttack reversal | Character-reversed injection strings |
| 6 | Reconstruction patterns | String.fromCharCode(), `rever |