🔍 TraceScope

OSINT, Network Intelligence, and Security Utility Suite
Modular reconnaissance toolkit for authorized security research and cybersecurity education

v2.0 - CLI Edition | MIT License
Purpose-built for intelligence gathering, network analysis, and breach investigation

---

📑 Table of Contents

• Legal Notice
• Core Capabilities
• Quick Start
• Configuration
• Usage
• Use Cases
• Contributing
• Support
• FAQ
• License

---

This tool is only for lawful use with proper authorization. Unauthorized access to computer systems is illegal.

• ✅ Authorized pentests and security assessments

• ✅ Personal research on your own systems

• ✅ Cybersecurity education in controlled lab environments

• ✅ OSINT research on publicly available data

• ❌ Unauthorized network scanning

• ❌ Hacking or unauthorized access

• ❌ Privacy violations or harassment

You are solely responsible for your use of this tool. The authors assume no liability.

---

✨ Core Capabilities

🌐 Network & Infrastructure Intelligence

• IP Geolocation - Pinpoint geographic location from IP addresses
• Public IP Detection - Identify your external IP with ISP and region data
• ICMP Ping Testing - Verify host reachability and latency
• TCP Port Scanning - Check service availability and connectivity
• IP Reputation Analysis - Cross-reference against AbuseIPDB for malicious activity patterns

🕵️ OSINT & Intelligence Gathering

• Phone Number Footprinting - Locate phone numbers across public records
• Username Reconnaissance - Track usernames across multiple platforms
• Email Breach Lookup - Cross-reference against Have I Been Pwned (HIBP) database
• Geographic Intelligence - ZIP code and location-based research

📱 Social Media Intelligence

• Instagram Open-Source Analysis - Public profile data collection (non-scraping)
• Cross-Platform Username Analysis - Correlate identity across services

---

🎯 Features At a Glance

Feature	Free	Requires API	Use Case
IP Geolocation	✅	Optional (IPinfo)	Find geographic location of IP
IP Reputation	✅	Optional (AbuseIPDB)	Check if IP is malicious/dangerous
Ping Testing	✅	❌	Verify host reachability
Port Scanning	✅	❌	Check if ports are open
Username Lookup	✅	❌	Find username across platforms
Email Breach Check	⚠️	Optional (HIBP)	Check if email in data breaches
Phone Lookup	✅	❌	Research phone numbers
Instagram Analysis	✅	❌	Extract public profile data
ZIP Code Research	✅	❌	Geographic intelligence

⚠️ = Free tier available, paid tiers unlock more features

---

📋 Prerequisites

• Python 3.8+ (3.11+ recommended for performance)
• Internet connection (required for API calls)
• API keys (optional but unlocks enhanced lookups)
  • AbuseIPDB - Enhanced IP reputation
  • Have I Been Pwned - Breach database access
  • IPinfo.io - Premium geolocation

Install dependencies:

pip install -r requirements.txt

---

🛠️ Quick Start (Windows)

git clone https://github.com/xdrew87/TraceScope.git
cd TraceScope
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python tracescope.py

🛠️ Quick Start (Linux/macOS)

git clone https://github.com/xdrew87/TraceScope.git
cd TraceScope
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 tracescope.py

---

⚙️ Configuration

Create a configuration file in the project root:

{
  "abuseipdb_api_key": "your_key_here",
  "hibp_api_key": "your_key_here",
  "ipinfo_token": "your_token_here"
}

Security Practices:

• API keys are optional—most features work without them
• Never commit config.json to version control
• Store keys in environment variables for production use
• Rotate API keys regularly if exposed
• Use restricted API permissions (IP allowlisting if available)

Add to .gitignore:

config.json
.env
venv/
__pycache__/
*.pyc

Obtaining API Keys:

• AbuseIPDB: https://www.abuseipdb.com/api
• HIBP: https://haveibeenpwned.com/API/
• IPinfo: https://ipinfo.io/

---

🚀 Usage

Start the CLI menu:

python tracescope.py

Then select a module from the interactive menu.

Common Workflows:

1. Network Reconnaissance

   • Verify target IP geolocation
   • Check IP reputation for known threats
   • Test connectivity (ICMP/TCP)

2. Identity Investigation

   • Username footprint across platforms
   • Email breach status check
   • Phone number research

3. OSINT Enrichment

   • Correlate public data from multiple sources
   • Build intelligence profiles
   • Verify collected data accuracy

Tips:

• Rate limits apply to free API tiers—space out requests
• Some data requires verified API keys
• Use responsibly during assessments to avoid detection
• Log results for documentation

---

⌨️ Command Reference

While TraceScope uses an interactive menu, here's what you can do:

# Start interactive CLI
python tracescope.py

# Then select options (examples):
# 1. Network Intelligence → IP Geolocation → Enter IP
# 2. OSINT → Username Lookup → Enter username
# 3. OSINT → Breach Check → Enter email
# 4. Social → Instagram Analysis → Enter handle

Common Investigation Workflows

Workflow: "I found an IP in my logs. What is it?"
→ Start TraceScope
→ Network Intelligence → IP Geolocation → Enter IP
→ Network Intelligence → IP Reputation → Enter IP
→ Document results

Workflow: "Is my email in a breach?"
→ Start TraceScope
→ OSINT → Breach Check → Enter your email
→ Review results
→ Change passwords if found

Workflow: "Verify a username across platforms"
→ Start TraceScope
→ OSINT → Username Lookup → Enter username
→ Review all platforms where it appears

---

In-Scope Authorization Required:

• 🔍 Authorized Penetration Testing

  • Intelligence gathering phase of authorized assessments
  • Target validation and reconnaissance
  • Network surface discovery

• 🏫 Cybersecurity Education

  • Lab environments and CTF competitions
  • Academic research and coursework
  • Security training scenarios

• 🛡️ Incident Response

  • IP intelligence during breach investigations
  • Threat actor infrastructure mapping
  • Email compromise validation (internal databases)

• 🔐 Personal Security Hygiene

  • Check if your email is in known breaches
  • Monitor your digital footprint
  • Verify public information accuracy

What NOT to Use This For:

• ❌ Unauthorized network scanning
• ❌ Collecting data on individuals without consent
• ❌ Harassment or stalking (even with "public" data)
• ❌ Circumventing access controls or ToS

---

⚠️ Known Limitations & Disclaimers

• Rate Limits: Free API tiers have daily/monthly caps. Space out bulk queries.
• Data Availability: Not all IPs/emails/usernames have public data available. Negative results are normal.
• API Accuracy: Third-party data sources may be outdated or incomplete.
• False Positives: IP reputation scores may flag legitimate services; verify findings independently.
• Geographic Data: IP geolocation is approximate (±100km accuracy typical).
• Instagram: Limited to public data only; private accounts cannot be analyzed.
• No Logging: Results are not persisted—capture output manually if needed.
• Stateless: TraceScope does not store target history or create databases.

---

🤝 Contributing

Contributions are welcome. Please follow these guidelines:

• Code Quality

  • Follow PEP 8 style guidelines
  • Add docstrings for new functions
  • Keep modules focused on single responsibility
  • Include error handling for API failures

• Security

  • Don't hardcode API keys or credentials
  • Validate user input before API calls
  • Document any permission requirements
  • Consider rate limiting in your code

• Modules

  • New modules should be self-contained
  • Document required API keys
  • Include usage examples
  • Test with and without API keys

• Documentation

  • Update README with new features
  • Include use case examples
  • Document any breaking changes
  • Add references to relevant APIs/services

---

📞 Support & Contact

• Discord: galmx
• GitHub Issues: Report bugs and feature requests
• Email: galmx@osintintelligence.xyz

Community:

• Join OSINT and security research communities
• Share findings responsibly
• Participate in authorized assessments

---

❓ FAQ

General Questions

Q: Do I need API keys to use TraceScope?
A: No. Most features work without API keys. Keys are optional and unlock enhanced functionality like IP reputation scoring and breach database access.

Q: Is this tool legal to use?
A: Yes, for authorized uses: penetests with permission, education, personal research, OSINT on public data. See Legal Notice for what's NOT allowed.

Q: What Python versions are supported?
A: Python 3.8+ (3.11+ recommended). Test with python --version.

Q: Can I use this on Windows/Mac/Linux?
A: Yes. TraceScope runs on all three platforms. See Quick Start for OS-specific commands.

Q: How do I report security issues?
A: Email galmx@osintintelligence.xyz (see SECURITY.md for responsible disclosure).

Technical Questions

Q: What if I hit API rate limits?
A: Rate limits reset daily (usually at UTC midnight). Free tiers have limits shown in docs/API_KEYS.md. Consider upgrading for higher limits.

Q: Can I run TraceScope in batch mode (multiple targets)?
A: Currently CLI is interactive. For batch: create a script that calls tracescope functions programmatically (advanced usage).

Q: How do I verify my config.json is correct?
A: Run: python -c "import json; json.load(open('config.json')); print('✓ Valid')"

Q: Does TraceScope leave traces or logs?
A: No. Results are printed to console but not saved by default. You can redirect output: python tracescope.py > results.txt

Q: Can I use this in closed networks (no internet)?
A: No. TraceScope requires internet to reach APIs. Some basic functions may work offline (depends on implementation).

Troubleshooting

Q: "ModuleNotFoundError: No module named 'requests'"
A: Run: pip install -r requirements.txt in your venv.

Q: API returns "Unauthorized" or "Invalid key"
A: Check config.json for typos, whitespace, or expired keys. Re-copy from API provider.

Q: "Connection refused" or timeout errors
A: Check internet connection. Some APIs may be temporarily down—try again later.

Q: Results look empty or incomplete
A: Some data may not be available for all targets. This is normal (not all IPs have reputation data, not all emails in breaches, etc.).

---

🔧 Verification & Testing

Installation Verification

After setup, verify everything works:

# 1. Check Python version
python --version
# Expected: Python 3.8+

# 2. Check venv is active (should see (venv) in prompt)
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

# 3. Check dependencies
pip list | grep -E "requests|json"
# Should list relevant packages

# 4. Verify config.json
python -c "import json; json.load(open('config.json')); print('✓ Config valid')"

# 5. Test script syntax
python -m py_compile tracescope.py
# No output = success

# 6. Run TraceScope
python tracescope.py
# Should show interactive menu

Quick API Test

# Once inside TraceScope, try these (no credentials needed):
# 1. Check your public IP (uses ipify API, no key needed)
# 2. Geolocate 8.8.8.8 (Google DNS - good test target)
# 3. Test username lookup with a common username

---

MIT License - See LICENSE file for details

You are free to:

• ✅ Use commercially
• ✅ Modify and distribute
• ✅ Use privately

With the condition:

• 📋 Include the license and copyright notice

---

🙏 Credits

• GhostTrack - Phone lookup methodology inspiration
• OSINT Community - Best practices and research techniques
• Security Researchers - Bug reports and feature ideas

---

⭐ If TraceScope helps your research or assessments, please star the repo!