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
Root launchers:
# Clone and enter directory
git clone https://github.com/SWORDIntel/SPECTRA.git
cd SPECTRA
# Main web console
./spectra
# Documentation launcher
python3 webapp.py./spectra is the primary entry point for the web console. python3 webapp.py opens the documentation shell and lands on /docs.
The repository also includes a local web launcher for orchestration, status, and documentation:
./spectraOptional API key protection:
export SPECTRA_GUI_API_KEY="change-me"
./spectra --api-key "$SPECTRA_GUI_API_KEY"Standard machine-readable API surfaces:
/openapi.json/.well-known/openapi.json/docs
# 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/
├── spectra ← Main launcher for the local web console
├── webapp.py ← Documentation launcher (`/docs`)
├── spectra.sh ← Compatibility wrapper
├── tgarchive/ ← Core CLI/TUI/archive/forwarding package
├── src/spectra_app/ ← Web launcher and orchestration implementation
├── spectra_app/ ← Compatibility package for repo-root imports
├── templates/ ← Shared web UI templates
├── docs/ ← Docusaurus source and compatibility docs
├── scripts/ ← Install, launch, and maintenance helpers
├── examples/ ← Example scripts
├── tests/ ← Repo-level smoke/integration scripts
├── deployment/ ← Docker/system deployment assets
├── bootstrap ← Bootstrap entrypoint
├── index.html ← Root redirect into the documentation site
├── Makefile ← Common development commands
├── setup.py ← Packaging entrypoint
└── CONTRIBUTING.md ← Development workflow guide
Local runtime output such as logs/, spectra_venv/, and spectra_config.json is intentionally kept out of version control.
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
See CONTRIBUTING.md for development workflow and verification guidance.
This project is licensed under the MIT License - see the LICENSE file for details.