mstoeck3/forensic-trails
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updates

Browse Source
This commit is contained in:
overcuriousity
2025-10-08 21:49:39 +02:00
parent aa61bfabc1
commit 86359ec850
11 changed files with 2022 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

313
.github/instructions/concept.instructions.md vendored Normal file
View File

@@ -0,0 +1,313 @@
---
applyTo: '**'
---
- # ForensicTrails - Technical Specification
- ## Forensic Investigation Documentation System
- **Version:** 1.0
- **Target:** Third-semester student project with AI assistance
- **Status:** Design Specification for Implementation
- ## 1. Project Overview
- ### 1.1 Purpose
- Desktop application for forensic investigators to document case work with:
- Immutable, timestamped note-taking
- Evidence tracking with chain of custody
- Configurable Investigation question framework (Standard: WHO/WHAT/WHEN/WHERE/HOW/WHY/WITH WHAT)
- Report generation
- Optional multi-user sync capability
- ### 1.2 Core Principles
- **Offline-first**: Must work without network
- **Simplicity**: Intuitive for solo investigators
- **Integrity**: Cryptographic Documentation of all data
- **Court-ready**: All documentation legally admissible
- **Case-agnostic**: No predefined templates, universal investigation framework
- ### 1.3 Success Criteria
- Solo investigator can document case from start to finish
- Generate PDF report with digital signatures
- Maintain complete chain of custody
- Evidence integrity verification via hashes
- All notes immutable with timestamps (can edit, but edits are documented)
- ## 2. Technical Architecture
- ### 2.1 Technology Stack
-
```
Frontend/GUI:
- Python 3.13+
- PyQt6 (desktop GUI framework)
- QtWebEngine (for rich text/markdown rendering)
Database:
- SQLite3 (local storage)
- SQLCipher (optional encryption)
- Connection pooling for optional remote PostgreSQL
Utilities:
- hashlib (MD5, SHA256 computation)
- cryptography (digital signatures, encryption)
- ReportLab (PDF generation)
- python-docx (Word export)
- Pillow (screenshot handling)
Deployment:
- PyInstaller (standalone executable)
- One build per OS (Windows, Linux, macOS)
```
- ### 2.2 System Architecture
-
```
┌─────────────────────────────────────────────┐
│ PyQt6 GUI Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Note │ │ Evidence │ │ Report │ │
│ │ Editor │ │ Manager │ │ Generator│ │
│ └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│ Business Logic Layer │
│ - Note immutability enforcement │
│ - Chain of custody tracking │
│ - Investigation question tagging │
│ - Timeline generation │
├─────────────────────────────────────────────┤
│ Data Access Layer │
│ - SQLite manager (local) │
│ - MariaDB connector (optional remote) │
│ - Encryption wrapper │
│ - Conflict resolution (for sync) │
├─────────────────────────────────────────────┤
│ Storage Layer │
│ Local: SQLite + File attachments │
│ Remote (optional): MariaDB │
└─────────────────────────────────────────────┘
```
- ## 3. Database Schema
- ### 3.1 Core Tables
-
```sql
-- Cases table
CREATE TABLE cases (
case_id TEXT PRIMARY KEY,
title TEXT NOT NULL,
date_opened TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
lead_investigator TEXT NOT NULL,
classification TEXT,
summary TEXT,
status TEXT DEFAULT 'Active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
modified_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Notes table (append-only, immutable)
CREATE TABLE notes (
note_id TEXT PRIMARY KEY,
case_id TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
content TEXT NOT NULL,
investigator TEXT NOT NULL,
question_tags TEXT, -- JSON array: ["WHO", "WHAT", etc.]
hash TEXT NOT NULL, -- SHA256 of content + timestamp
FOREIGN KEY (case_id) REFERENCES cases(case_id)
);
-- Evidence table
CREATE TABLE evidence (
evidence_id TEXT PRIMARY KEY,
case_id TEXT,
description TEXT NOT NULL,
filename TEXT,
file_size INTEGER,
md5_hash TEXT,
sha256_hash TEXT,
source_origin TEXT,
received_date DATE,
received_by TEXT,
physical_location TEXT,
notes TEXT,
status TEXT DEFAULT 'Active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (case_id) REFERENCES cases(case_id)
);
-- Chain of Custody table
CREATE TABLE chain_of_custody (
coc_id TEXT PRIMARY KEY,
evidence_id TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
action TEXT NOT NULL, -- 'received', 'transferred', 'accessed', 'archived'
from_person TEXT,
to_person TEXT,
location TEXT,
purpose TEXT,
signature_hash TEXT, -- Digital signature if needed
FOREIGN KEY (evidence_id) REFERENCES evidence(evidence_id)
);
-- Attachments table (screenshots, documents)
CREATE TABLE attachments (
attachment_id TEXT PRIMARY KEY,
case_id TEXT NOT NULL,
note_id TEXT, -- Optional link to specific note
filename TEXT NOT NULL,
file_path TEXT NOT NULL,
file_hash TEXT NOT NULL,
mime_type TEXT,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (case_id) REFERENCES cases(case_id),
FOREIGN KEY (note_id) REFERENCES notes(note_id)
);
-- Investigation Questions tracking
CREATE TABLE question_entries (
entry_id TEXT PRIMARY KEY,
case_id TEXT NOT NULL,
note_id TEXT NOT NULL,
question_type TEXT NOT NULL, -- WHO/WHAT/WHEN/WHERE/HOW/WHY/WITH_WHAT
entry_text TEXT NOT NULL,
timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (case_id) REFERENCES cases(case_id),
FOREIGN KEY (note_id) REFERENCES notes(note_id)
);
-- User settings (for multi-user)
CREATE TABLE users (
user_id TEXT PRIMARY KEY,
username TEXT UNIQUE NOT NULL,
full_name TEXT NOT NULL,
role TEXT DEFAULT 'Investigator', -- Investigator/Manager/Admin
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Optional: Task assignments (team mode)
CREATE TABLE tasks (
task_id TEXT PRIMARY KEY,
case_id TEXT NOT NULL,
title TEXT NOT NULL,
description TEXT,
assigned_to TEXT,
assigned_by TEXT,
priority TEXT,
due_date DATE,
status TEXT DEFAULT 'Open',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (case_id) REFERENCES cases(case_id)
);
```
- ### 3.2 Indexes for Performance
-
```sql
CREATE INDEX idx_notes_case ON notes(case_id);
CREATE INDEX idx_notes_timestamp ON notes(timestamp);
CREATE INDEX idx_evidence_case ON evidence(case_id);
CREATE INDEX idx_coc_evidence ON chain_of_custody(evidence_id);
CREATE INDEX idx_question_case ON question_entries(case_id, question_type);
```
- ## 4. Core Features
- ### 4.1 Case Management
- Create new case with minimal metadata
- List all cases with search (& Filter)
- Open/close/archive cases
- Case status tracking
- ### 4.2 Note-Taking
- Rich text editor for notes
- Auto-timestamp on every entry (immutable)
- Notes can be edited, but each edit is documented (can restore old states)
- Tag notes with investigation questions
- Search across all notes
- Screenshot integration with auto-hash
- ### 4.3 Evidence Management
- Add evidence with ID, description, hashes
- Compute MD5/SHA256 automatically or paste
- Track physical location (text field)
- Evidence status (Active/Archived/Destroyed)
- Link evidence to notes
- ### 4.4 Chain of Custody
- Automatic entry on evidence creation
- Manual entries for transfers/access
- Immutable CoC log
- ### 4.5 Investigation Questions Framework
- Tag any note with: WHO/WHAT/WHEN/WHERE/HOW/WHY/WITH_WHAT
- configurable questions
- View organized by question type
- Timeline view (auto-generated from WHEN tags)
- Summary view per question
- ### 4.6 Report Generation
- PDF export with all case data
- Sections: Metadata, Notes, Evidence, CoC, Questions
- Digital signature of report
- Court-ready formatting
- Optional DOCX export
- ### 4.7 Optional: Remote Sync
- Configure MariaDB connection
- Push/pull case data
- Conflict resolution (timestamp-based)
- Offline-capable (queue sync)
- ## 5. User Interface Layout
- ### 5.1 Main Window Structure
-
```
┌─────────────────────────────────────────────────────┐
│ Menu Bar: File | Case | Evidence | View | Tools │
├──────────┬──────────────────────────────┬───────────┤
│ │ │ │
│ Cases │ Active View Area │ Sidebar │
│ List │ (Notes/Evidence/Timeline) │ Panel │
│ │ │ │
│ - Case 1 │ [Content depends on │ • Case │
│ - Case 2 │ selected tab below] │ Info │
│ - Case 3 │ │ • Ques- │
│ │ │ tions │
│ [Search] │ │ • Evid- │
│ │ │ ence │
│ │ │ │
├──────────┴──────────────────────────────┴───────────┤
│ Tab Bar: Notes | Evidence | Questions | Timeline │
│ | Chain of Custody | Reports │
└─────────────────────────────────────────────────────┘
```
- ### 5.2 Key Views
- **Notes View:**
- Chronological log of all notes (immutable)
- New note entry at bottom
- Quick tag buttons (WHO/WHAT/WHEN/WHERE/HOW/WHY/WITH_WHAT)
- or whatever can be configured
- Screenshot button
- Evidence reference button
- **Evidence View:**
- Table of all evidence items
- Add/view evidence details
- CoC view per item
- **Questions View:**
- Accordion/expandable sections per question
- Shows all notes tagged with that question
- Quick navigation
- **Timeline View:**
- Visual timeline of events
- Generated from WHEN-tagged notes
- Zoomable, filterable
- **Chain of Custody View:**
- Per-evidence CoC log
- Transfer recording interface
- **Reports View:**
- Report templates
- Generate PDF/DOCX
- Preview before export
- ## 6. Implementation Priorities
- ### Phase 1: Minimum Viable Product (Core Solo Mode)
- 1. Case creation and listing
- 2. Note-taking with immutable timestamps
- 3. Evidence management with hashing
- 4. Basic Chain of Custody
- 5. Simple PDF export
- **Deliverable:** Functional solo investigator tool
- ### Phase 2: Enhanced Features
- 1. Investigation questions tagging
- 2. Questions-organized view
- 3. Timeline visualization
- 4. Screenshot integration
- 5. Advanced PDF report with formatting
- **Deliverable:** Full-featured documentation tool
- ### Phase 3: Team & Advanced
- 1. Multi-user support (local)
- 2. Task assignment
- 3. MariaDB remote sync
- 4. Digital signatures on reports
- 5. Advanced search and filtering
- **Deliverable:** Team-capable system