npm package: @modular-intelligence/maltego
Description: MCP server for OSINT entity enrichment using multiple intelligence APIs
Latest version: 1.0.2

# Maltego OSINT MCP Server

A comprehensive Model Context Protocol (MCP) server for Open Source Intelligence (OSINT) entity enrichment using multiple intelligence APIs. This server provides powerful tools for investigating domains, IP addresses, emails, people, and companies through various public intelligence sources.

## Features

- **Multi-API Integration**: Combines data from multiple OSINT sources
- **Entity-Based Investigations**: Support for domains, IPs, emails, people, companies, phones, hashes, and URLs
- **Graph Building**: Recursively discover and map relationships between entities
- **Privacy-Aware**: All outputs include PII warnings for responsible data handling
- **Read-Only Operations**: Safe, non-intrusive intelligence gathering
- **Graceful Degradation**: Works with varying levels of API key configuration

## Available Tools

### 1. maltego_entity_lookup
Generic entity lookup that routes to appropriate APIs based on entity type.

**Parameters:**
- `entity_type`: Type of entity (domain, ip, email, phone, hash, url)
- `entity_value`: The entity value to investigate
- `depth`: Enrichment depth (1-3, default: 1)

**Data Sources:**
- Domains: WHOIS, DNS-over-HTTPS
- IPs: ip-api.com, AbuseIPDB
- Emails: Hunter.io
- Hashes: VirusTotal

### 2. maltego_domain_recon
Comprehensive domain reconnaissance and intelligence gathering.

**Parameters:**
- `domain`: Domain name to investigate
- `include`: Data sources to query (whois, dns, subdomains, certificates, technologies)

**Capabilities:**
- WHOIS registration data
- DNS records (A, AAAA, MX, NS, TXT, CNAME)
- Subdomain enumeration via certificate transparency
- SSL/TLS certificate history
- Technology stack detection (with API key)

### 3. maltego_person_search
Search and profile individuals across multiple sources.

**Parameters:**
- `name`: Person's full name
- `domain`: Associated domain/company (optional)
- `depth`: Search depth (1-3, default: 1)

**Capabilities:**
- Email discovery via Hunter.io
- Domain associations
- Social media profile hints
- Professional information

### 4. maltego_company_search
Company and organization intelligence gathering.

**Parameters:**
- `company`: Company or organization name
- `depth`: Search depth (1-3, default: 1)

**Capabilities:**
- Domain discovery
- Email pattern identification
- Employee enumeration
- WHOIS and DNS data for discovered domains

### 5. maltego_ip_enrichment
Detailed IP address intelligence and reputation analysis.

**Parameters:**
- `ip`: IP address (IPv4 or IPv6)
- `depth`: Enrichment depth (1-3, default: 1)

**Capabilities:**
- Geolocation (country, city, ISP, organization)
- Abuse and reputation scoring via AbuseIPDB
- Open port and service detection via Shodan
- Reverse DNS lookup
- ASN information

### 6. maltego_email_investigate
Email address verification and investigation.

**Parameters:**
- `email`: Email address to investigate
- `depth`: Investigation depth (1-3, default: 1)

**Capabilities:**
- Email deliverability verification
- Source attribution
- Associated person identification
- Domain intelligence
- MX record validation
- Social profile discovery

### 7. maltego_graph_build
Build comprehensive relationship graphs through recursive entity enrichment.

**Parameters:**
- `root_entity`: Starting entity value
- `root_type`: Starting entity type (domain, ip, email, person, company)
- `depth`: Graph depth (1-3, default: 1)
- `max_nodes`: Maximum graph nodes (1-100, default: 50)

**Output:**
- Nodes with entity type, value, and properties
- Edges showing relationships between entities
- Graph statistics

## Prerequisites

### Required
- Bun runtime (v1.0.0+)

### Optional API Keys
The server works with varying levels of functionality based on available API keys. Configure as many as needed:

- `HUNTER_API_KEY`: Email intelligence and verification (Hunter.io)
- `ABUSEIPDB_API_KEY`: IP reputation and abuse reports
- `SHODAN_API_KEY`: Port scanning and service detection
- `VIRUSTOTAL_API_KEY`: Hash and file reputation
- `PASSIVETOTAL_API_KEY`: Passive DNS and threat intelligence
- `BUILTWITH_API_KEY`: Technology stack detection

**Note:** The server degrades gracefully - features requiring missing API keys will return informative messages about configuration requirements.

## Installation

```bash
cd /path/to/mi-mcp-servers/packages/maltego
bun install
```

## Configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
# Optional API Keys - add as many as you have
export HUNTER_API_KEY="your_hunter_api_key"
export ABUSEIPDB_API_KEY="your_abuseipdb_key"
export SHODAN_API_KEY="your_shodan_key"
export VIRUSTOTAL_API_KEY="your_virustotal_key"
export PASSIVETOTAL_API_KEY="your_passivetotal_key"
export BUILTWITH_API_KEY="your_builtwith_key"
```

### MCP Settings

Add to your MCP settings file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "maltego": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/maltego/src/index.ts"],
      "env": {
        "HUNTER_API_KEY": "your_hunter_api_key",
        "ABUSEIPDB_API_KEY": "your_abuseipdb_key",
        "SHODAN_API_KEY": "your_shodan_key"
      }
    }
  }
}
```

## Usage Examples

### Domain Investigation
```javascript
// Comprehensive domain recon
maltego_domain_recon({
  domain: "example.com",
  include: ["whois", "dns", "subdomains", "certificates"]
})
```

### Email Verification
```javascript
// Verify and investigate email
maltego_email_investigate({
  email: "contact@example.com",
  depth: 2
})
```

### IP Intelligence
```javascript
// Deep IP enrichment
maltego_ip_enrichment({
  ip: "8.8.8.8",
  depth: 2
})
```

### Graph Building
```javascript
// Build relationship graph from domain
maltego_graph_build({
  root_entity: "example.com",
  root_type: "domain",
  depth: 2,
  max_nodes: 50
})
```

## Security & Privacy

### PII Warnings
All tool outputs include the following warning:
> ⚠️ This output may contain personally identifiable information (PII). Handle according to your organization's data handling policies.

### Security Features
- **Input Validation**: All inputs validated against strict regex patterns
- **Rate Limiting**: 10 requests per second per API to prevent abuse
- **Sanitization**: Entity values checked for shell metacharacters
- **Depth Limiting**: Maximum enrichment depth of 3 levels
- **Read-Only**: All operations are non-intrusive lookups

### Best Practices
1. **Compliance**: Ensure OSINT activities comply with applicable laws and regulations
2. **Authorization**: Only investigate entities you have authorization to research
3. **Data Handling**: Follow your organization's data retention and privacy policies
4. **API Keys**: Keep API keys secure and never commit them to version control
5. **Rate Limits**: Respect API provider rate limits and terms of service

## API Sources

This server integrates with:

- **WHOIS**: whoisjson.com (domain registration data)
- **DNS**: Cloudflare DNS-over-HTTPS (DNS records)
- **Certificates**: crt.sh (certificate transparency logs)
- **Geolocation**: ip-api.com (IP geolocation)
- **Reputation**: AbuseIPDB (IP abuse reports)
- **Port Scanning**: Shodan (service detection)
- **Email Intelligence**: Hunter.io (email verification and discovery)
- **File Hashing**: VirusTotal (hash reputation)

## Development

### Build
```bash
bun run build
```

### Start
```bash
bun run start
```

### Project Structure
```
maltego/
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── README.md            # This file
└── src/
    ├── index.ts         # Main server entry point
    ├── schemas.ts       # Zod validation schemas
    ├── security.ts      # Security utilities
    └── tools/
        ├── maltego-entity-lookup.ts
        ├── maltego-domain-recon.ts
        ├── maltego-person-search.ts
        ├── maltego-company-search.ts
        ├── maltego-ip-enrichment.ts
        ├── maltego-email-investigate.ts
        └── maltego-graph-build.ts
```

## Limitations

- **Rate Limits**: Subject to API provider rate limits
- **API Coverage**: Some features require paid API subscriptions
- **Data Freshness**: Data freshness depends on source APIs
- **Completeness**: Not all entity types supported by all data sources

## Troubleshooting

### "Required API key not set"
- Configure the required API key in your environment
- Check that the environment variable name matches exactly

### Rate Limit Errors
- Built-in rate limiting protects against most issues
- Some APIs have daily/monthly quotas - check your usage

### No Results Returned
- Verify the entity value format is correct
- Check that the entity exists and is publicly queryable
- Ensure API keys are valid and active

## License

MIT License - See LICENSE file for details

## Contributing

Contributions welcome! Please ensure:
1. All Zod schemas include `.describe()` for all fields
2. Security validations are maintained
3. PII warnings are included in outputs
4. Error handling is comprehensive
5. API rate limiting is respected

## Disclaimer

This tool is for authorized security research and intelligence gathering only. Users are responsible for ensuring their use complies with all applicable laws, regulations, and terms of service. The authors assume no liability for misuse.