phantomsignal 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. phantomsignal-1.3.0/LICENSE +32 -0
  2. phantomsignal-1.3.0/MANIFEST.in +6 -0
  3. phantomsignal-1.3.0/PKG-INFO +466 -0
  4. phantomsignal-1.3.0/README.md +364 -0
  5. phantomsignal-1.3.0/config/phantomsignal.yaml +104 -0
  6. phantomsignal-1.3.0/phantomsignal/__init__.py +56 -0
  7. phantomsignal-1.3.0/phantomsignal/cli.py +635 -0
  8. phantomsignal-1.3.0/phantomsignal/core/__init__.py +0 -0
  9. phantomsignal-1.3.0/phantomsignal/core/config.py +244 -0
  10. phantomsignal-1.3.0/phantomsignal/core/database.py +83 -0
  11. phantomsignal-1.3.0/phantomsignal/core/engine.py +276 -0
  12. phantomsignal-1.3.0/phantomsignal/core/models.py +279 -0
  13. phantomsignal-1.3.0/phantomsignal/exporters/__init__.py +0 -0
  14. phantomsignal-1.3.0/phantomsignal/exporters/manager.py +528 -0
  15. phantomsignal-1.3.0/phantomsignal/intel/__init__.py +0 -0
  16. phantomsignal-1.3.0/phantomsignal/intel/apis/__init__.py +0 -0
  17. phantomsignal-1.3.0/phantomsignal/intel/apis/all_apis.py +1558 -0
  18. phantomsignal-1.3.0/phantomsignal/intel/apis/base.py +215 -0
  19. phantomsignal-1.3.0/phantomsignal/intel/apis/shodan_api.py +165 -0
  20. phantomsignal-1.3.0/phantomsignal/intel/orchestrator.py +130 -0
  21. phantomsignal-1.3.0/phantomsignal/intel/people/__init__.py +0 -0
  22. phantomsignal-1.3.0/phantomsignal/intel/people/aggregator.py +254 -0
  23. phantomsignal-1.3.0/phantomsignal/scrapers/__init__.py +0 -0
  24. phantomsignal-1.3.0/phantomsignal/scrapers/api_hunter.py +286 -0
  25. phantomsignal-1.3.0/phantomsignal/scrapers/crawler.py +366 -0
  26. phantomsignal-1.3.0/phantomsignal/scrapers/dns_recon.py +379 -0
  27. phantomsignal-1.3.0/phantomsignal/scrapers/port_scanner.py +448 -0
  28. phantomsignal-1.3.0/phantomsignal/scrapers/spiders/__init__.py +0 -0
  29. phantomsignal-1.3.0/phantomsignal/scrapers/tech_detector.py +447 -0
  30. phantomsignal-1.3.0/phantomsignal/web/__init__.py +0 -0
  31. phantomsignal-1.3.0/phantomsignal/web/app.py +134 -0
  32. phantomsignal-1.3.0/phantomsignal/web/routes/__init__.py +0 -0
  33. phantomsignal-1.3.0/phantomsignal/web/routes/api.py +106 -0
  34. phantomsignal-1.3.0/phantomsignal/web/routes/dashboard.py +48 -0
  35. phantomsignal-1.3.0/phantomsignal/web/routes/export.py +66 -0
  36. phantomsignal-1.3.0/phantomsignal/web/routes/intel.py +59 -0
  37. phantomsignal-1.3.0/phantomsignal/web/routes/scans.py +124 -0
  38. phantomsignal-1.3.0/phantomsignal/web/routes/settings.py +63 -0
  39. phantomsignal-1.3.0/phantomsignal/web/static/css/owlscan.css +1609 -0
  40. phantomsignal-1.3.0/phantomsignal/web/static/img/owl-ascii-transparent.png +0 -0
  41. phantomsignal-1.3.0/phantomsignal/web/static/img/owl-ascii.png +0 -0
  42. phantomsignal-1.3.0/phantomsignal/web/static/js/app.js +239 -0
  43. phantomsignal-1.3.0/phantomsignal/web/static/js/matrix.js +70 -0
  44. phantomsignal-1.3.0/phantomsignal/web/static/js/terminal.js +67 -0
  45. phantomsignal-1.3.0/phantomsignal/web/templates/about.html +157 -0
  46. phantomsignal-1.3.0/phantomsignal/web/templates/base.html +105 -0
  47. phantomsignal-1.3.0/phantomsignal/web/templates/dashboard.html +198 -0
  48. phantomsignal-1.3.0/phantomsignal/web/templates/errors/404.html +10 -0
  49. phantomsignal-1.3.0/phantomsignal/web/templates/errors/500.html +10 -0
  50. phantomsignal-1.3.0/phantomsignal/web/templates/export.html +104 -0
  51. phantomsignal-1.3.0/phantomsignal/web/templates/intel/results.html +181 -0
  52. phantomsignal-1.3.0/phantomsignal/web/templates/intel/search.html +132 -0
  53. phantomsignal-1.3.0/phantomsignal/web/templates/scans/list.html +77 -0
  54. phantomsignal-1.3.0/phantomsignal/web/templates/scans/new.html +312 -0
  55. phantomsignal-1.3.0/phantomsignal/web/templates/scans/results.html +463 -0
  56. phantomsignal-1.3.0/phantomsignal/web/templates/settings.html +155 -0
  57. phantomsignal-1.3.0/phantomsignal.egg-info/PKG-INFO +466 -0
  58. phantomsignal-1.3.0/phantomsignal.egg-info/SOURCES.txt +63 -0
  59. phantomsignal-1.3.0/phantomsignal.egg-info/dependency_links.txt +1 -0
  60. phantomsignal-1.3.0/phantomsignal.egg-info/entry_points.txt +3 -0
  61. phantomsignal-1.3.0/phantomsignal.egg-info/requires.txt +63 -0
  62. phantomsignal-1.3.0/phantomsignal.egg-info/top_level.txt +1 -0
  63. phantomsignal-1.3.0/requirements.txt +105 -0
  64. phantomsignal-1.3.0/setup.cfg +4 -0
  65. phantomsignal-1.3.0/setup.py +53 -0
@@ -0,0 +1,32 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 packetsn1ffer
4
+ Claude (Anthropic) — AI Architecture & Implementation
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
23
+
24
+ ---
25
+
26
+ NightOwl — Open Source OSINT Intelligence Framework
27
+ "The night sees all. The owl forgets nothing."
28
+
29
+ This software is intended for authorized security research, OSINT investigation,
30
+ and educational purposes only. Users are solely responsible for ensuring their
31
+ use complies with all applicable local, state, national, and international laws.
32
+ The authors assume no liability for misuse or damage caused by this software.
@@ -0,0 +1,6 @@
1
+ include requirements.txt
2
+ include LICENSE
3
+ include README.md
4
+ recursive-include phantomsignal/web/templates *.html
5
+ recursive-include phantomsignal/web/static *
6
+ recursive-include config *.yaml *.yml
@@ -0,0 +1,466 @@
1
+ Metadata-Version: 2.4
2
+ Name: phantomsignal
3
+ Version: 1.3.0
4
+ Summary: PhantomSignal :: Open-Source OSINT Intelligence Framework
5
+ Home-page: https://github.com/owlscan/phantomsignal
6
+ Author: packetsn1ffer
7
+ Project-URL: Homepage, https://phantomsignal.sh
8
+ Project-URL: Documentation, https://phantomsignal.sh
9
+ Project-URL: Bug Reports, https://github.com/owlscan/phantomsignal/issues
10
+ Project-URL: Source, https://github.com/owlscan/phantomsignal
11
+ Keywords: osint intelligence reconnaissance security pentest phantom signal
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Web Environment
14
+ Classifier: Intended Audience :: Information Technology
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Security
23
+ Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
24
+ Classifier: Topic :: System :: Networking :: Monitoring
25
+ Requires-Python: >=3.10
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: flask>=3.0.0
29
+ Requires-Dist: flask-socketio>=5.3.6
30
+ Requires-Dist: flask-sqlalchemy>=3.1.0
31
+ Requires-Dist: flask-login>=0.6.3
32
+ Requires-Dist: flask-wtf>=1.2.1
33
+ Requires-Dist: eventlet>=0.35.0
34
+ Requires-Dist: sqlalchemy>=2.0.0
35
+ Requires-Dist: alembic>=1.13.0
36
+ Requires-Dist: scrapy>=2.11.0
37
+ Requires-Dist: scrapy-splash>=0.9.0
38
+ Requires-Dist: scrapy-rotating-proxies>=0.6.2
39
+ Requires-Dist: scrapy-user-agents>=0.1.1
40
+ Requires-Dist: playwright>=1.40.0
41
+ Requires-Dist: httpx[asyncio]>=0.26.0
42
+ Requires-Dist: aiohttp>=3.9.0
43
+ Requires-Dist: requests>=2.31.0
44
+ Requires-Dist: urllib3>=2.1.0
45
+ Requires-Dist: shodan>=1.31.0
46
+ Requires-Dist: censys>=2.2.0
47
+ Requires-Dist: OTXv2>=1.5.12
48
+ Requires-Dist: dnspython>=2.4.0
49
+ Requires-Dist: python-whois>=0.9.4
50
+ Requires-Dist: ipwhois>=1.2.0
51
+ Requires-Dist: scapy>=2.5.0
52
+ Requires-Dist: cryptography>=42.0.0
53
+ Requires-Dist: bcrypt>=4.1.0
54
+ Requires-Dist: pyotp>=2.9.0
55
+ Requires-Dist: pydantic>=2.5.0
56
+ Requires-Dist: pandas>=2.1.0
57
+ Requires-Dist: numpy>=1.26.0
58
+ Requires-Dist: click>=8.1.0
59
+ Requires-Dist: rich>=13.7.0
60
+ Requires-Dist: typer>=0.9.0
61
+ Requires-Dist: reportlab>=4.0.8
62
+ Requires-Dist: openpyxl>=3.1.2
63
+ Requires-Dist: lxml>=5.0.0
64
+ Requires-Dist: stix2>=3.0.1
65
+ Requires-Dist: jinja2>=3.1.2
66
+ Requires-Dist: weasyprint>=61.0
67
+ Requires-Dist: python-dotenv>=1.0.0
68
+ Requires-Dist: pyyaml>=6.0.1
69
+ Requires-Dist: aiofiles>=23.2.1
70
+ Requires-Dist: python-dateutil>=2.8.2
71
+ Requires-Dist: humanize>=4.9.0
72
+ Requires-Dist: tldextract>=5.1.1
73
+ Requires-Dist: ua-parser>=0.18.0
74
+ Requires-Dist: user-agents>=2.2.0
75
+ Requires-Dist: fake-useragent>=1.4.0
76
+ Requires-Dist: geoip2>=4.8.0
77
+ Requires-Dist: geopy>=2.4.1
78
+ Requires-Dist: Pillow>=10.2.0
79
+ Requires-Dist: pytesseract>=0.3.10
80
+ Requires-Dist: aiofiles>=23.2.1
81
+ Requires-Dist: aiodns>=3.1.1
82
+ Requires-Dist: matplotlib>=3.8.0
83
+ Requires-Dist: pytest>=7.4.0
84
+ Requires-Dist: pytest-asyncio>=0.23.0
85
+ Requires-Dist: pytest-cov>=4.1.0
86
+ Requires-Dist: black>=23.12.0
87
+ Requires-Dist: isort>=5.13.2
88
+ Requires-Dist: flake8>=7.0.0
89
+ Requires-Dist: mypy>=1.8.0
90
+ Requires-Dist: pre-commit>=3.6.0
91
+ Dynamic: author
92
+ Dynamic: classifier
93
+ Dynamic: description
94
+ Dynamic: description-content-type
95
+ Dynamic: home-page
96
+ Dynamic: keywords
97
+ Dynamic: license-file
98
+ Dynamic: project-url
99
+ Dynamic: requires-dist
100
+ Dynamic: requires-python
101
+ Dynamic: summary
102
+
103
+ # PhantomSignal
104
+
105
+ ```
106
+ ____ __ _____ _ ____________ __ ___
107
+ / __ \/ / / / | / | / /_ __/ __ \/ |/ /
108
+ / /_/ / /_/ / /| | / |/ / / / / / / / /|_/ /
109
+ / ____/ __ / ___ |/ /| / / / / /_/ / / / /
110
+ /_/ /_/ /_/_/ |_/_/ |_/ /_/ \____/_/ /_/
111
+
112
+ _____ ___________ _____ __
113
+ / ___// _/ ____/ | / / | / /
114
+ \__ \ / // / __/ |/ / /| | / /
115
+ ___/ // // /_/ / /| / ___ |/ /___
116
+ /____/___/\____/_/ |_/_/ |_/_____/
117
+
118
+ >> OPEN-SOURCE OSINT INTELLIGENCE FRAMEWORK <<
119
+ "See everything. Leave no trace."
120
+ ```
121
+
122
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-00ff41?style=flat-square&logo=python)](https://python.org)
123
+ [![License: MIT](https://img.shields.io/badge/license-MIT-00f3ff?style=flat-square)](LICENSE)
124
+ [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows%20%7C%20Docker-b026ff?style=flat-square)]()
125
+ [![GitHub Stars](https://img.shields.io/github/stars/owlscan/phantomsignal?style=flat-square&color=00ff41)](https://github.com/owlscan/phantomsignal/stargazers)
126
+ [![Open Issues](https://img.shields.io/github/issues/owlscan/phantomsignal?style=flat-square&color=b026ff)](https://github.com/owlscan/phantomsignal/issues)
127
+ [![CI](https://img.shields.io/github/actions/workflow/status/owlscan/phantomsignal/ci.yml?branch=main&style=flat-square&label=CI&color=00ff41)](https://github.com/owlscan/phantomsignal/actions/workflows/ci.yml)
128
+ [![PyPI](https://img.shields.io/pypi/v/phantomsignal?style=flat-square&color=b026ff&logo=pypi&logoColor=white)](https://pypi.org/project/phantomsignal/)
129
+ [![Project Site](https://img.shields.io/badge/site-phantomsignal.sh-00f3ff?style=flat-square&logo=github)](https://phantomsignal.sh)
130
+ [![Changelog](https://img.shields.io/badge/changelog-view-00ff41?style=flat-square)](CHANGELOG.md)
131
+
132
+
133
+ ---
134
+
135
+ ## ⚡ What's New in v1.3.0
136
+
137
+ ### Rich CLI output panels
138
+ `phantomsignal scan <target>` now renders module-specific intelligence panels instead of a raw table — DNS records, subdomains, SPF/DMARC/DNSSEC status, an aligned port table with version/banner/risk, tech stack with security header grade A–F, exposed API resources, GeoIP/ASN intel, and a red anomaly callout. All panel right-borders are pinned to terminal width.
139
+
140
+ ### nmap integration
141
+ The port scanner now chains **nmap** (`-sV --version-intensity 7 -O --osscan-guess`) for full service-version detection and OS fingerprinting, with a transparent pure-Python async TCP fallback when nmap is absent or running without raw-socket privileges (macOS / Windows). The scan engine used and OS guess are shown inline in the port panel footer.
142
+
143
+ ### Expanded port coverage
144
+ `COMMON_PORTS` expanded from 56 → 99 ports covering low privileged services and high-numbered application ports — WinRM (5985/5986), Webmin (10000), InfluxDB (8086), Radmin (4899), and more. `DANGEROUS_PORTS` extended accordingly.
145
+
146
+ ### Web UI parity with CLI
147
+ The scan results page now renders each result type as structured output — port cards, DNS record tables, SPF/DMARC status, security header grade, TLS issuer/expiry, API endpoint status codes, IP geolocation with TOR/VPN flags — matching the CLI display. Quick Probe now runs all 5 default modules (`dns_recon`, `port_scan`, `tech_detect`, `api_hunt`, `intel`).
148
+
149
+ ---
150
+
151
+ ## 🎬 Demo
152
+
153
+ ### CLI — Ghost Run in action
154
+
155
+ ![CLI scan demo](https://raw.githubusercontent.com/phantomsignal/phantomsignal/main/docs/assets/demo.gif)
156
+
157
+ ### Web UI — Shadow Grid (Dashboard)
158
+
159
+ ![Dashboard](https://raw.githubusercontent.com/phantomsignal/phantomsignal/main/docs/assets/screenshot_dashboard.svg)
160
+
161
+ ### Web UI — Launch Ghost Run
162
+
163
+ ![Launch Ghost Run](https://raw.githubusercontent.com/phantomsignal/phantomsignal/main/docs/assets/screenshot_launch.svg)
164
+
165
+ ### Web UI — Scan Results
166
+
167
+ ![Scan results](https://raw.githubusercontent.com/phantomsignal/phantomsignal/main/docs/assets/screenshot_results.svg)
168
+
169
+ ### Web UI — Theme Options
170
+
171
+ PhantomSignal ships with two built-in UI themes, selectable via the **☀/🌙 toggle** in the top navigation bar. Your preference is saved automatically and persists across sessions.
172
+
173
+ | Theme | Description |
174
+ |-------|-------------|
175
+ | **Dark** *(default)* | Cyberpunk aesthetic — deep charcoal background, neon green/cyan/purple accents, matrix rain canvas, glowing owl logo |
176
+ | **Light** | "Phantom Dawn" — soft blue-grey background, muted accent palette, clean black ASCII logo, matrix rain disabled |
177
+
178
+ > **Asciinema recording:** Watch the full interactive demo on asciinema.org, or play it locally:
179
+ > ```bash
180
+ > pip install asciinema
181
+ > asciinema play https://raw.githubusercontent.com/phantomsignal/phantomsignal/main/docs/assets/demo.cast
182
+ > ```
183
+
184
+ [![asciicast](https://asciinema.org/a/1163488.svg)](https://asciinema.org/a/1163488)
185
+
186
+ ---
187
+
188
+ ## ⚡ What is PhantomSignal?
189
+
190
+ PhantomSignal is a **community-powered, open-source OSINT intelligence framework** built for security researchers, penetration testers, investigators, and enthusiasts. It combines web scraping, network reconnaissance, people intelligence aggregation, and threat analysis into a single cohesive platform.
191
+
192
+ > **LEGAL DISCLAIMER:** PhantomSignal is for **authorized security research, OSINT investigations, and educational purposes only**. Only scan targets you have explicit permission to test. You are solely responsible for compliance with all applicable laws. The developers assume NO liability for misuse.
193
+
194
+ ---
195
+
196
+ ## 🔥 Features
197
+
198
+ ### 🕷 Web Reconnaissance
199
+ - **Scrapy-powered** deep web crawler with JavaScript rendering support
200
+ - **Technology detection** — fingerprints 50+ technologies (CMS, frameworks, CDNs, WAFs)
201
+ - **API endpoint hunter** — discovers REST APIs, GraphQL, Swagger docs, admin panels, `.env` leaks
202
+ - **Security header analysis** with graded posture scoring
203
+ - **Email, phone, link, and comment harvesting**
204
+
205
+ ### 🌐 Network Intelligence
206
+ - **nmap-powered port scanner** — full service-version detection and OS fingerprinting via nmap (`-sV -O`); pure-Python async TCP fallback when nmap unavailable — no config required
207
+ - **Expanded port coverage** — 99 common ports by default, 1,000+ port profile, or full 65,535; covers WinRM, Webmin, InfluxDB, Docker API, Kubernetes, and more
208
+ - **DNS recon** — A/AAAA/MX/NS/TXT/SOA/CAA, zone transfer attempts, subdomain brute-force
209
+ - **Certificate transparency** via crt.sh — uncover subdomains via SSL history
210
+ - **SPF/DMARC analysis** — identify email spoofing vulnerabilities
211
+ - **Reverse DNS** and co-hosted domain discovery
212
+
213
+ ### 🔬 Intelligence APIs (30+ Integrations)
214
+
215
+ | Category | APIs |
216
+ |----------|------|
217
+ | **Network Scanning** | Shodan, Censys, ZoomEye, BinaryEdge |
218
+ | **Threat Intelligence** | VirusTotal, AbuseIPDB, GreyNoise, AlienVault OTX |
219
+ | **Email** | Hunter.io, HaveIBeenPwned, HaveIBeenPwned |
220
+ | **Domain/Web** | SecurityTrails, URLScan.io, WhoisXML, Local WHOIS |
221
+ | **Geolocation** | IPInfo.io |
222
+ | **People Search** | Pipl, FullContact, WhitePages, Spokeo, Clearbit |
223
+ | **Social** | GitHub, Twitter/X |
224
+ | **Custom** | Bring your own API via plugin architecture |
225
+
226
+ ### 👤 Shadow Profiler (People Intelligence)
227
+ LexisNexis-style identity aggregation from public records:
228
+ - Cross-correlates data from multiple people-search APIs
229
+ - Discovers emails, phones, addresses, relatives, employers
230
+ - Breach data correlation via HIBP and other sources
231
+ - Social media profile linking
232
+ - **Shadow Score** — digital exposure quantification (0-100)
233
+ - Social graph building and timeline reconstruction
234
+
235
+ ### 📦 Export Formats
236
+ | Format | Description |
237
+ |--------|-------------|
238
+ | **JSON** | Raw machine-readable data |
239
+ | **CSV** | Spreadsheet-compatible |
240
+ | **HTML** | Self-contained cyberpunk-styled report |
241
+ | **PDF** | Professional dossier via ReportLab |
242
+ | **XML** | Structured data |
243
+ | **XLSX** | Excel workbook |
244
+ | **STIX 2.1** | Threat intelligence sharing format |
245
+ | **Markdown** | Human-readable report |
246
+
247
+ All formats support **ZIP compression** and **AES-256-GCM encryption**.
248
+
249
+ ### 🌑 Ghost Mode
250
+ - Low-and-slow scanning profiles to minimize detection
251
+ - Identity rotation via user-agent spoofing
252
+ - Tor proxy integration (Docker compose profile: `ghost`)
253
+ - Configurable request jitter and delays
254
+
255
+ ### 🔔 Additional Features
256
+ - **Real-time live feed** — WebSocket-powered terminal during scans
257
+ - **Shadow Score** — composite risk/exposure scoring
258
+ - **Scheduled Phantoms** — recurring automated ghost runs
259
+ - **API health monitor** — dashboard showing configured APIs and rate limits
260
+ - **Light/Dark theme** — toggle between cyberpunk Dark mode and "Phantom Dawn" Light mode via the ☀/🌙 button; preference persisted in localStorage
261
+ - **Full REST API** — integrate PhantomSignal into your own toolchain
262
+ - **CLI interface** — `phantomsignal scan`, `phantomsignal profile`, `phantomsignal export`
263
+ - **Docker** — single-command deployment
264
+
265
+ ---
266
+
267
+ ## 🚀 Quick Start
268
+
269
+ ### Option 1: Docker (Recommended)
270
+ ```bash
271
+ git clone https://github.com/owlscan/phantomsignal
272
+ cd phantomsignal
273
+ docker-compose up -d
274
+ # Open http://localhost:5000
275
+ ```
276
+
277
+ ### Option 2: Manual Installation
278
+ ```bash
279
+ # Python 3.10+ required
280
+ git clone https://github.com/owlscan/phantomsignal
281
+ cd phantomsignal
282
+ pip install -e .
283
+ phantomsignal init
284
+ phantomsignal web --open-browser
285
+ ```
286
+
287
+ ### Option 3: CLI Scan
288
+ ```bash
289
+ # Quick probe
290
+ phantomsignal scan example.com --profile quick
291
+
292
+ # Full spectrum with export
293
+ phantomsignal scan 192.168.1.1 --type ip_recon --format html --output ./reports
294
+
295
+ # People intelligence
296
+ phantomsignal profile --email target@company.com --first-name John --last-name Doe
297
+ ```
298
+
299
+ ---
300
+
301
+ ## ⚙️ Configuration
302
+
303
+ ### Environment Variables (Recommended for API Keys)
304
+ ```bash
305
+ export SHODAN_API_KEY="your-shodan-key"
306
+ export VIRUSTOTAL_API_KEY="your-vt-key"
307
+ export HUNTER_API_KEY="your-hunter-key"
308
+ export HIBP_API_KEY="your-hibp-key"
309
+ export GREYNOISE_API_KEY="your-greynoise-key"
310
+ export IPINFO_TOKEN="your-ipinfo-token"
311
+ export ABUSEIPDB_API_KEY="your-abuseipdb-key"
312
+ export ALIENVAULT_API_KEY="your-otx-key"
313
+ export GITHUB_TOKEN="your-github-token"
314
+ export SECURITYTRAILS_API_KEY="your-st-key"
315
+ # See config/phantomsignal.yaml for full list
316
+ ```
317
+
318
+ ### Config File
319
+ Copy `config/phantomsignal.yaml` to `~/.phantomsignal/config.yaml` and customize.
320
+
321
+ ---
322
+
323
+ ## 🔌 Adding Custom APIs
324
+
325
+ PhantomSignal uses a plugin architecture. Adding a new intelligence source takes ~20 lines:
326
+
327
+ ```python
328
+ # phantomsignal/intel/apis/my_api.py
329
+ from phantomsignal.intel.apis.base import BaseIntelAPI, register_api, APICategory, APITier
330
+
331
+ @register_api
332
+ class MyAPI(BaseIntelAPI):
333
+ NAME = "myapi"
334
+ DESCRIPTION = "My custom intelligence source"
335
+ REQUIRES_KEY = True
336
+ TIER = APITier.FREE_LIMITED
337
+ CATEGORIES = [APICategory.NETWORK]
338
+ BASE_URL = "https://api.myservice.com/v1"
339
+ SIGN_UP_URL = "https://myservice.com/signup"
340
+
341
+ async def search(self, query: str, **kwargs):
342
+ data = await self._get(
343
+ f"{self.BASE_URL}/search",
344
+ params={"q": query, "key": self._api_key}
345
+ )
346
+ return [self._wrap_result("my_result", data)]
347
+ ```
348
+
349
+ Then import it in `phantomsignal/intel/orchestrator.py` and it auto-registers.
350
+
351
+ ---
352
+
353
+ ## 🏗 Architecture
354
+
355
+ ```
356
+ phantomsignal/
357
+ ├── core/ — Engine, config, database, models
358
+ ├── scrapers/ — Scrapy crawler, tech detector, port scanner, API hunter, DNS recon
359
+ ├── intel/
360
+ │ ├── apis/ — 30+ API integrations (plugin architecture)
361
+ │ └── people/ — People intelligence aggregation
362
+ ├── exporters/ — JSON/CSV/PDF/HTML/XML/XLSX/STIX + crypto wrapper
363
+ └── web/
364
+ ├── routes/ — Flask blueprints (dashboard, scans, intel, settings, export, REST API)
365
+ ├── templates/ — Cyberpunk Jinja2 templates
366
+ └── static/ — CSS (cyberpunk), JS (matrix, terminal, app)
367
+ ```
368
+
369
+ ---
370
+
371
+ ## 🛡 REST API
372
+
373
+ ```bash
374
+ # Create a scan
375
+ curl -X POST http://localhost:5000/api/v1/scans \
376
+ -H "Content-Type: application/json" \
377
+ -d '{"target": "example.com", "scan_type": "web_recon"}'
378
+
379
+ # Get results
380
+ curl http://localhost:5000/api/v1/scans/{scan_id}
381
+
382
+ # List all APIs
383
+ curl http://localhost:5000/api/v1/apis
384
+
385
+ # Health check
386
+ curl http://localhost:5000/api/v1/health
387
+ ```
388
+
389
+ ---
390
+
391
+ ## 🤝 Contributing
392
+
393
+ PhantomSignal thrives on community contributions. Ways to help:
394
+
395
+ 1. **Add API integrations** — Follow the plugin pattern above
396
+ 2. **Improve detection signatures** — Expand `tech_detector.py`
397
+ 3. **Bug reports** — [GitHub Issues](https://github.com/owlscan/phantomsignal/issues)
398
+ 4. **Documentation** — Improve the wiki
399
+ 5. **Translations** — Internationalize the UI
400
+
401
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Please also review our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).
402
+
403
+ ---
404
+
405
+ ## 📖 Documentation
406
+
407
+ - **[Usage Guide](docs/USAGE.md)** — full walkthroughs, usage scenarios, CLI reference, and per-platform troubleshooting (Linux / macOS / Windows / Docker)
408
+
409
+ ---
410
+
411
+ ## ⚠️ Legal & Ethics
412
+
413
+ PhantomSignal is a dual-use tool. Operators are responsible for:
414
+ - Obtaining explicit authorization before scanning any system
415
+ - Complying with applicable laws (CFAA, GDPR, CCPA, ECPA, local laws)
416
+ - Respecting privacy and data protection regulations
417
+ - Not using this tool for harassment, stalking, or unauthorized surveillance
418
+
419
+ **The developers provide this software as-is with no warranty. Misuse is your responsibility.**
420
+
421
+ ---
422
+
423
+ ## 🏷 Topics
424
+
425
+ [![osint](https://img.shields.io/badge/osint-00ff41?style=flat-square)](https://github.com/topics/osint)
426
+ [![security](https://img.shields.io/badge/security-00f3ff?style=flat-square)](https://github.com/topics/security)
427
+ [![python](https://img.shields.io/badge/python-00f3ff?style=flat-square)](https://github.com/topics/python)
428
+ [![hacking](https://img.shields.io/badge/hacking-00ff41?style=flat-square)](https://github.com/topics/hacking)
429
+ [![cybersecurity](https://img.shields.io/badge/cybersecurity-b026ff?style=flat-square)](https://github.com/topics/cybersecurity)
430
+ [![reconnaissance](https://img.shields.io/badge/reconnaissance-00ff41?style=flat-square)](https://github.com/topics/reconnaissance)
431
+ [![recon](https://img.shields.io/badge/recon-00f3ff?style=flat-square)](https://github.com/topics/recon)
432
+ [![penetration-testing](https://img.shields.io/badge/penetration--testing-b026ff?style=flat-square)](https://github.com/topics/penetration-testing)
433
+ [![ethical-hacking](https://img.shields.io/badge/ethical--hacking-00ff41?style=flat-square)](https://github.com/topics/ethical-hacking)
434
+ [![bug-bounty](https://img.shields.io/badge/bug--bounty-00f3ff?style=flat-square)](https://github.com/topics/bug-bounty)
435
+ [![information-gathering](https://img.shields.io/badge/information--gathering-b026ff?style=flat-square)](https://github.com/topics/information-gathering)
436
+ [![threat-intelligence](https://img.shields.io/badge/threat--intelligence-00ff41?style=flat-square)](https://github.com/topics/threat-intelligence)
437
+ [![security-tools](https://img.shields.io/badge/security--tools-00f3ff?style=flat-square)](https://github.com/topics/security-tools)
438
+ [![network-scanner](https://img.shields.io/badge/network--scanner-b026ff?style=flat-square)](https://github.com/topics/network-scanner)
439
+ [![dns-recon](https://img.shields.io/badge/dns--recon-00ff41?style=flat-square)](https://github.com/topics/dns-recon)
440
+ [![infosec](https://img.shields.io/badge/infosec-00f3ff?style=flat-square)](https://github.com/topics/infosec)
441
+ [![flask](https://img.shields.io/badge/flask-b026ff?style=flat-square)](https://github.com/topics/flask)
442
+ [![security-research](https://img.shields.io/badge/security--research-00ff41?style=flat-square)](https://github.com/topics/security-research)
443
+ [![footprinting](https://img.shields.io/badge/footprinting-00f3ff?style=flat-square)](https://github.com/topics/footprinting)
444
+ [![automation](https://img.shields.io/badge/automation-b026ff?style=flat-square)](https://github.com/topics/automation)
445
+
446
+ ---
447
+
448
+ ## 🤝 Community
449
+
450
+ | Document | Description |
451
+ |----------|-------------|
452
+ | [Code of Conduct](CODE_OF_CONDUCT.md) | Community standards and expectations |
453
+ | [Contributing Guidelines](CONTRIBUTING.md) | How to contribute to PhantomSignal |
454
+ | [Security Policy](SECURITY.md) | Reporting vulnerabilities responsibly |
455
+ | [License](LICENSE) | MIT License terms |
456
+
457
+ ---
458
+
459
+ ## 📜 License
460
+
461
+ MIT License — see [LICENSE](LICENSE)
462
+
463
+ ---
464
+
465
+ *Built with questionable amounts of caffeine. "See everything. Leave no trace."*
466
+ *Some ghosts leave no trace. This one left commits. — Claude*