GitHub - 123s4567/cybercrew: CyberCrew v2.0 - Offline desktop DFIR application. PyQt6 GUI wrapping 26 forensic tools with evidence chain-of-custody, SHA-256 hashing, and automated reporting.

 ██████╗██╗   ██╗██████╗ ███████╗██████╗  ██████╗██████╗ ███████╗██╗    ██╗
██╔════╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔════╝██╔══██╗██╔════╝██║    ██║
██║      ╚████╔╝ ██████╔╝█████╗  ██████╔╝██║     ██████╔╝█████╗  ██║ █╗ ██║
██║       ╚██╔╝  ██╔══██╗██╔══╝  ██╔══██╗██║     ██╔══██╗██╔══╝  ██║███╗██║
╚██████╗   ██║   ██████╔╝███████╗██║  ██║╚██████╗██║  ██║███████╗╚███╔███╔╝
 ╚═════╝   ╚═╝   ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝ ╚══╝╚══╝
                                                              v 2 . 0 . 0

CyberCrew v2.0 — A standalone, offline digital forensics investigation platform combining the power of CLI tools with a dark-themed, mission-critical GUI.

📽 Preview

Animated GIF description (replace this block with assets/demo.gif): The GIF should show: (1) The dark cockpit splash with the animated logo border pulse; (2) a new case being created with the CC-YYYY-XXXX case number appearing; (3) the Network module being selected, a target IP entered, a port scan launched — streaming terminal output with colour-highlighted ports; (4) the Metrics panel updating live (risk badge animating from NONE → HIGH); (5) the Evidence panel showing SHA-256 hashing in progress (amber spinner) then transitioning to VERIFIED (green tick); (6) the Report page generating a PDF — 10 seconds total.

1. Overview

What is CyberCrew?

CyberCrew v2.0 is a fully offline, cross-platform desktop application for digital forensics investigators, cybersecurity students, and non-specialist responders. It wraps industry-standard CLI forensics tools — nmap, tshark, exiftool, ADB, Sleuth Kit, John the Ripper, Tesseract, and Nikto — inside a single, cohesive graphical interface with real-time output streaming, an immutable evidence chain, case management, and HTML/PDF report generation.

You do not need to remember command flags. You do not need to string bash pipelines. You open CyberCrew, create a case, select a module, fill in a target, and click LAUNCH.

Why CyberCrew instead of the alternatives?

Feature	CyberCrew v2.0	Autopsy	Volatility	Bash Scripts
Fully offline	✅	✅	✅	✅
Unified GUI for 5 domains	✅	❌	❌	❌
Real-time streaming output	✅	❌	❌	✅ (terminal only)
SHA-256 evidence chain	✅	Partial	❌	Manual
Multi-instance parallelism	✅	❌	❌	❌
Built-in report generation	✅	✅	❌	❌
Tamper-evident audit log	✅	Partial	❌	❌
Single install, no Java	✅	❌ (Java)	✅	✅
Mobile forensics (ADB)	✅	Partial	❌	Manual
Non-specialist friendly	✅	Partial	❌	❌

Screenshot Guide

┌─────────────────────────────────────────────────────────────────────────────┐
│ ◉ CYBERCREW │ DASHBOARD  NETWORK  COMPUTER  MOBILE  MEDIA  WEBAPP │ CC-2025│
├─────────────────────────────────────────────────────────────────────────────┤
│ ● network-scan-1  ● port-scan-2  + NEW INSTANCE                            │
├──────────────────────────────────┬──────────────────────────────────────────┤
│                                  │  RISK: HIGH  7.4                        │
│  [TERMINAL OUTPUT PANEL]         │  ─────────────────                      │
│  $ nmap -sV -v 192.168.1.0/24   │  SCAN METRICS                          │
│  [+] Nmap scan report for...     │  Hosts Up     ............  12          │
│  PORT    STATE  SERVICE          │  Open Ports   ............  47          │
│  22/tcp  open   OpenSSH 8.9      │  Services     ............  23          │
│  80/tcp  open   Apache 2.4.54    │  ─────────────────                      │
│  443/tcp open   nginx            │  OPEN PORTS                            │
│                                  │  22   OPEN   ssh                       │
├──────────────────────────────────│  80   OPEN   http                      │
│ CASE LOG                         │  443  OPEN   https                     │
│  12:34:01  [INFO]  Scan started  ├──────────────────────────────────────────┤
│  12:34:22  [DONE]  3 hosts up    │  EVIDENCE CHAIN                        │
│                                  │  ✓ 3  ⟳ 1  • 2                        │
└──────────────────────────────────┴──────────────────────────────────────────┘

Panels (left to right, top to bottom): TitleBar with navigation, InstanceBar, Terminal Panel with live tool output, Case Log Panel, Metrics Panel with animated counters, Evidence Panel with hash status.

Feature Matrix

Feature	Status	Modules
Host discovery (nmap -sn)	✅ Stable	Network
Port scanning (nmap -sV)	✅ Stable	Network
Vulnerability scanning (nmap --script=vuln)	✅ Stable	Network
Live packet capture (tshark)	✅ Stable	Network
Offline pcap analysis	✅ Stable	Network
Disk imaging (dd)	✅ Stable	Computer
File carving (photorec)	✅ Stable	Computer
Filesystem timeline (sleuthkit)	✅ Stable	Computer
OCR extraction (tesseract)	✅ Stable	Computer
Password cracking (john)	✅ Stable	Computer
ADB device info	✅ Stable	Mobile
Media extraction (adb pull)	✅ Stable	Mobile
Call log extraction	✅ Stable	Mobile
SMS extraction	✅ Stable	Mobile
GPS data extraction	✅ Stable	Mobile
Contacts extraction	✅ Stable	Mobile
Image EXIF analysis (exiftool)	✅ Stable	Media
Video metadata extraction	✅ Stable	Media
PDF metadata analysis	✅ Stable	Media
Office document metadata	✅ Stable	Media
PE executable analysis	✅ Stable	Media
Email header/MX analysis	✅ Stable	WebApp
WhatsApp export analysis	✅ Stable	WebApp
Website vulnerability scan (nikto)	✅ Stable	WebApp
Domain reconnaissance (whois/dig)	✅ Stable	WebApp
URL lookup	✅ Stable	WebApp
HTML report generation	✅ Stable	Reports
PDF report generation	✅ Stable	Reports
SHA-256 evidence chain	✅ Stable	Core
Multi-instance parallel execution	✅ Stable	Core
Tamper-evident audit log	✅ Stable	Core
Case management (SQLite)	✅ Stable	Core

2. Architecture

Application Flow

flowchart TD
    A([main.py]) --> B[QApplication Init]
    B --> C[Load Fonts]
    B --> D[Init SQLite Database]
    B --> E[Create ForensicsEngine]
    C & D & E --> F[MainWindow.show]

    F --> G{User Navigation}
    G --> H[Dashboard Page]
    G --> I[Module Pages\nNetwork / Computer / Mobile / Media / WebApp]

    I --> J[Create Case\nCC-YYYY-XXXX]
    J --> K[Fill Module Parameters]
    K --> L[validate_input]
    L -->|Invalid| M[ModuleInputError → UI Warning]
    L -->|Valid| N[build_command → list of str]
    N --> O[ForensicsEngine.launch\nQProcess — NO shell=True]

    O --> P{QProcess Signals}
    P --> Q[readyReadStandardOutput\n→ TerminalPanel]
    P --> R[readyReadStandardError\n→ TerminalPanel red]
    P --> S[finished\n→ on_complete]
    P --> T[errorOccurred\n→ on_error]

    Q --> U[parse_output\n→ MetricsPanel update]
    Q --> V[finding_discovered\n→ CaseLogPanel]

    S --> W[ArtifactHasher.hash_file_async\nQThread — non-blocking]
    W --> X[EvidencePanel: HASHING → VERIFIED]
    W --> Y[write_hash_sidecar .sha256]

    X --> Z[ReportGenerator\nJinja2 HTML + WeasyPrint PDF]
    Z --> AA([dist/report.html / report.pdf])

Technology Stack

Component	Library	Version	Purpose
GUI framework	PyQt6	≥ 6.6.0	All UI widgets, signals/slots
Async subprocess	QProcess	built-in	Non-blocking tool execution
Background threading	QThread	built-in	SHA-256 hashing
Database ORM	SQLModel	≥ 0.0.18	SQLite schema + queries
Database driver	SQLite	built-in	Embedded storage
Real-time charts	PyQtGraph	≥ 0.13.3	Network traffic chart
Report templates	Jinja2	≥ 3.1.3	HTML templating
PDF generation	WeasyPrint	≥ 61.0	HTML → PDF conversion
Distribution	PyInstaller	≥ 6.3.0	AppImage / .exe
Input sanitization	Custom	—	Path/injection prevention

3. Prerequisites

System Requirements

Requirement	Minimum	Recommended
OS	Ubuntu 22.04 / Windows 10	Kali Linux 2024.x / Windows 11
Python	3.11	3.12
RAM	4 GB	8 GB
Disk space	2 GB free	10 GB free
Display	1280×720	1920×1080
Network	Optional	Optional

Required System Binaries (Linux)

sudo apt-get install -y \
  nmap \
  tshark \
  android-tools-adb \
  sleuthkit \
  foremost \
  libimage-exiftool-perl \
  john \
  tesseract-ocr \
  tesseract-ocr-eng \
  nikto \
  tcpdump \
  ffmpeg \
  whois \
  dnsutils \
  openssl \
  net-tools

Required System Binaries (Windows)

Install via winget:

winget install Npcap                          # Required for tshark on Windows
winget install WiresharkFoundation.Wireshark  # Includes tshark
winget install Google.PlatformTools           # Android ADB

Then manually install:

ADB Setup (Mobile Module)

# Linux — allow ADB without root
sudo usermod -aG plugdev $USER
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="*", MODE="0664", GROUP="plugdev"' \
  | sudo tee /etc/udev/rules.d/51-android.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

# Verify device is detected:
adb devices

On the Android device: enable Developer Options → USB Debugging.

Root vs. Non-Root Capability Matrix

Tool	Requires Root	Notes
nmap (host discovery, port scan)	❌ No	SYN scan requires root; TCP-connect scan works without
nmap (vuln scripts)	❌ No	Some scripts faster with root
tshark (live capture)	✅ Yes or `wireshark` group	`sudo usermod -aG wireshark $USER`
dd (disk imaging)	✅ Yes	Writing to `/dev/sdX` requires root
photorec	❌ No	Can read image files without root
fls / mactime (sleuthkit)	❌ No	Reading image files
tesseract	❌ No	Userspace OCR
john	❌ No	Hash cracking is CPU-bound
adb	❌ No	Requires USB debugging on device
exiftool	❌ No	Reads file metadata
nikto	❌ No	Web scanner
whois / dig	❌ No	DNS queries

4. Installation

🐧 Kali Linux (Recommended)

Most forensics tools come pre-installed on Kali:

# 1. Clone the repository
git clone https://github.com/your-org/cybercrew.git
cd cybercrew

# 2. Run the automated installer
chmod +x scripts/install_linux.sh
sudo ./scripts/install_linux.sh

# 3. Activate the virtual environment
source venv/bin/activate

# 4. Launch
python main.py

🐧 Ubuntu 22.04 / Debian 12

# 1. Update system
sudo apt-get update && sudo apt-get upgrade -y

# 2. Install Python 3.11+
sudo apt-get install -y python3.11 python3.11-venv python3.11-dev

# 3. Clone the repository
git clone https://github.com/your-org/cybercrew.git
cd cybercrew

# 4. Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# 5. Install Python dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 6. Install system forensics tools
sudo apt-get install -y nmap tshark android-tools-adb sleuthkit \
  foremost libimage-exiftool-perl john tesseract-ocr nikto \
  whois dnsutils tcpdump ffmpeg openssl

# 7. Install fonts
mkdir -p ~/.local/share/fonts
cp assets/fonts/*.ttf ~/.local/share/fonts/
fc-cache -fv

# 8. Add user to wireshark group (for tshark without root)
sudo usermod -aG wireshark $USER
newgrp wireshark

# 9. Verify installation
python main.py --check-deps

🐧 Arch Linux / Manjaro

# 1. Install system dependencies via pacman and AUR
sudo pacman -S --noconfirm python nmap wireshark-qt android-tools \
  sleuthkit perl-image-exiftool john tesseract tcpdump ffmpeg whois

# AUR: photorec (testdisk), nikto, foremost
yay -S testdisk nikto foremost --noconfirm

# 2. Clone + setup
git clone https://github.com/your-org/cybercrew.git && cd cybercrew
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

🪟 Windows 10 / 11

# Run as Administrator in PowerShell

# 1. Install prerequisites via winget
winget install Python.Python.3.12
winget install Npcap
winget install WiresharkFoundation.Wireshark
winget install Google.PlatformTools

# 2. Close and reopen PowerShell (refresh PATH)

# 3. Clone the repository
git clone https://github.com/your-org/cybercrew.git
cd cybercrew

# 4. Run the Windows installer script
.\scripts\install_windows.ps1

# 5. Launch
.\venv\Scripts\Activate.ps1
python main.py

Font Installation

CyberCrew uses JetBrains Mono and IBM Plex Mono. They are bundled in assets/fonts/. If you want system-wide installation:

# Linux
cp assets/fonts/*.ttf ~/.local/share/fonts/
fc-cache -fv

# macOS
cp assets/fonts/*.ttf ~/Library/Fonts/

# Windows — double-click each .ttf file and click "Install"

Verify Installation

python main.py --check-deps

Expected output:

CyberCrew v2.0.0 — Dependency Check
────────────────────────────────────
✓  nmap          /usr/bin/nmap
✓  tshark        /usr/bin/tshark
✓  adb           /usr/bin/adb
✓  fls           /usr/bin/fls
✓  exiftool      /usr/bin/exiftool
✓  john          /usr/sbin/john
✓  tesseract     /usr/bin/tesseract
✓  nikto         /usr/bin/nikto
✓  whois         /usr/bin/whois
✓  dig           /usr/bin/dig
────────────────────────────────────
10/10 dependencies satisfied. Ready to launch.

5. Quick Start

Step 1 — Launch and Create a Case

source venv/bin/activate
python main.py

Click + NEW CASE on the Dashboard. Enter:

Case Name: e.g., Incident-2025-001
Investigator: your name
Description: optional

A case number is auto-assigned: CC-2025-0001.

Step 2 — Launch Your First Scan

Click NETWORK in the navigation bar
Click + NEW INSTANCE
Select tool: Port Scanner
Enter target: 192.168.1.0/24
Click ▶ LAUNCH

Watch the terminal stream live nmap output. The Metrics panel updates automatically.

Step 3 — Export a Report

When the scan completes (status: DONE), click REPORTS
Select format: HTML or PDF
Click GENERATE REPORT
Report saved to evidence/<case-number>/report.*

6. Module Documentation

6.1 Network Module

Wraps nmap and tshark for network reconnaissance and traffic analysis.

Tools

Tool	Binary	Description
Host Discovery	nmap	Ping sweep of IP range (-sn)
Port Scanner	nmap	Service version detection (-sV)
Vuln Scanner	nmap	NSE vulnerability scripts (--script=vuln)
Packet Capture	tshark	Live interface capture
Packet Analyzer	tshark	Offline PCAP analysis

Usage: Port Scanner

Parameters:

target (required) — IP address, CIDR range, or hostname
ports (optional) — Port range, e.g. 1-1024, 80,443,8080
timing (optional) — nmap timing template: T1–T5

Example Output:

[*] Starting Nmap 7.94 scan of 192.168.1.1
PORT    STATE  SERVICE  VERSION
22/tcp  open   ssh      OpenSSH 8.9p1 Ubuntu
80/tcp  open   http     Apache httpd 2.4.54
443/tcp open   ssl/http nginx 1.22.0
[*] Nmap done: 1 IP address (1 host up) scanned in 8.42 seconds

Usage: Packet Capture

Parameters:

interface (required) — Network interface (e.g. eth0, wlan0)
filter (optional) — BPF filter expression (e.g. tcp port 80)
count (optional) — Stop after N packets
duration (optional) — Stop after N seconds

6.2 Computer Module

Wraps dd, photorec, sleuthkit, tesseract, and john for disk and file forensics.

Tools

Tool	Binary	Description
Disk Imager	dd	Block-level forensic disk image
File Recovery	photorec	Carve deleted/lost files
Timeline	fls + mactime	Filesystem activity timeline
OCR	tesseract	Extract text from images
Password Cracker	john	Crack password hashes

Usage: Disk Imager

Parameters:

source (required) — Device path (e.g. /dev/sdb) — requires root
output (optional) — Output image path (auto-generated if omitted)
block_size (optional) — dd block size, default 64K

⚠️ Chain of Custody: The output image is automatically SHA-256 hashed after completion and a .sha256 sidecar file is written. Do not modify the image after creation.

Usage: Password Cracker

Parameters:

hash_file (required) — File containing password hashes
wordlist (optional) — Path to wordlist file (e.g. /usr/share/wordlists/rockyou.txt)
format (optional) — Hash format (e.g. md5crypt, sha512crypt, NT)

6.3 Mobile Module

Wraps Android Debug Bridge (adb) for Android device forensics.

Tools

Tool	Command	Description
ADB Info	adb shell getprop	Device model, OS version, serial
Media Extractor	adb pull	Pull photos, videos, audio
Call Log	content query	Extract call history
GPS	dumpsys location	Extract location data
SMS	content query	Extract text messages
Contacts	content query	Extract contact list

Prerequisites

USB Debugging must be enabled on the device
Device must be connected via USB or ADB over TCP/IP
Run adb devices to confirm device is detected before launching

Usage: Media Extractor

Parameters:

serial (optional) — Device serial (required if multiple devices connected)
remote_path (optional) — Source path on device, default /sdcard/DCIM/

6.4 Media Module

Wraps exiftool for forensic metadata extraction from media files and documents.

Tools

Tool	File Types	Key Metadata
Image	JPG, PNG, TIFF, RAW, HEIC	GPS, Camera model, Timestamps, EXIF
Video	MP4, AVI, MKV, MOV	Duration, Frame rate, Codec, Creation date
PDF	PDF	Author, Creator, Modification dates, embedded content
Office	DOCX, XLSX, PPTX	Author, LastSavedBy, Company, Revision count
EXE	EXE, DLL, SYS	Compile timestamp, OriginalFilename, CompanyName, PE version

Anomaly Detection

CyberCrew automatically flags:

Editing software present in camera image (e.g. Photoshop EXIF in a "screenshot")
GPS/timestamp mismatch between EXIF and filesystem
PE compile timestamp predating Windows NT release (indicator of timestamp manipulation)
OriginalFilename mismatch (EXE renamed to bypass detection)

6.5 Web Application Module

Wraps nikto, whois, and dig for web presence and domain investigation.

Tools

Tool	Binary	Description
Email Analysis	dig	MX, SPF, DMARC record lookup
WhatsApp Analysis	(parser)	Parse WhatsApp `.txt` export
Website Scanner	nikto	Web vulnerability scan
URL Lookup	whois	Domain registration info
Domain Recon	dig	Full DNS record enumeration

Usage: Website Scanner

Parameters:

url (required) — Target URL (must begin with http:// or https://)
ports (optional) — Port list, e.g. 80,443,8443
tuning (optional) — Nikto tuning options (1-9)

⚠️ Legal Notice: Only scan systems you own or have explicit written permission to test.

7. Case Management

Creating a Case

Every investigation is tied to a case. Cases store:

Auto-assigned case number (CC-YYYY-XXXX)
Investigator name
Status: OPEN / ACTIVE / SUSPENDED / CLOSED
All artifacts, findings, event logs, and reports

Case Workflow

CREATE → OPEN → ACTIVE (tools running) → SUSPENDED (optional) → CLOSED

Evidence Directory Structure

evidence/
└── CC-2025-0001/
    ├── network/
    │   ├── port_scan_20250101_143022.xml
    │   ├── port_scan_20250101_143022.xml.sha256
    │   └── capture_20250101_143055.pcap
    ├── computer/
    │   ├── disk_image_20250101_150000.dd
    │   └── disk_image_20250101_150000.dd.sha256
    ├── mobile/
    │   └── media/
    ├── media/
    │   └── image_metadata_20250101_151200.json
    ├── webapp/
    │   └── nikto_scan_20250101_152000.txt
    └── reports/
        ├── report_20250101_160000.html
        └── report_20250101_160000.pdf

Chain of Custody

Every artifact file receives:

A SHA-256 hash computed in a background thread (non-blocking)
A .sha256 sidecar file in sha256sum format
A database record in the artifacts table with hash, path, and timestamp
An audit log entry in the event_log table

To verify integrity at any time: Evidence Panel → VERIFY ALL

8. Report Generation

Generating a Report

From any module page:

Click the REPORTS tab
Select Case from the dropdown
Choose Format: HTML or PDF
Click GENERATE

Report Structure

Header — Case number, investigator, generation timestamp
Stats Overview — Total findings, artifacts, critical count, events
Executive Summary — Editable text field
Findings — Severity-sorted cards (CRITICAL → INFO)
Evidence Chain — Table of all artifacts with SHA-256 hashes
Event Timeline — Chronological audit log
Tool Output Logs — Raw tool output per session

Report Location

evidence/<case-number>/reports/report_<timestamp>.html
evidence/<case-number>/reports/report_<timestamp>.pdf

9. Configuration Reference

Configuration is stored in the settings table in SQLite. Access via Dashboard → Settings.

Key	Default	Valid Values	Description
`max_instances`	`8`	`1–32`	Maximum parallel tool instances
`evidence_base_dir`	`./evidence`	Any writable path	Root directory for all evidence
`auto_hash_artifacts`	`true`	`true/false`	Auto-SHA-256 all output files
`hash_chunk_size`	`65536`	`4096–1048576`	Byte chunk size for hashing
`terminal_scrollback`	`10000`	`1000–100000`	Max terminal lines retained
`auto_scroll_terminal`	`true`	`true/false`	Follow latest output
`report_format_default`	`html`	`html/pdf/both`	Default report format
`investigator_name`	`""`	Any string ≤64 chars	Pre-fill investigator field
`font_size_terminal`	`11`	`8–16`	Terminal font size (pt)
`animation_enabled`	`true`	`true/false`	Disable for low-power systems
`nmap_default_timing`	`T4`	`T1–T5`	Default nmap timing template
`tshark_default_count`	`0`	`0=unlimited`	Default packet count limit

10. Keyboard Shortcuts

Shortcut	Action
`Ctrl+T`	New instance in current module
`Ctrl+W`	Close active instance
`Ctrl+Q`	Quit CyberCrew (graceful shutdown)
`F5`	Refresh current page
`F11`	Toggle fullscreen
`↑` / `↓`	Navigate command history in terminal
`Enter`	Submit command in terminal input
`Ctrl+L`	Clear terminal output
`Ctrl+S`	Save terminal output to file
`1`	Switch to DASHBOARD tab
`2`	Switch to NETWORK tab
`3`	Switch to COMPUTER tab
`4`	Switch to MOBILE tab
`5`	Switch to MEDIA tab
`6`	Switch to WEBAPP tab

11. Troubleshooting

Issue 1: `tshark: Couldn't run /usr/bin/dumpcap in child process`

Cause: User is not in the wireshark group.

Fix:

sudo usermod -aG wireshark $USER
newgrp wireshark

Issue 2: `ModuleNotFoundError: No module named 'PyQt6'`

Cause: Python virtual environment not activated, or dependencies not installed.

Fix:

source venv/bin/activate
pip install -r requirements.txt

Issue 3: ADB shows "no devices/emulators found"

Cause: USB Debugging not enabled, or ADB server not started.

Fix:

adb kill-server
adb start-server
adb devices

Enable Settings → Developer Options → USB Debugging on the Android device. Accept the RSA key prompt on the device.

Issue 4: `dd: error writing '/dev/sdb': No space left on device`

Cause: Output disk is smaller than source disk.

Fix: Ensure the output destination has at least as much free space as the source device size. Use lsblk to check sizes.

Issue 5: Fonts not displaying correctly (boxes or squares instead of characters)

Cause: JetBrains Mono or IBM Plex Mono not installed.

Fix:

cp assets/fonts/*.ttf ~/.local/share/fonts/
fc-cache -fv
# Restart CyberCrew

Issue 6: `nmap: You requested a scan type which requires root privileges`

Cause: SYN scan (-sS) requires raw socket access.

Workaround: CyberCrew uses TCP connect scan by default, which does not require root. For SYN scans, launch CyberCrew with sudo python main.py (not recommended for normal use).

Issue 7: PDF report is blank or fails to generate

Cause: WeasyPrint is not installed or missing GTK dependencies.

Fix:

# Linux
sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libcairo2 \
  libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
pip install weasyprint

# Windows — WeasyPrint on Windows requires additional setup
# See: https://doc.courtbouillon.org/weasyprint/stable/first_steps.html

Issue 8: Application crashes on startup with `QXcbConnection: Could not connect to display`

Cause: Running on a headless server without a display.

Fix: CyberCrew requires a graphical display. On a headless server, use a virtual display:

sudo apt-get install -y xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
python main.py

Issue 9: `john: No password hashes loaded`

Cause: Hash file is in an unsupported format or is empty.

Fix: Specify the hash format explicitly using the format parameter. Use john --list=formats to see supported formats.

Issue 10: Evidence verification fails (FAILED status in red)

Cause: File has been modified after initial hashing (tampering detected), or the .sha256 sidecar file was deleted.

Fix: This is a chain of custody alert. Do not modify files in the evidence directory. If the file was legitimately re-processed, delete the original artifact record and re-collect.

12. Contributing

We welcome contributions! Please read these guidelines before submitting a pull request.

Development Setup

git clone https://github.com/your-org/cybercrew.git
cd cybercrew
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Testing + linting deps

Code Standards

Python 3.11+ only
Type hints on all public functions and methods
Google-style docstrings on every class and method
No shell=True — ever
No direct widget-to-widget method calls — use Qt signals/slots
All user inputs must pass through InputSanitizer before use
Tests required for all new modules and security-sensitive code

Running Tests

pytest tests/ -v --cov=src --cov-report=html

Submitting a Pull Request

Fork the repository
Create a feature branch: git checkout -b feature/my-new-module
Write code and tests
Run pytest — all tests must pass
Run ruff check src/ — no linting errors
Submit a PR with a description of changes and a test plan

See docs/plugin_development.md for adding new forensics modules.

13. License

MIT License

Copyright (c) 2025 CyberCrew Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

14. Acknowledgements

CyberCrew v2.0 stands on the shoulders of these outstanding open-source projects:

Project	License	Use in CyberCrew
nmap	NPSL / GPL v2	Network scanning and vulnerability detection
Wireshark / tshark	GPL v2	Packet capture and pcap analysis
ExifTool	Perl Artistic License	Metadata extraction from all media types
Android Debug Bridge (ADB)	Apache 2.0	Android device forensics
Sleuth Kit (fls, mactime)	CPL / IBM / GPL	Filesystem timeline and analysis
PhotoRec / TestDisk	GPL v2	File carving and recovery
John the Ripper	GPL v2+ (Jumbo)	Password hash cracking
Tesseract OCR	Apache 2.0	Optical character recognition
Nikto	GPL v2	Web application vulnerability scanning
PyQt6	GPL v3 / Commercial	Application GUI framework
PyQtGraph	MIT	Real-time chart rendering
SQLModel	MIT	Database ORM
Jinja2	BSD 3-Clause	Report HTML templating
WeasyPrint	BSD 3-Clause	HTML to PDF conversion
JetBrains Mono	OFL 1.1	Primary UI font
IBM Plex Mono	OFL 1.1	Terminal output font

Built with 🔬 for the digital forensics community.

Report a Bug · Request a Feature · Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
PHASE2_COMPLETE.md		PHASE2_COMPLETE.md
README.md		README.md
cybercrew.spec		cybercrew.spec
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

📽 Preview

Table of Contents

1. Overview

What is CyberCrew?

Why CyberCrew instead of the alternatives?

Screenshot Guide

Feature Matrix

2. Architecture

Application Flow

Technology Stack

3. Prerequisites

System Requirements

Required System Binaries (Linux)

Required System Binaries (Windows)

ADB Setup (Mobile Module)

Root vs. Non-Root Capability Matrix

4. Installation

🐧 Kali Linux (Recommended)

🐧 Ubuntu 22.04 / Debian 12

🐧 Arch Linux / Manjaro

🪟 Windows 10 / 11

Font Installation

Verify Installation

5. Quick Start

Step 1 — Launch and Create a Case

Step 2 — Launch Your First Scan

Step 3 — Export a Report

6. Module Documentation

6.1 Network Module

Tools

Usage: Port Scanner

Usage: Packet Capture

6.2 Computer Module

Tools

Usage: Disk Imager

Usage: Password Cracker

6.3 Mobile Module

Tools

Prerequisites

Usage: Media Extractor

6.4 Media Module

Tools

Anomaly Detection

6.5 Web Application Module

Tools

Usage: Website Scanner

7. Case Management

Creating a Case

Case Workflow

Evidence Directory Structure

Chain of Custody

8. Report Generation

Generating a Report

Report Structure

Report Location

9. Configuration Reference

10. Keyboard Shortcuts

11. Troubleshooting

Issue 1: tshark: Couldn't run /usr/bin/dumpcap in child process

Issue 2: ModuleNotFoundError: No module named 'PyQt6'

Issue 3: ADB shows "no devices/emulators found"

Issue 4: dd: error writing '/dev/sdb': No space left on device

Issue 5: Fonts not displaying correctly (boxes or squares instead of characters)

Issue 6: nmap: You requested a scan type which requires root privileges

Issue 7: PDF report is blank or fails to generate

Issue 8: Application crashes on startup with QXcbConnection: Could not connect to display

Issue 9: john: No password hashes loaded

Issue 10: Evidence verification fails (FAILED status in red)

12. Contributing

Development Setup

Code Standards

Running Tests

Submitting a Pull Request

13. License

14. Acknowledgements

About

Issue 1: `tshark: Couldn't run /usr/bin/dumpcap in child process`

Issue 2: `ModuleNotFoundError: No module named 'PyQt6'`

Issue 4: `dd: error writing '/dev/sdb': No space left on device`

Issue 6: `nmap: You requested a scan type which requires root privileges`

Issue 8: Application crashes on startup with `QXcbConnection: Could not connect to display`

Issue 9: `john: No password hashes loaded`

Packages