{"_id":"@abusix/guardian-intel-mcp-server","name":"@abusix/guardian-intel-mcp-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@abusix/guardian-intel-mcp-server","version":"1.0.1","description":"MCP server for Abusix Guardian Intel threat intelligence API","type":"module","main":"dist/index.js","bin":{"guardian-intel-mcp-server":"dist/cli.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","prepublishOnly":"npm run build && npm test"},"keywords":["mcp","threat-intelligence","abusix","guardian-intel","security"],"author":{"name":"Abusix"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^0.5.0","axios":"^1.6.0","commander":"^12.0.0","dotenv":"^17.0.1"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.5.0","ts-jest":"^29.1.0","tsx":"^4.0.0","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+ssh://git@github.com/abusix/guardian-intel-mcp-server.git"},"bugs":{"url":"https://github.com/abusix/guardian-intel-mcp-server/issues"},"homepage":"https://github.com/abusix/guardian-intel-mcp-server#readme","_id":"@abusix/guardian-intel-mcp-server@1.0.1","gitHead":"f6c995c4ccc4d5f2cb2b0036544b2a9f09a060d5","types":"./dist/index.d.ts","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-eq6fIyS2jrl9GQxk/qKb0Xcj9RG7ax50nrDK9o6NDOBoWP2+DQOOqEOPM4JiVqLvwaQE72re5Gc7dlR7DG7gMQ==","shasum":"4075aaa546925235a0d42156756cc9b7a4b2cd58","tarball":"https://registry.npmjs.org/@abusix/guardian-intel-mcp-server/-/guardian-intel-mcp-server-1.0.1.tgz","fileCount":22,"unpackedSize":63499,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAqCEwgiOyVTadCVRiITMORBR6+84zeii5a5+ByouQKAAiA8GrSevT2tyA/bJHt5TJ7CV82i9+mmBcnlwWv3fJ5uWQ=="}]},"_npmUser":{"name":"a2x_at_abusix","email":"alexander.wagner@abusix.com","actor":{"name":"a2x_at_abusix","email":"alexander.wagner@abusix.com","type":"user"}},"directories":{},"maintainers":[{"name":"thomasdissertabusix","email":"thomas.dissert@abusix.com"},{"name":"fabianskii","email":"fabian.isele@abusix.com"},{"name":"coderwelsch","email":"social@coderwelsch.com"},{"name":"abusix-main","email":"info@abusix.com"},{"name":"a2x_at_abusix","email":"alexander.wagner@abusix.com"},{"name":"a-rodelta","email":"rodrigo.delarivera@abusix.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/guardian-intel-mcp-server_1.0.1_1751445783084_0.7468154535387876"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-02T08:43:02.956Z","1.0.1":"2025-07-02T08:43:03.278Z","modified":"2025-07-02T08:43:03.637Z"},"maintainers":[{"name":"thomasdissertabusix","email":"thomas.dissert@abusix.com"},{"name":"fabianskii","email":"fabian.isele@abusix.com"},{"name":"coderwelsch","email":"social@coderwelsch.com"},{"name":"abusix-main","email":"info@abusix.com"},{"name":"a2x_at_abusix","email":"alexander.wagner@abusix.com"},{"name":"a-rodelta","email":"rodrigo.delarivera@abusix.com"}],"description":"MCP server for Abusix Guardian Intel threat intelligence API","homepage":"https://github.com/abusix/guardian-intel-mcp-server#readme","keywords":["mcp","threat-intelligence","abusix","guardian-intel","security"],"repository":{"type":"git","url":"git+ssh://git@github.com/abusix/guardian-intel-mcp-server.git"},"author":{"name":"Abusix"},"bugs":{"url":"https://github.com/abusix/guardian-intel-mcp-server/issues"},"license":"MIT","readme":"# Abusix Guardian Intel MCP Server\n\n[![npm version](https://badge.fury.io/js/@abusix%2Fguardian-intel-mcp-server.svg)](https://badge.fury.io/js/@abusix%2Fguardian-intel-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA Model Context Protocol (MCP) server that provides AI assistants with access to [Abusix Guardian Intel](https://abusix.com/guardian-intel/) threat intelligence data. This server enables AI models to perform IP reputation lookups, analyze threat intelligence tags, and access comprehensive security data with high-fidelity and low false positives.\n\n## Features\n\n- 🔍 **IP Threat Intelligence Lookup** - Comprehensive threat analysis for any IP address\n- 🏷️ **Threat Intelligence Tags** - Access to categorized threat intelligence taxonomy\n- 📊 **Tag-based IP Enumeration** - Find IP addresses associated with specific threat types\n- ⚡ **High Performance** - Built with TypeScript and optimized for speed\n- 🛡️ **Low False Positives** - Leverages Abusix's industry-leading 0.284% false positive rate\n- 🚀 **Easy Distribution** - Available via NPX for instant usage\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+ \n- Abusix Guardian Intel API key ([Get yours here](https://portal.abusix.com/))\n\n### Installation & Usage\n\nThe easiest way to use this MCP server is with NPX:\n\n```bash\n# Set your API key\nexport ABUSIX_API_KEY=\"your-api-key-here\"\n\n# Run the MCP server\nnpx @abusix/guardian-intel-mcp-server\n```\n\n### Alternative: Global Installation\n\n```bash\nnpm install -g @abusix/guardian-intel-mcp-server\nguardian-intel-mcp-server\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `ABUSIX_API_KEY` | Your Abusix Guardian Intel API key | ✅ Yes |\n| `ABUSIX_BASE_URL` | Custom API endpoint (default: https://threat-intel-api.abusix.com/beta) | ❌ No |\n\n### Command Line Options\n\n```bash\nnpx @abusix/guardian-intel-mcp-server [options]\n\nOptions:\n  --api-key <key>   Abusix Guardian Intel API key\n  --base-url <url>  Base URL for Guardian Intel API\n  --debug           Enable debug logging\n  --help-usage      Show detailed usage examples\n  -h, --help        Display help for command\n```\n\n## MCP Tools\n\nThis server provides 4 MCP tools for comprehensive threat intelligence analysis:\n\n### 1. `guardian_intel_lookup`\n\nLook up threat intelligence for an IP address.\n\n**Parameters:**\n- `ip` (string, required): IPv4 or IPv6 address to analyze\n\n**Returns:**\n- IP classification (malicious/suspicious/unknown)\n- Threat level assessment\n- First/last seen timestamps\n- Abuse contact information\n- ASN details\n- Blocklist presence\n- Observed malicious activities\n\n### 2. `guardian_intel_tags_list`\n\nRetrieve all available threat intelligence tags.\n\n**Parameters:**\n- `includeDescriptions` (boolean, optional): Include detailed tag descriptions\n\n**Returns:**\n- Complete list of available tags\n- Tag categories and intent classification\n- Statistical breakdown by category and intent\n\n### 3. `guardian_intel_tag_details`\n\nGet detailed information about a specific threat intelligence tag.\n\n**Parameters:**\n- `tagName` (string, required): Name of the tag (e.g., \"credentials:brute-force\")\n\n**Returns:**\n- Tag metadata (name, intent, category)\n- Detailed description\n- Reference links\n- Historical timeline\n\n### 4. `guardian_intel_tag_ips`\n\nRetrieve IP addresses associated with a specific threat intelligence tag.\n\n**Parameters:**\n- `tagName` (string, required): Name of the tag\n- `offset` (number, optional): Starting offset for pagination (default: 0)\n- `limit` (number, optional): Maximum IPs to return (default: 1000, max: 10000)\n- `snapshot` (string, optional): Snapshot ID for consistent pagination\n\n**Returns:**\n- List of IP addresses\n- Pagination metadata\n- Last update timestamp\n- Total count and snapshot information\n\n## Integration Examples\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"guardian-intel\": {\n      \"command\": \"npx\",\n      \"args\": [\"@abusix/guardian-intel-mcp-server\"],\n      \"env\": {\n        \"ABUSIX_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Continue.dev\n\nAdd to your `config.json`:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"guardian-intel\",\n      \"command\": \"npx\",\n      \"args\": [\"@abusix/guardian-intel-mcp-server\"],\n      \"env\": {\n        \"ABUSIX_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  ]\n}\n```\n\n### Generic MCP Client\n\n```bash\nmcp-client connect stdio -- npx @abusix/guardian-intel-mcp-server\n```\n\n## API Classifications\n\nGuardian Intel uses three main IP classifications:\n\n- **Malicious**: IPs with confirmed malicious activity or carrying malicious tags\n- **Suspicious**: IPs involved in systematic probing, scanning, or enumeration activities\n- **Unknown**: IPs that don't meet malicious or suspicious criteria\n\n## Data Sources\n\nAbusix Guardian Intel aggregates data from multiple high-quality sources:\n\n- 🍯 **Honeypots** - Deceptive systems designed to attract malicious activity\n- 📧 **Spamtraps** - Email addresses that should never receive legitimate mail\n- 🕳️ **Sinkholes** - Network resources capturing malicious traffic\n- 📨 **SMTP Transaction Feeds** - Real-time mail server interaction data\n- 🛡️ **Policy Blocklist Scanners** - Active server behavior validation\n- 🤝 **Partner Contributions** - Trusted data from ISPs and security partners\n\n## Development\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/abusix/guardian-intel-mcp-server.git\ncd guardian-intel-mcp-server\n\n# Install dependencies\nnpm install\n\n# Set up your API key\nexport ABUSIX_API_KEY=\"your-api-key-here\"\n\n# Run in development mode\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Test the built version\nnpm start\n```\n\n### Testing\n\n```bash\n# Test API connection without API key (should fail gracefully)\nnode dist/cli.js --debug\n\n# Test with API key\nABUSIX_API_KEY=\"your-key\" node dist/cli.js --debug\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling for:\n\n- Invalid API keys or authentication failures\n- Network connectivity issues\n- Invalid IP address formats\n- Non-existent threat intelligence tags\n- API rate limiting and service availability\n- Request timeouts\n\n## Security Considerations\n\n- API keys are handled securely and never logged\n- All API communication uses HTTPS\n- Input validation prevents injection attacks\n- Rate limiting is respected to prevent API abuse\n\n## Troubleshooting\n\n### Common Issues\n\n**\"ABUSIX_API_KEY environment variable is required\"**\n- Solution: Set your API key using `export ABUSIX_API_KEY=\"your-key\"` or use the `--api-key` option\n\n**\"Unable to connect to Guardian Intel API\"**\n- Check your internet connection\n- Verify your API key is valid\n- Check if there are firewall restrictions\n\n**\"Guardian Intel API Error (401)\"**\n- Your API key is invalid or has expired\n- Contact Abusix support to verify your account status\n\n**\"Guardian Intel API Error (503)\"**\n- The Guardian Intel service is temporarily unavailable\n- Try again in a few minutes\n\n### Debug Mode\n\nEnable debug mode for detailed logging:\n\n```bash\nnpx @abusix/guardian-intel-mcp-server --debug\n```\n\n## Support\n\n- 📚 **Documentation**: [Abusix Guardian Intel Docs](https://docs.abusix.com/docs/guardian-intel/)\n- 🎫 **Support Portal**: [portal.abusix.com](https://portal.abusix.com/)\n- 🐛 **Issues**: [GitHub Issues](https://github.com/abusix/guardian-intel-mcp-server/issues)\n- 🌐 **Website**: [abusix.com/guardian-intel](https://abusix.com/guardian-intel/)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n**Made with ❤️ by [Abusix](https://abusix.com/) - Making the digital world safer**","readmeFilename":"README.md","_rev":"1-7c854304d5090128c3beb14d8eaef4a2"}