{"id":51118977,"url":"https://github.com/sulthonzh/agent-dep-shield","last_synced_at":"2026-06-25T00:30:35.362Z","repository":{"id":363493454,"uuid":"1259783435","full_name":"sulthonzh/agent-dep-shield","owner":"sulthonzh","description":"Guard AI agent dependency installations with intelligent security checks","archived":false,"fork":false,"pushed_at":"2026-06-19T07:30:14.000Z","size":124,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T09:18:49.982Z","etag":null,"topics":["ai","ai-agent","code-security","dependency","guard","mcp","npm","pip","security","slopsquat","supply-chain","typosquat"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sulthonzh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T21:18:12.000Z","updated_at":"2026-06-19T07:25:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sulthonzh/agent-dep-shield","commit_stats":null,"previous_names":["sulthonzh/agent-dep-shield"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sulthonzh/agent-dep-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fagent-dep-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fagent-dep-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fagent-dep-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fagent-dep-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sulthonzh","download_url":"https://codeload.github.com/sulthonzh/agent-dep-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sulthonzh%2Fagent-dep-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","code-security","dependency","guard","mcp","npm","pip","security","slopsquat","supply-chain","typosquat"],"created_at":"2026-06-25T00:30:35.260Z","updated_at":"2026-06-25T00:30:35.353Z","avatar_url":"https://github.com/sulthonzh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Dep Shield\n\n[![CI](https://github.com/sulthonzh/agent-dep-shield/actions/workflows/ci.yml/badge.svg)](https://github.com/sulthonzh/agent-dep-shield/actions/workflows/ci.yml)\n[![NPM Version](https://img.shields.io/npm/v/agent-dep-shield.svg)](https://www.npmjs.com/package/agent-dep-shield)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Guard AI agent dependency installations** - Intercept and validate npm/pip packages before AI agents install them, preventing slopsquatting, typosquatting, and supply chain attacks.\n\n## The Problem\n\nAI coding agents (Claude Code, Cursor, Copilot, Codex) routinely suggest and install packages without security verification:\n\n- **Slopsquatting**: Attackers register packages that AI models hallucinate\n- **Typosquatting**: AI agents typo package names at scale  \n- **Post-install scripts**: #1 attack vector — agents run `npm install` blindly\n- 86% of repos have packages with known vulnerabilities\n- Average detection time for compromised package: 209 days\n\n## Solution\n\nAgent Dep Shield intercepts package installations with intelligent security checks:\n\n### 🚨 Pre-Install Protection\n- **Risk Scoring**: 0-100 score based on multiple security factors\n- **Block/Allow Logic**: Configurable thresholds for automatic blocking\n- **Audit Trail**: All decisions logged for security review\n\n### 🔍 Smart Detection\n- **Slopsquat Detection**: Validates package existence against top registries\n- **Typosquat Detection**: Edit distance analysis against popular packages\n- **Script Detection**: Flags packages with postinstall/preinstall hooks\n- **CVE Scanning**: Checks for known vulnerabilities\n\n### 🔌 Multiple Interfaces\n- **CLI**: Direct command-line usage\n- **MCP Server**: Native integration with AI agents\n- **Git Hook**: Pre-commit protection\n- **CI Integration**: GitHub Action and GitLab CI support\n\n## Installation\n\n```bash\nnpm install -g agent-dep-shield\n```\n\nOr use directly with npx:\n\n```bash\nnpx agent-dep-shield check \u003cpackage-name\u003e\n```\n\n## Quick Start\n\n### 1. Basic Package Check\n\n```bash\n# Check a single package\nnpx agent-dep-shield check express\n\n# Check with custom threshold\nnpx agent-dep-shield check express --risk-threshold 70\n\n# Multiple packages\nnpx agent-dep-shield check express react lodash\n```\n\n### 2. Intercept npm install\n\n```bash\n# Intercept package installation\nnpx agent-dep-shield install express\n\n# With automatic approval below threshold\nnpx agent-dep-shield install express --auto-approve 50\n\n# Block risky packages\nnpx agent-dep-shield install express --block-high-risk\n```\n\n### 3. Wrap npm install (Guard Mode)\n\n```bash\n# Intercept all npm installs in current session\nnpx agent-dep-shield guard\n\n# Guard with specific configuration\nnpx agent-dep-shield guard --config ./shield-config.json\n```\n\n## Configuration\n\nCreate `shield-config.json`:\n\n```json\n{\n  \"riskThresholds\": {\n    \"block\": 80,\n    \"warn\": 60,\n    \"autoApprove\": 40\n  },\n  \"checks\": {\n    \"slopsquat\": true,\n    \"typosquat\": true,\n    \"scripts\": true,\n    \"cve\": true\n  },\n  \"allowList\": [\"express\", \"react\", \"lodash\"],\n  \"blockList\": [\"eval\", \"dangerous-pkg\"],\n  \"registries\": {\n    \"npm\": \"https://registry.npmjs.org\",\n    \"pip\": \"https://pypi.org/simple\"\n  }\n}\n```\n\n## Usage Patterns\n\n### CLI Mode\n\n```bash\n# Check package before installation\nnpx agent-dep-shield check \u003cpackage\u003e\n\n# Install with security checks\nnpx agent-dep-shield install \u003cpackage\u003e\n\n# Guard mode - intercept all package operations\nnpx agent-dep-shield guard\n\n# MCP server mode\nnpx agent-dep-shield mcp-server\n```\n\n### MCP Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"dependency_check\": {\n      \"command\": \"npx\",\n      \"args\": [\"agent-dep-shield\", \"mcp-server\"]\n    }\n  }\n}\n```\n\n### Git Hook\n\n```bash\n# Pre-commit hook\ngit config hooks.dependency-check \"$(which agent-dep-shield) check\"\n\n# Or in .git/hooks/pre-commit:\n#!/bin/sh\nagent-dep-shield check $(git diff --cached --name-only --diff-filter=AM | grep -E 'package\\.json$|requirements\\.txt$' | xargs -I{} sh -c 'cat {} | grep -E \"\\\"[^\\\"]+\\\"|\\\"[^\\\"]+\\\"' | grep -E '^[^:]+:[0-9]+:' | awk -F: '{print $2}' | sed 's/[\"\",]//g')\n```\n\n## Risk Scoring\n\n### Risk Factors (0-100 scale)\n\n| Factor | Weight | Description |\n|--------|--------|-------------|\n| Package Existence | 30 | Does package exist in official registry? |\n| Popularity | 20 | Download count and community trust |\n| Script Presence | 25 | Has postinstall/preinstall scripts |\n| Vulnerability History | 15 | CVE history and security track record |\n| Age | 10 | Package age and maintenance status |\n\n### Risk Levels\n\n- **0-40**: Safe (Green) ✅\n- **41-70**: Moderate (Yellow) ⚠️\n- **71-80**: High (Orange) 🟠\n- **81-100**: Critical (Red) 🔴\n\n## Examples\n\n### Safe Package Check\n```bash\n$ npx agent-dep-shield check express\n\n📦 Checking express...\n✅ Package exists in npm registry\n✅ 81M+ weekly downloads (high popularity)\n✅ No postinstall scripts\n✅ Active maintenance (5 years)\n📊 Risk Score: 15/100 (SAFE)\n✅ Installation recommended\n```\n\n### Risky Package Check\n```bash\n$ npx agent-dep-shield check express-hack\n\n📦 Checking express-hack...\n⚠️ Package exists but suspicious name\n⚠️ Only 23 downloads (low popularity)\n⚠️ Contains postinstall scripts\n📊 Risk Score: 85/100 (CRITICAL)\n🚨 BLOCKED: High risk detected\n❌ Installation blocked\n```\n\n## Output Formats\n\n### JSON Output\n```json\n{\n  \"package\": \"express\",\n  \"riskScore\": 15,\n  \"riskLevel\": \"safe\",\n  \"checks\": {\n    \"exists\": true,\n    \"popularity\": { \"score\": 20, \"downloads\": \"81M+\" },\n    \"scripts\": false,\n    \"vulnerabilities\": [],\n    \"age\": { \"years\": 5, \"active\": true }\n  },\n  \"recommendation\": \"install\",\n  \"timestamp\": \"2026-06-05T03:47:00Z\"\n}\n```\n\n### Text Output\n```\n📦 Package: express\n📊 Risk Score: 15/100 (SAFE)\n✅ Exists in npm registry\n✅ 81M+ weekly downloads\n✅ No suspicious scripts\n✅ Active maintenance\n🎯 Recommendation: INSTALL\n```\n\n## Advanced Features\n\n### Custom Rules\n\n```json\n{\n  \"customRules\": [\n    {\n      \"name\": \"no-crypto-packages\",\n      \"pattern\": \"crypto.*\",\n      \"weight\": 90,\n      \"message\": \"Crypto packages require special approval\"\n    }\n  ]\n}\n```\n\n### Team Policies\n\n```json\n{\n  \"policies\": {\n    \"devDependencies\": {\n      \"maxRisk\": 50,\n      \"allowScripts\": false\n    },\n    \"production\": {\n      \"maxRisk\": 30,\n      \"requireVetApproval\": true\n    }\n  }\n}\n```\n\n## Integration\n\n### GitHub Action\n\n```yaml\nname: Dependency Security Check\non: [pull_request]\n\njobs:\n  security-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '18'\n      - run: npm install -g agent-dep-shield\n      - name: Check dependencies\n        run: |\n          agent-dep-shield check $(cat package.json | grep -E \"\\\"[^\\\"]+\\\"\" | awk -F'\"' '{print $2}')\n```\n\n### CI Pipeline Integration\n\n```bash\n# In your CI script\necho \"🔍 Running dependency security check...\"\nagent-dep-shield guard --ci-mode\n\n# Check before install\nif agent-dep-shield check react --risk-threshold 50; then\n  npm install react\nelse\n  echo \"❌ React package blocked due to security concerns\"\n  exit 1\nfi\n```\n\n## API\n\n### Programmatic Usage\n\n```javascript\nimport { AgentDepShield } from 'agent-dep-shield';\n\nconst shield = new AgentDepShield();\n\n// Check a package\nconst result = await shield.check('express');\nconsole.log(result.riskScore);\nconsole.log(result.recommendation);\n\n// Install with checks\nawait shield.install('express', { autoApprove: 40 });\n```\n\n## Development\n\n```bash\ngit clone https://github.com/sulthonzh/agent-dep-shield.git\ncd agent-dep-shield\nnpm install\nnpm run build\nnpm test\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Security\n\nAgent Dep Shield is designed to be security-first:\n\n- ✅ Zero dependencies for security isolation\n- ✅ Local-only analysis (no data sent to servers)\n- ✅ Configurable control over risk thresholds\n- ✅ Comprehensive audit logging\n\n## Acknowledgments\n\n- Based on research from Aikido.dev slopsquatting reports\n- Microsoft \"Mini Shai-Hulud\" campaign analysis\n- AI Coding Guild dependency security guidelines\n\n---\n\n**Agent Dep Shield** - Protecting AI agents from dependency attacks","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fagent-dep-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsulthonzh%2Fagent-dep-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsulthonzh%2Fagent-dep-shield/lists"}