Skip to content

Home

Jump to bottom
MrP edited this page Mar 6, 2026 · 4 revisions

Welcome to the ThreatSight wiki!

The aim of this wiki is to give understanding about the project in more detailed way , even if you are a beginner and trying to hands on this , this will give you the clear understanding how to use it and what is the vision behind this tool

ThreatSight Wiki

Table of Contents

  1. Overview
  2. Getting Started
  3. Core Features
  4. Architecture
  5. Usage Guide
  6. Contributing
  7. Security & Ethics
  8. Roadmap
  9. FAQ
  10. Troubleshooting

Overview

What is ThreatSight?

ThreatSight is an intelligent network security scanner that combines Nmap's powerful scanning capabilities with automated analysis and risk assessment. It transforms raw network scan data into actionable security insights.

Why ThreatSight?

While Nmap provides excellent network discovery, ThreatSight adds:

  • Automated vulnerability correlation
  • Risk prioritization
  • Actionable reporting
  • Multi-threaded efficiency

Target Audience

  • Security Analysts: Quick network assessments
  • Penetration Testers: Reconnaissance automation
  • DevOps Teams: Pre-deployment security checks
  • Cybersecurity Students: Learning tool for network scanning

Getting Started

System Requirements

  • Python 3.8+
  • Nmap 7.93+
  • 2GB+ RAM
  • Network interface with packet injection capability

Installation Steps

Step 1: Install Nmap

# Ubuntu/Debian
sudo apt update && sudo apt install nmap

# macOS
brew install nmap

# Windows
# Download from https://nmap.org/download.html

Step 2: Clone ThreatSight

git clone https://github.com/yourusername/ThreatSight.git
cd ThreatSight

Step 3: Install Python Dependencies

pip install -r requirements.txt

Step 4: Verify Installation

python3 threat_sight.py --test

Quick Start Example

# Single host scan
python3 threat_sight.py

# Multiple hosts scan
python3 threat_sight.py --targets hosts.txt

Core Features

1. Multi-Protocol Scanning

Scan Type Command Use Case
SYN ACK -sS Stealthy TCP port discovery
UDP Scan -sU UDP service detection
Comprehensive -sS -sV -O -A Full service and OS fingerprinting

2. Threaded Performance

ThreatSight uses concurrent scanning to dramatically reduce scan times:

# Without threading (sequential)
Host 1: 45s
Host 2: 45s
Host 3: 45s
Total: 135s

# With ThreatSight (10 threads)
Hosts 1-10: 45s
Total: 45s (70% faster)

3. Intelligent Analysis

# Example output enhancement
Nmap Output:
Port 80/tcp open http

ThreatSight Output:
Port 80/tcp open http
├─ Service: Apache 2.4.49
├─ CVE-2021-41773 (CVSS 9.8)
└─ Action: Upgrade to Apache 2.4.51+

4. Color-Coded Interface

  • 🔴 Red: Errors, critical vulnerabilities
  • 🟡 Yellow: Warnings, medium risk
  • 🟢 Green: Success, low risk
  • 🔵 Blue: Information, scan progress

Architecture

Project Structure

ThreatSight/
├── core/
│   ├── scanner.py          # Main scanning logic
│   ├── utils.py            # Helper functions
│   └── __init__.py
├── tests/
│   ├── test_scanner.py
│   └── __init__.py
├── config.yaml             # Configuration
├── threat_sight.py         # Main executable
├── requirements.txt
└── README.md

Data Flow

graph LR
    A[User Input] --> B[IP Validation]
    B --> C[Host Discovery]
    C --> D[Threaded Scanning]
    D --> E[Result Analysis]
    E --> F[Risk Scoring]
    F --> G[Report Generation]
Loading

Key Components

  1. Scanner Module: Handles all Nmap interactions
  2. Thread Manager: Orchestrates concurrent scans
  3. Result Parser: Extracts meaningful data from Nmap output
  4. Risk Engine: Prioritizes findings (future release)

📖 Usage Guide

Basic Commands

Interactive Mode

python3 threat_sight.py
Enter IP (or 'q' to exit): 192.168.1.1
Enter port range (1-1024): 1-1000
Choose scan type (1:SYN/2:UDP/3:Full): 1

Batch Mode

python3 threat_sight.py --file targets.txt --ports 20-443 --type syn

Continuous Monitoring

python3 threat_sight.py --continuous --interval 3600

Scan Examples

1. Quick Network Survey

# Scan local network for common services
python3 threat_sight.py --target 192.168.1.0/24 --ports 22,80,443,3389

2. Compliance Check

# Verify only required ports are open
python3 threat_sight.py --target server.example.com --verify-ports 22,443

3. Service Discovery

# Find all web servers
python3 threat_sight.py --target 10.0.0.0/16 --find-service http

Output Formats

ThreatSight supports multiple output formats:

# JSON for automation
python3 threat_sight.py --output json > scan_results.json

# CSV for spreadsheets
python3 threat_sight.py --output csv > scan_results.csv

# HTML for reports
python3 threat_sight.py --output html --report report.html

Contributing

How to Contribute

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests
  5. Submit a pull request

Development Setup

# Clone with SSH
git clone git@github.com:yourusername/ThreatSight.git

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

Coding Standards

  • Follow PEP 8
  • Use type hints
  • Write docstrings
  • Add unit tests for new features

Project Labels

Label Purpose
good first issue Beginner-friendly tasks
enhancement New features
bug Issues to fix
documentation Docs improvement

Security & Ethics

Legal Considerations

Using ThreatSight responsibly:

Allowed Uses

  • Scanning your own networks
  • Authorized penetration testing
  • Educational environments (with supervision)
  • Security research (with permission)

Prohibited Uses

  • Scanning networks you don't own
  • Violating terms of service
  • Disrupting services
  • Data theft or intrusion

Compliance

ThreatSight helps with:

  • PCI DSS: Regular vulnerability scanning
  • HIPAA: Network security assessments
  • GDPR: Data protection verification

Best Practices

  1. Get Written Permission: Always have authorization
  2. Schedule Scans: Avoid peak hours
  3. Limit Bandwidth: Use --max-rate option
  4. Document Results: Keep logs for audits

Roadmap

Phase 1: Core Scanner (Current)

  • Basic Nmap wrapper
  • Multi-threaded scanning
  • Color-coded output
  • Port range validation

Phase 2: Vulnerability Intelligence (Q2 2024)

  • CVE database integration
  • CVSS scoring
  • Exploitability assessment

Phase 3: Risk Management (Q3 2024)

  • Asset criticality scoring
  • Compliance mapping
  • Remediation guidance

Phase 4: Enterprise Features (Q4 2024)

  • API interface
  • SIEM integration
  • Scheduled scanning

❓ FAQ

Q: Is ThreatSight a replacement for Nmap?

A: No, ThreatSight enhances Nmap by adding analysis and automation layers. It uses Nmap as its scanning engine.

Q: Why Python instead of native Nmap scripts?

A: Python provides better threading, data processing, and integration capabilities than NSE (Nmap Scripting Engine).

Q: How many hosts can I scan simultaneously?

A: Default is 10 threads. Adjust with --threads flag:

python3 threat_sight.py --threads 20

Q: Can ThreatSight scan IPv6 addresses?

A: Yes, if Nmap supports it on your system:

python3 threat_sight.py --target 2001:db8::1

Q: How do I save scan results?

A: Use output redirection:

python3 threat_sight.py > scan_results.txt

Q: What if a scan hangs?

A: Set timeout with --timeout:

python3 threat_sight.py --timeout 30  # 30 seconds per host

Troubleshooting

Common Issues

Issue: "Nmap not found"

Solution:

which nmap  # Check if installed
export PATH=$PATH:/usr/local/nmap/bin  # Add to PATH if needed

Issue: "Permission denied" for SYN scans

Solution:

# Run with sudo
sudo python3 threat_sight.py

# Or set capabilities
sudo setcap cap_net_raw,cap_net_admin+eip $(which nmap)

Issue: Slow UDP scans

Solution: Use rate limiting:

python3 threat_sight.py --max-rate 100  # 100 packets/second

Issue: Incomplete scan results

Solution: Increase timeouts:

python3 threat_sight.py --scan-delay 5 --host-timeout 300

Performance Optimization

Scenario Optimization
Large networks --threads 50
Slow targets --max-retries 3
Noisy networks --defeat-rst-ratelimit
Firewalled hosts -Pn (skip ping)

Debug Mode

Enable verbose output for troubleshooting:

python3 threat_sight.py --debug --log-level DEBUG

Support

Getting Help

  1. GitHub Issues: Report bugs or request features
  2. Wiki: Check this documentation first
  3. Community: Join discussions

Reporting Vulnerabilities

Email : DO NOT post security issues publicly.

Stay Updated

  • Star the GitHub repository
  • Watch for releases
  • Follow project updates

License

ThreatSight is released under the MIT License. See LICENSE for details.

Last Updated: Jan 2026
Version: 1.0.0
Author: Parshant Kumar

Clone this wiki locally