camsniff 1.0.5

IP camera reconnaissance toolkit: Python core + web backend

CamSniff - IP Camera Reconnaissance Tool

• Introduction
• Features
• Dependencies
• Installation
• Usage
• Output and Reporting
• Configuration
• Troubleshooting
• Contributing
• Acknowledgments
• License

---

Release 1.0.4 Highlights

This release focuses on backend modernization and internal consistency:

• Introduced a new FastAPI backend (camsniff-web) with:
  • /health readiness probe
  • /events endpoint (JSONL tail with filtering by level/event)
  • WebSocket streaming (/ws) for real-time scan events with backlog replay
• Centralized path handling via python_core/config.py (single source for output/log/database paths; respects CAMSNIFF_OUTPUT).
• Removed duplicate legacy logging functions and tightened JSONL event logging contract.
• Added initial Python tests for configuration and backend endpoints.
• Debian packaging updated (added FastAPI & Uvicorn runtime dependencies).
• Makefile improvements: added pytest, quicktest, package-check, lint, and format targets.

Version Note: Earlier references to 2.0.x were provisional; the project is formally continuing at 1.0.4 to keep alignment with Debian packaging history while the new backend stabilizes.

---

Introduction

CamSniff is a powerful reconnaissance tool for discovering, analyzing and displaying IP cameras and IoT devices.

• It performs device fingerprinting, service enumeration, endpoint detection, snapshot capture for AI analysis, and vulnerability scanning.

• The built-in web interface provides real-time visualizations, including camera feeds, network maps, geographic locations, and alerts.

Primarily built for Debian-based Linux distributions, CamSniff auto-installs dependencies on first run with admin privileges.

• It uses local datasets for RTSP paths (data/rtsp_paths.csv) and CVEs (data/cves) by default, avoiding network downloads. Radio-based features (Wi-Fi, BLE, Zigbee, Z-Wave) may not work on WSL due to hardware limitations.

Disclaimer: This tool is for educational and research purposes only. Use responsibly and with explicit permission. The authors are not liable for any misuse.

Features

• Device Fingerprinting: Supports major brands like Hikvision, D-Link, TP-Link, Samsung, Panasonic, Dahua, Axis, Vivotek, and Foscam.
• Network Scanning: Uses fping, arp-scan, masscan, nmap, and onesixtyone for host discovery and port scanning.
• Protocol Handling: RTSP, HTTP (MJPEG/HLS), CoAP, RTMP, and MQTT.
• IoT Enumeration: UPnP/SSDP, mDNS, BLE, Zigbee/Z-Wave, Wi-Fi OUI lookup, and network topology mapping.
• Web Interface: Flask-based dashboard for camera feeds, topology diagrams, maps, alerts, live screenshots, and timelines.
• Reporting: Text/JSON summaries, alert logs, and optional Nmap vulnerability scans.
• Credential Brute-Forcing: Hydra and Medusa with custom wordlists; Gobuster for directory brute-forcing.
• AI Analysis: OpenCV for detecting infrared, motion, and brightness in snapshots.
• Multi-View Support: Mosaic layouts with overlays for multiple cameras.
• Automation: Auto/quiet modes, subnet targeting, stealth delays, and plugin extensibility.

Dependencies

CamSniff depends on various open-source tools and libraries, auto-installed on first run with sudo. Review their licenses individually.

Core Utilities 🛠

• Bash - Scripting shell
• curl - Data transfer
• jq - JSON processing
• netcat - Network utility
• FFmpeg - Multimedia handling
• FFplay - Media playback

Network Scanning 🔍

• fping - ICMP ping
• masscan - Fast port scanner
• Nmap - Network mapping
• Hydra - Brute-force login
• tcpdump - Packet capture
• tshark - Protocol analysis
• arp-scan - ARP scanning

Python Components 🐍

• Python 3 - Core language
• venv - Virtual environments
• pip - Package manager
• OpenCV - Computer vision
• Flask - Web framework

Additional Tools 🧰

• Gobuster - Directory enumeration
• Medusa - Brute-force
• onesixtyone - SNMP scanner
• libcoap - CoAP client
• rtmpdump - RTMP streaming

IoT Discovery 📡

• Avahi - mDNS/DNS-SD
• BlueZ - Bluetooth/BLE
• NetworkManager - Wi-Fi tools (iw, nmcli)

Recommended: avahi-utils, bluez, bluez-tools, wireless-tools, iw, network-manager.

Installation

Recommended: DEB Package

Download from releases:

sudo apt install ./camsniff*.deb

Or:

sudo gdebi ./camsniff*.deb

Installs /usr/bin/camsniff and /etc/camsniff/camcfg.json.

From Source

1. Clone:

   git clone https://github.com/John0n1/CamSniff.git
   cd CamSniff
   

2. Make executable:

   chmod +x *.sh
   

Python-Only (via pip)

For CLI probes and web backend:

pip install camsniff

Provides camsniff-cli and camsniff-web. Does not include full Bash orchestrator or system tools.

Python Extras Quick Reference

Use Case	Command
Core CLI + FastAPI backend	pip install camsniff[web]
Add AI / CV / snapshot analysis	pip install camsniff[ai]
Developer tooling (lint, tests)	pip install camsniff[dev]

Multiple groups (example):

pip install 'camsniff[web,ai,dev]'

Usage

Run with sudo for full functionality:

sudo ./camsniff.sh

Or if installed:

sudo camsniff

Options:

• -y, --yes: Skip prompts
• -q, --quiet: Less verbose
• -a, --auto: Fully automated
• -t, --target <subnet>: e.g., 192.168.1.0/24
• -h, --help: Show help

Wireless features require compatible hardware; disable in config if unsupported.

Project Structure

├── camsniff.sh          # Main entry point script
├── core/                # Core functionality scripts
│   ├── env_setup.sh     # Environment configuration
│   ├── scan_analyze.sh  # Scanning and analysis logic
│   ├── setup.sh         # Initial setup functions
│   ├── cleanup.sh       # Cleanup operations
│   ├── install_deps.sh  # Dependency installation
│   ├── iot_enumerate.sh # IoT device enumeration
│   ├── webui.sh         # Web interface launcher
│   └── doctor.sh        # System diagnostics
├── python_core/         # Python modules and scripts
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # Command-line interface
│   ├── web_backend.py   # FastAPI backend
│   ├── ai_analyze.py    # AI analysis functions
│   └── cve_quick_search.py # CVE search functionality
├── tests/               # Test suite
│   ├── test_*.sh        # Individual test scripts
│   └── ...
├── data/                # Data files (RTSP paths, wordlists)
├── web/                 # Web interface files
└── debian/              # Debian packaging files

Output and Reporting

Results saved in output/results_YYYYMMDD_HHMMSS/:

• logs/: Scan logs
• screenshots/: Annotated snapshots
• reports/:
  • summary_YYYYMMDD_HHMMSS.txt/json: Overviews
  • cameras.json: Device details (IPs, protocols, etc.)
  • alerts.log: Events
  • analysis_IP.json: AI results per device
  • mdns_services.txt, ssdp_devices.txt, ble_scan.txt: IoT data
  • topology.json: Network map
  • logs/nmap_vuln_*.txt: Vulnerability scans (if enabled)

Web Interface: Start with ./core/webui.sh or camsniff-web. Access at http://localhost:8088 (configurable via CAMSNIFF_WEB_PORT).

Updated Event Log Schema (JSONL):

{"ts":"2025-01-01T12:00:00.123Z","event_type":"camera_found","level":"info","category":"camera","payload":{"ip":"192.168.1.10","port":554,"protocol":"rtsp","url":"rtsp://..."}}

Command-line emission example:

python -m python_core.logging_utils emit --event-type camera_found \
  --category camera \
  --payload '{"ip":"192.168.1.10","port":554}'

Listing recent events:

python -m python_core.logging_utils list --limit 5

Tailing (follow mode):

python -m python_core.logging_utils tail --follow

Field Semantics:

• ts: ISO8601 UTC timestamp with millisecond precision.
• event_type: Machine-friendly event key (e.g. camera_found, scan_start, vuln_detected).
• level: info | warn | error | debug (semantic severity, not tied to Python logging module).
• category: Optional coarse grouping (scan, camera, vuln, system, auth, stream).
• message: Optional human-readable summary for quick display.
• payload: Arbitrary structured object; avoid duplicating top-level fields.

Backward Compatibility:

• The backend /events endpoint already reads only event_type; older event keys will not appear unless translated. Shell emission harmonization is in progress (1.0.5 milestone).

Configuration

Edit camcfg.json (defaults: /etc/camsniff/camcfg.json):

{
  "sleep_seconds": 45,
  "nmap_ports": "1-65535",
  "masscan_rate": 20000,
  "hydra_rate": 16,
  "max_streams": 4,
  "cve_github_repo": "",
  "cve_cache_dir": "data/cves",
  "cve_current_year": "2025",
  "dynamic_rtsp_url": "",
  "dirb_wordlist": "/usr/share/wordlists/dirb/common.txt",
  "password_wordlist": "data/passwords.txt",
  "username_wordlist": "data/usernames.txt",
  "snmp_communities": ["public", "private", "camera", "admin", "cam", "cisco", "default", "guest", "test"],
  "medusa_threads": 8,
  "enable_iot_enumeration": true,
  "enable_pcap_capture": true,
  "enable_wifi_scan": true,
  "enable_ble_scan": true,
  "enable_zigbee_zwave_scan": true,
  "stealth_mode": true,
  "enable_nmap_vuln": true
}

• stealth_mode: Adds delays for stealth.
• enable_nmap_vuln: Enables detailed vuln scans (slower).
• Offline-first: Uses local files for RTSP/CVEs.

Troubleshooting

• Dependencies: Use sudo for auto-install.
• RTSP Errors: Verify dynamic_rtsp_url or use fallback.
• Permissions: sudo required for scans.
• Animations: Set NO_ANIM=1 for non-interactive.
• IoT Scans: Disable unsupported features in config.
• Logs: Check output/*/logs/ and alerts.log.

Additional Logging / Diagnostics:

• To set an explicit output root: export CAMSNIFF_OUTPUT=/tmp/camsniff_run
• Confirm backend health: curl -s http://localhost:8089/health -> ok
• Quick event sanity check: python -m python_core.logging_utils emit --event-type test_ping --message "hello"
• If systemd unit is used, inspect: journalctl -u camsniff-web.service -e

Security Hardening Notes:

• The systemd service runs with a dynamic user and a tightened filesystem view.
• Write locations are restricted to the configured output and volatility directories.

Contributing

1. Fork and clone:

   git clone https://github.com/your-username/CamSniff.git
   cd CamSniff
   

2. Branch:

   git checkout -b feature-branch
   

3. Commit and push:

   git commit -m "Description"
   git push origin feature-branch
   

4. Open a PR with details.

Try to follow simimar coding patterns.

Acknowledgments

Gratitude to open-source tool developers powering CamSniff.

License

MIT License. See LICENSE.