SPECTRA

Spectrally-Processing Extraction, Crawling, & Tele-Reconnaissance Archive

SPECTRA is an advanced framework for Telegram data collection, network discovery, and forensic-grade archiving with multi-account support, graph-based targeting, and robust OPSEC features.

Features

• 🔄 Multi-account & API key rotation with smart, persistent selection and failure detection
• 🕵️ Proxy rotation for OPSEC and anti-detection
• 🔎 Network discovery of connected groups and channels (with SQL audit trail)
• 📊 Graph/network analysis to identify high-value targets
• 📁 Forensic archiving with integrity checksums and sidecar metadata
• 📱 Topic/thread support for complete conversation capture
• 🗄️ SQL database storage for all discovered groups, relationships, and archive metadata
• ⚡ Parallel processing leveraging multiple accounts and proxies simultaneously
• 🖥️ Modern TUI (npyscreen) and CLI, both using the same modular backend
• ⚙️ Streamlined Account Management - Full CRUD operations directly in the TUI with keyboard shortcuts
• ☁️ Forwarding Mode: Traverse a series of channels, discover related channels, and download text/archive files with specific rules, using a single API key.
• 🛡️ Red team/OPSEC features: account/proxy rotation, SQL audit trail, sidecar metadata, persistent state

⚡ Quick Start

One-command setup and launch:

# Clone and enter directory
git clone https://github.com/SWORDIntel/SPECTRA.git
cd SPECTRA

# Bootstrap (automatic setup + launch)
./bootstrap
# OR use make
make bootstrap

# On subsequent runs, just launch the TUI
make run
# OR
python -m tgarchive

The TUI (Terminal User Interface) is the primary way to interact with SPECTRA. It provides an intuitive, menu-driven interface for all operations including archiving, discovery, network analysis, and forwarding.

For more commands: make help

Installation

# Clone the repository
git clone https://github.com/SWORDIntel/SPECTRA.git
cd SPECTRA

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install core dependencies (recommended - stable)
pip install telethon rich pillow pandas networkx matplotlib python-magic pyaes pyasn1 feedgen lxml imagehash croniter npyscreen pysocks

# OR install all dependencies (may require system packages)
pip install -r requirements.txt

# Install package in development mode
pip install -e .

Configuration

SPECTRA supports multi-account configuration with automatic account import from gen_config.py (TELESMASHER-compatible) and persistent SQL storage for all operations.

Setting up Telegram API access

1. Visit https://my.telegram.org/apps to register your application
2. Create a config file or use the built-in account import:

# Import accounts from gen_config.py
python -m tgarchive accounts --import

System Status

Current Version: 2025-01-XX (Production Ready)

• ✅ Core System: Fully operational with all syntax errors resolved
• ✅ CLI Interface: 18 commands available and tested
• ✅ Dependencies: Core dependencies installed and verified
• ✅ Architecture: Professional-grade modular design validated
• ✅ CNSA 2.0 Compliance: All cryptographic operations updated

Recent Enhancements (2025-01-XX):

• Fixed critical Git merge conflicts blocking system startup
• Resolved CLI parser conflicts and syntax errors
• Validated full system functionality and dependency chain
• See CHANGELOG.md for complete details

Documentation

📚 Full Documentation Site

Complete HTML documentation with search, navigation, and interactive features.

For local development:

cd docs && npm install && npm start

Quick Links

Getting Started

• Installation Guide - Complete installation instructions
• Quick Start Guide - Get running in 30 seconds
• Configuration Guide - Setting up API keys and accounts

User Guides

• TUI Usage Guide - Complete guide to using the Terminal User Interface
• Forwarding Guide - Message forwarding and deduplication features
• CLI Reference - Complete command-line interface documentation

Features

• Advanced Features - AI/ML intelligence, threat scoring, vector databases, and more

Legacy Documentation

Original markdown files are still available in:

• docs/guides/ — User guides and walkthroughs
• docs/reference/ — Technical reference documentation
• docs/features/ — Feature documentation
• docs/reports/ — Security summaries and integration reports
• docs/roadmap/ — Long-term initiatives and backlog
• docs/research/ — Strategic research documents

Project Layout

SPECTRA/
├── scripts/          ← Executable scripts (install, launch, setup)
├── docs/             ← Documentation and guides
├── data/             ← Runtime data (not tracked in git)
├── src/              ← Archived/deprecated code
├── tgarchive/        ← Main Python package
│   ├── core/         ← Core business logic
│   ├── ui/           ← User interfaces (TUI)
│   ├── services/     ← Background services
│   ├── utils/        ← Utility functions
│   ├── db/           ← Database layer
│   ├── forwarding/   ← Message forwarding
│   └── osint/        ← Intelligence gathering
├── tests/            ← Test suite
├── examples/         ← Example scripts
├── bootstrap         ← Auto-setup entry point (recommended)
├── Makefile          ← Common commands (make help)
└── setup.py          ← Python package setup

For detailed structure explanation, see PROJECT_STRUCTURE.md

Integration & Architecture

• SPECTRA/tgarchive/discovery.py: Integration point for group crawling, network analysis, parallel archiving, and SQL-backed state
• SPECTRA/tgarchive/__main__.py: Unified CLI/TUI entry point
• examples/parallel_example.py: Example for parallel, multi-account operations
• All modules are importable and can be reused in your own scripts or pipelines

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.