# Spectra

![Spectra Logo](images/Belati-logo.png)

**Spectra — Open-Source OSINT Reconnaissance Toolkit**

A Python 3 OSINT framework for collecting publicly available data about domains, IP addresses, email addresses, and organisations. Runs as an interactive CLI, a Django web UI, and an MCP server for Claude Desktop.

> **Ethical Use Notice:** This tool is for educational and authorised security research only. Only use it against targets you have explicit written permission to scan. The authors accept no liability for misuse.

---

## Features

| Category | Capability |
|---|---|
| Domain Intel | WHOIS, Banner Grab, Subdomain Enum (5 sources), DNS Deep Scan |
| IP Intel | IP WHOIS/ARIN, ASN/BGP lookup, Reverse DNS, Real IP behind CDN/WAF |
| SSL/TLS | Certificate inspection, CT log history, expiry alerts |
| Web Fingerprinting | Security Headers (A+ grade), WAF/CDN detection, Favicon Hash (Shodan) |
| Email Intel | Email harvest from search engines + PGP keyservers |
| Document Intel | Public document scraper, EXIF/metadata extraction |
| Exposure Checks | Exposed .git/.svn, .env, config.php, backups, phpinfo |
| Network Recon | Port scanner (with rate limiting), robots.txt scraper |
| Company Intel | LinkedIn company/employee intelligence |
| Username | Username availability checker across platforms |
| Storage | SQLite3 database for scan results |
| Interfaces | Interactive CLI, Django web UI, MCP server for Claude Desktop |
| Privacy | Rotating User-Agents, proxy support (single + rotating list) |

---

## Requirements

### System
- Python 3.10+
- `nmap` (optional — for port scanning; non-root TCP scan works without it)
- `exiftool` (optional — for document metadata extraction)
- `git` (optional — for update checks)

### Install system deps

**Debian/Ubuntu:**
```bash
sudo apt-get install nmap git sqlite3 libimage-exiftool-perl
```

**macOS (Homebrew):**
```bash
brew install nmap git exiftool
```

**Windows:**
- Install [nmap](https://nmap.org/download.html) and add it to PATH
- Install [ExifTool](https://exiftool.org)

---

## Installation

```bash
git clone https://github.com/your-username/spectra.git
cd spectra
pip install -r requirements.txt
python3 Spectra.py --help
```

### Docker
```bash
docker build -t spectra .
docker run -it --rm spectra

# With web UI:
docker run -p 127.0.0.1:8000:8000 -it spectra python3 web/manage.py runserver 0.0.0.0:8000
```

---

## CLI Usage

```bash
python3 Spectra.py
```

Inside the interactive shell:

```
spectra > set domain example.com
spectra > set orgcomp "Example Corp"
spectra > show options
spectra > start
```

### CLI Options

| Command | Description |
|---|---|
| `set domain <value>` | Target domain |
| `set orgcomp <value>` | Organisation/company name |
| `set username <value>` | Username to check |
| `set email <value>` | Email address |
| `set proxy <url>` | Single proxy (e.g. `http://127.0.0.1:8080`) |
| `set proxy_file <path>` | File with proxy list (one per line) |
| `show options` | Display all parameter values |
| `start` | Run full automated scan |
| `startws` | Start web UI only |
| `version` | Show version |
| `quit` | Exit |

### SSL Verification

By default all requests verify SSL certificates. If you are scanning a target with a known self-signed certificate, you can disable verification explicitly:

```bash
python3 Spectra.py --no-ssl-verify
```

A warning is printed when this flag is used. Never use it casually.

---

## Web UI

After running a scan the Django web UI shows all results:

```bash
python3 web/manage.py runserver 127.0.0.1:8000
```

Then open `http://127.0.0.1:8000` in your browser.

> **NOTE:** `runserver` is for local use only. Do not expose it on a public interface or production server. It has no authentication and is not hardened.

### First-time setup

```bash
python3 web/manage.py migrate
```

---

## MCP Server (Claude Desktop Integration)

Spectra exposes all its scan functions as MCP tools so Claude can call them directly in conversation.

### Setup

1. Run the MCP server:
   ```bash
   python3 spectra_mcp_server.py
   ```

2. Add to Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
   ```json
   {
     "mcpServers": {
       "spectra": {
         "command": "python3",
         "args": ["C:/full/path/to/spectra/spectra_mcp_server.py"]
       }
     }
   }
   ```

3. Restart Claude Desktop. You will see the Spectra tools listed.

### Available MCP Tools

| Tool | Description |
|---|---|
| `spectra_whois` | WHOIS lookup |
| `spectra_subdomain_enum` | Subdomain enumeration |
| `spectra_dns_deep_scan` | Full DNS scan |
| `spectra_ssl_inspect` | SSL/TLS inspection |
| `spectra_asn_lookup` | ASN/BGP lookup |
| `spectra_reverse_dns` | Reverse DNS / PTR |
| `spectra_real_ip_finder` | Find origin IP behind CDN/WAF |
| `spectra_security_headers` | HTTP security header analysis |
| `spectra_waf_detect` | WAF/CDN detection |
| `spectra_ip_whois` | Full IP WHOIS / ARIN |
| `spectra_favicon_hash` | Favicon MurmurHash3 (Shodan) |
| `spectra_banner_grab` | HTTP/HTTPS banner grab |
| `spectra_robots_scraper` | robots.txt fetch |
| `spectra_harvest_email` | Email harvest from PGP keyservers |
| `spectra_exposed_files` | Exposed .env, config, backups |
| `spectra_port_scan` | Port scan with rate limiting |

---

## Security Notes

- **SSL verification** is enabled by default. Use `--no-ssl-verify` only when explicitly needed.
- **nmap** uses TCP connect scan (`-sT`) when running as a non-root user; SYN scan (`-sS`) only when root.
- **Input validation** is applied to all domain/IP inputs before they reach any subprocess or DNS resolver.
- **SQLite database** stores scan results in plaintext. Treat `web/db.sqlite3` as sensitive data — it contains OSINT findings including emails, IP info, and document metadata. Do not commit it to version control.
- **Django SECRET_KEY** should be set via the `SPECTRA_SECRET_KEY` environment variable before any use beyond local-only. The default insecure key is only acceptable for local-only dev use.
- **Rate limiting** is applied to port scans (50ms default delay, configurable). Increase it when scanning to avoid triggering IDS alerts.
- **Log files** in `logs/` use rotating handlers (5 MB, 5 backups) and are excluded from git. They may contain sensitive target information — treat them accordingly.

---

## Tested On

- Ubuntu 22.04 / 24.04
- Debian 12 (Bookworm)
- macOS 14+
- Windows 11

---

## Credits & License

Spectra is based on **Belati** (Copyright © 2017 Aan Wahyu / Petruknisme, https://github.com/aancw/Belati).

Licensed under the **GNU General Public License v2 (GPLv2)**. See [LICENSE](LICENSE) for the full text.

Portions of this project incorporate:
- [pywhois](https://github.com/richardpenman/pywhois) — WHOIS parsing
- [CheckMyUsername](https://github.com/aancw/CheckMyUsername) — vendored in `lib/`
- MailHarvester / Emingoo regex patterns — thanks to pantuts and maldevel

---

## Contributing

Pull requests welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md).