@superadnim/osint-mcp-server

# OSINT MCP Server A professional-grade OSINT (Open Source Intelligence) MCP server that provides comprehensive intelligence gathering capabilities with strong privacy protection and ethical guidelines. ## Features ### 🔍 Intelligence Gathering Tools - **People Search**: Multi-source people search with demographic intelligence - **Phone Lookup**: Comprehensive phone number intelligence including carrier, location, and spam analysis - **Email Intelligence**: Email analysis including breach data and account enumeration - **Username Enumeration**: Systematic username discovery across platforms - **Domain Reconnaissance**: DNS analysis, WHOIS, and subdomain enumeration - **Google Dorking**: Advanced search engine reconnaissance - **Investigation Mind Maps**: Visual investigation workflow organization ### 🔒 Privacy & Security - **Privacy Protection**: Automatic redaction of sensitive information (SSN, financial data) - **GDPR/CCPA Compliance**: Built-in compliance with privacy regulations - **Data Retention**: Configurable data retention policies - **Audit Logging**: Comprehensive audit trail of all activities - **Rate Limiting**: Respectful API usage with configurable rate limits ### 🏗️ Architecture - **Three-Tier OSINT Methodology**: Basic → Intermediate → Advanced intelligence gathering - **Modular Data Sources**: Pluggable architecture for different intelligence sources - **Correlation Engine**: Cross-reference and validate data from multiple sources - **Caching System**: Intelligent caching to reduce API calls and improve performance - **Error Handling**: Robust error handling and fallback mechanisms ## Installation ### Global Installation ```bash npm install -g @superadnim/osint-mcp-server ``` ### NPX Usage ```bash npx @superadnim/osint-mcp-server ``` ### Local Project ```bash npm install @superadnim/osint-mcp-server ``` ## MCP Client Integration Add to your MCP client configuration: ```json { "mcpServers": { "osint": { "command": "npx", "args": ["@superadnim/osint-mcp-server"], "env": { "OSINT_API_TIMEOUT": "30000", "OSINT_RATE_LIMIT_ENABLED": "true" } } } } ``` ## Environment Variables ### API Configuration ```bash OSINT_API_TIMEOUT=30000 # API request timeout in milliseconds OSINT_RATE_LIMIT_ENABLED=true # Enable rate limiting OSINT_MAX_CONCURRENT_REQUESTS=5 # Maximum concurrent requests # Data Retention OSINT_DATA_RETENTION_HOURS=24 # Data retention in hours OSINT_INVESTIGATION_TTL=168 # Investigation TTL in hours (7 days) # Privacy Settings OSINT_REDACT_SSN=true # Redact Social Security Numbers OSINT_REDACT_FINANCIAL=true # Redact financial information OSINT_GDPR_COMPLIANCE=true # Enable GDPR compliance # Logging OSINT_LOG_LEVEL=info # Log level (debug, info, warn, error) OSINT_STRUCTURED_LOGGING=true # Enable structured JSON logging OSINT_AUDIT_ENABLED=true # Enable audit logging ``` ### API Keys (Optional for Enhanced Features) ```bash HAVEIBEENPWNED_API_KEY=your_key_here SHODAN_API_KEY=your_key_here VIRUSTOTAL_API_KEY=your_key_here HUNTER_IO_API_KEY=your_key_here NUMVERIFY_API_KEY=your_key_here ``` ## Available Tools ### 1. osint_people_search Search for people using name, email, or phone across multiple sources. ```json { "query": "John Doe", "search_type": "name", "include_relatives": false, "include_addresses": true, "confidence_threshold": 0.3, "max_results": 10 } ``` ### 2. osint_phone_lookup Lookup phone number information including carrier and location data. ```json { "phone": "+1234567890", "include_carrier": true, "include_location": true, "include_spam_check": true } ``` ### 3. osint_email_intel Analyze email addresses for breaches and account enumeration. ```json { "email": "example@domain.com", "check_breaches": true, "enumerate_accounts": false, "analyze_domain": true } ``` ### 4. osint_username_enum Enumerate username across social media platforms. ```json { "username": "johndoe123", "platforms": ["twitter", "instagram", "linkedin"], "include_profiles": false, "max_concurrent": 10 } ``` ### 5. osint_domain_recon Perform comprehensive domain reconnaissance. ```json { "domain": "example.com", "include_subdomains": false, "include_dns_records": true, "include_whois": true } ``` ### 6. osint_google_dorking Advanced Google dorking and search engine reconnaissance. ```json { "query": "site:example.com filetype:pdf", "dork_type": "custom", "max_results": 10 } ``` ### 7. osint_create_mind_map Create and manage investigation mind maps. ```json { "investigation_id": "inv-123", "action": "create", "name": "Investigation Alpha" } ``` ## Privacy and Ethics This tool is designed for **defensive security purposes only**. Users must: - Only investigate entities they have explicit permission to research - Comply with all applicable laws and regulations - Respect privacy and data protection rights - Use the tool ethically and responsibly - Not use the tool for harassment, stalking, or malicious purposes ### Built-in Privacy Protection - Automatic redaction of sensitive personal information - Configurable data retention policies - GDPR/CCPA compliance features - Audit logging for accountability - No persistent storage of personal data ## Development ### Prerequisites - Node.js >= 18.0.0 - NPM >= 8.0.0 ### Setup ```bash git clone <repository> cd osint-mcp-server npm install ``` ### Build ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ### Testing ```bash npm test npm run test:coverage ``` ### Linting ```bash npm run lint npm run lint:fix ``` ## License MIT License - see [LICENSE](LICENSE) file for details. ## Disclaimer This software is provided for educational and defensive security purposes only. Users are responsible for ensuring their use complies with all applicable laws and regulations. The authors are not responsible for any misuse of this tool. ## Contributing Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## Support For issues and questions: - GitHub Issues: [Create an issue](https://github.com/osint-tools/mcp-server/issues) - Documentation: [Full documentation](docs/) --- **⚠️ Important**: Always use this tool responsibly and in compliance with applicable laws and ethical guidelines.