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.
- 🔄 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
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 tgarchiveThe 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
# 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 .SPECTRA supports multi-account configuration with automatic account import from gen_config.py (TELESMASHER-compatible) and persistent SQL storage for all operations.
- Visit https://my.telegram.org/apps to register your application
- Create a config file or use the built-in account import:
# Import accounts from gen_config.py
python -m tgarchive accounts --importCurrent 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
Complete HTML documentation built with Docusaurus - a modern static site generator with:
- 🔍 Full-text search across all documentation
- 🌙 Dark theme (default) with light mode toggle
- 📱 Responsive design for mobile and desktop
- 🧭 Interactive navigation with organized sidebar
- ⚡ Fast loading with optimized static HTML
- 🔗 Versioning support for future releases
For local development:
cd docs
npm install # Install Docusaurus dependencies
npm start # Start development server (http://localhost:3000)
npm run build # Build static HTML to docs/html/Documentation Framework:
- Built with Docusaurus 3.x
- Source files:
docs/docs/(markdown with frontmatter) - Configuration:
docs/docusaurus.config.js - Build output:
docs/html/(generated HTML files) - Root entry point:
index.html(redirects to documentation)
- Installation Guide - Complete installation instructions
- Quick Start Guide - Get running in 30 seconds
- Configuration Guide - Setting up API keys and accounts
- 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
- Advanced Features - AI/ML intelligence, threat scoring, vector databases, and more
Original markdown files are still available in:
docs/guides/— User guides and walkthroughsdocs/reference/— Technical reference documentationdocs/features/— Feature documentationdocs/reports/— Security summaries and integration reportsdocs/roadmap/— Long-term initiatives and backlogdocs/research/— Strategic research documents
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
SPECTRA/tgarchive/discovery.py: Integration point for group crawling, network analysis, parallel archiving, and SQL-backed stateSPECTRA/tgarchive/__main__.py: Unified CLI/TUI entry pointexamples/parallel_example.py: Example for parallel, multi-account operations- All modules are importable and can be reused in your own scripts or pipelines
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.