traceforge-osint 1.0.0__py3-none-any.whl

traceforge/__init__.py

@@ -0,0 +1,6 @@
+"""
+TraceForge — Open-Source Intelligence & Digital Forensics Platform.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Aman Kumar Pandey"

traceforge/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from traceforge.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

traceforge/case.py

@@ -0,0 +1,295 @@
+import datetime
+import hashlib
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from traceforge.config import get_workspace_dir, load_config, save_config
+
+def hash_file(file_path: Path) -> Dict[str, str]:
+    """Calculates SHA-256 and MD5 checksums for a given file."""
+    sha256 = hashlib.sha256()
+    md5 = hashlib.md5()
+    with open(file_path, "rb") as f:
+        while chunk := f.read(65536):
+            sha256.update(chunk)
+            md5.update(chunk)
+    return {
+        "sha256": sha256.hexdigest(),
+        "md5": md5.hexdigest(),
+    }
+
+class Case:
+    """Manages an active forensic investigation case workspace."""
+
+    def __init__(self, case_id: str):
+        self.case_id = case_id
+        self.case_dir = get_workspace_dir() / case_id
+        self.case_json = self.case_dir / "case.json"
+        self.evidence_dir = self.case_dir / "evidence"
+        self.reports_dir = self.case_dir / "reports"
+        self.exports_dir = self.case_dir / "exports"
+        self.logs_dir = self.case_dir / "logs"
+        self.data: Dict[str, Any] = {}
+        self.load()
+
+    def exists(self) -> bool:
+        return self.case_dir.exists() and self.case_json.exists()
+
+    def load(self) -> None:
+        if self.case_json.exists():
+            try:
+                with open(self.case_json, "r", encoding="utf-8") as f:
+                    self.data = json.load(f)
+            except Exception:
+                self.data = {}
+        else:
+            self.data = {}
+
+    def save(self) -> None:
+        self.case_dir.mkdir(parents=True, exist_ok=True)
+        self.evidence_dir.mkdir(parents=True, exist_ok=True)
+        self.reports_dir.mkdir(parents=True, exist_ok=True)
+        self.exports_dir.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+
+        with open(self.case_json, "w", encoding="utf-8") as f:
+            json.dump(self.data, f, indent=2)
+
+    def log_action(self, action: str, details: str, operator: str = "Analyst") -> None:
+        """Appends an immutable entry to the chain of custody audit log."""
+        ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+        entry = {
+            "timestamp": ts,
+            "operator": operator,
+            "action": action,
+            "details": details,
+        }
+        if "chain_of_custody" not in self.data:
+            self.data["chain_of_custody"] = []
+        self.data["chain_of_custody"].append(entry)
+
+        # Also append to custody log file
+        log_file = self.logs_dir / "chain_of_custody.log"
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(f"[{ts}] [{operator}] {action} - {details}\n")
+        self.save()
+
+    def add_evidence(
+        self,
+        source_path: Union[str, Path],
+        description: str = "",
+        source_device: str = "Target System",
+        analyst: str = "Analyst"
+    ) -> Dict[str, Any]:
+        src = Path(source_path).resolve()
+        if not src.exists() or not src.is_file():
+            raise FileNotFoundError(f"Evidence file not found: {source_path}")
+
+        evid_list = self.data.setdefault("evidence", [])
+        evid_id = f"EVID-{len(evid_list) + 1:03d}"
+        dest_filename = f"{evid_id}_{src.name}"
+        dest_path = self.evidence_dir / dest_filename
+
+        # Copy evidence immutably
+        shutil.copy2(src, dest_path)
+        os.chmod(dest_path, 0o444)  # Make read-only
+
+        hashes = hash_file(dest_path)
+        size_bytes = dest_path.stat().st_size
+        ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+        record = {
+            "id": evid_id,
+            "filename": src.name,
+            "stored_filename": dest_filename,
+            "relative_path": f"evidence/{dest_filename}",
+            "size_bytes": size_bytes,
+            "sha256": hashes["sha256"],
+            "md5": hashes["md5"],
+            "description": description,
+            "source_device": source_device,
+            "acquired_at": ts,
+            "analyst": analyst,
+        }
+
+        evid_list.append(record)
+        self.log_action("INGEST_EVIDENCE", f"Ingested {src.name} as {evid_id} (SHA-256: {hashes['sha256'][:16]}...)", analyst)
+        return record
+
+    ingest_evidence = add_evidence
+
+    def add_finding(
+        self,
+        title: str,
+        category: str = "General",
+        severity: str = "medium",
+        status: str = "open",
+        description: str = "",
+        evidence_refs: Optional[List[str]] = None,
+        analyst: str = "Analyst"
+    ) -> Dict[str, Any]:
+        findings = self.data.setdefault("findings", [])
+        find_id = f"FIND-{len(findings) + 1:03d}"
+        ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+        rec = {
+            "id": find_id,
+            "title": title,
+            "category": category,
+            "severity": severity.lower(),
+            "status": status.lower(),
+            "description": description,
+            "evidence": evidence_refs or [],
+            "created_at": ts,
+            "analyst": analyst,
+        }
+        findings.append(rec)
+        self.log_action("RECORD_FINDING", f"Created finding {find_id}: {title} [{severity.upper()}]", analyst)
+        return rec
+
+    def add_ioc(
+        self,
+        value: str,
+        ioc_type: str = "domain",
+        context: str = "",
+        source: str = "Manual Record",
+        confidence: str = "high",
+        analyst: str = "Analyst"
+    ) -> Dict[str, Any]:
+        iocs = self.data.setdefault("iocs", [])
+        ioc_id = f"IOC-{len(iocs) + 1:03d}"
+        ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+        rec = {
+            "id": ioc_id,
+            "type": ioc_type.lower(),
+            "value": value.strip(),
+            "context": context,
+            "source": source,
+            "confidence": confidence.lower(),
+            "first_seen": ts,
+            "last_seen": ts,
+        }
+        iocs.append(rec)
+        self.log_action("ADD_IOC", f"Registered observable {ioc_id} ({ioc_type}: {value})", analyst)
+        return rec
+
+    def add_event(
+        self,
+        timestamp_str: str,
+        title: str,
+        description: str = "",
+        source: str = "Manual Record",
+        severity: str = "info",
+        evidence_ref: str = "",
+        analyst: str = "Analyst"
+    ) -> Dict[str, Any]:
+        events = self.data.setdefault("timeline", [])
+        evt_id = f"EVT-{len(events) + 1:04d}"
+
+        rec = {
+            "id": evt_id,
+            "timestamp": timestamp_str,
+            "title": title,
+            "description": description,
+            "source": source,
+            "severity": severity.lower(),
+            "evidence_ref": evidence_ref,
+        }
+        events.append(rec)
+        self.log_action("ADD_TIMELINE_EVENT", f"Timeline event {evt_id} recorded ({title})", analyst)
+        return rec
+
+    add_timeline_event = add_event
+
+    def get_summary(self) -> Dict[str, Any]:
+        evidence = self.data.get("evidence", [])
+        findings = self.data.get("findings", [])
+        iocs = self.data.get("iocs", [])
+        timeline = self.data.get("timeline", [])
+
+        high_sev = sum(1 for f in findings if f.get("severity") in ("high", "critical"))
+        unique_ips = len({i["value"] for i in iocs if i.get("type") in ("ipv4", "ipv6", "ip")})
+        unique_doms = len({i["value"] for i in iocs if i.get("type") == "domain"})
+        unique_emails = len({i["value"] for i in iocs if i.get("type") == "email"})
+
+        return {
+            "case_id": self.case_id,
+            "case_name": self.data.get("case_name", "Untitled Case"),
+            "analyst": self.data.get("analyst", "Analyst"),
+            "status": self.data.get("status", "active"),
+            "created_at": self.data.get("created_at", "-"),
+            "total_evidence": len(evidence),
+            "total_findings": len(findings),
+            "high_severity_findings": high_sev,
+            "total_iocs": len(iocs),
+            "unique_ips": unique_ips,
+            "unique_domains": unique_doms,
+            "unique_emails": unique_emails,
+            "total_timeline_events": len(timeline),
+        }
+
+def create_case(name: str = "Forensic Investigation", analyst: str = "Analyst", case_id: Optional[str] = None) -> Case:
+    """Initializes a new case directory and case.json."""
+    if not case_id:
+        rand_suffix = hashlib.sha256(f"{name}{datetime.datetime.now()}".encode()).hexdigest()[:6].upper()
+        date_str = datetime.datetime.now().strftime("%Y%m%d")
+        case_id = f"CASE-{date_str}-{rand_suffix}"
+
+    case = Case(case_id)
+    case.case_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+    case.data = {
+        "case_id": case_id,
+        "case_name": name,
+        "analyst": analyst,
+        "status": "active",
+        "created_at": ts,
+        "evidence": [],
+        "findings": [],
+        "iocs": [],
+        "timeline": [],
+        "chain_of_custody": [],
+    }
+    case.save()
+    case.log_action("CREATE_CASE", f"Initialized new case: {name} ({case_id})", analyst)
+
+    # Set as active case
+    cfg = load_config()
+    cfg["active_case"] = case_id
+    save_config(cfg)
+
+    return case
+
+def get_active_case() -> Optional[Case]:
+    cfg = load_config()
+    cid = cfg.get("active_case", "")
+    if cid:
+        c = Case(cid)
+        if c.exists():
+            return c
+    return None
+
+def set_active_case(case_id: str) -> bool:
+    c = Case(case_id)
+    if c.exists():
+        cfg = load_config()
+        cfg["active_case"] = case_id
+        save_config(cfg)
+        return True
+    return False
+
+def list_all_cases() -> List[Dict[str, Any]]:
+    ws = get_workspace_dir()
+    results = []
+    if not ws.exists():
+        return results
+    for entry in sorted(ws.iterdir()):
+        if entry.is_dir() and (entry / "case.json").exists():
+            c = Case(entry.name)
+            results.append(c.get_summary())
+    return results

traceforge/catalog.py

@@ -0,0 +1,202 @@
+import csv
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from traceforge.config import get_project_root
+from traceforge.platform_detect import is_tool_installed, which_tool
+
+class ToolRecord:
+    def __init__(
+        self,
+        tool_id: int,
+        name: str,
+        binary: str,
+        category: str,
+        subcategory: str,
+        ecosystem: str,
+        mac_install: str,
+        linux_install: str,
+        description: str,
+        status: str,
+        requires_root: bool,
+        requires_api: bool,
+        requires_hardware: bool,
+        notes: str,
+        source_url: str,
+        termux_status: str = "supported",
+        termux_package: str = "-",
+        termux_install: str = "-",
+        termux_notes: str = "",
+        termux_root: bool = False,
+        termux_api: bool = False,
+        termux_hardware: bool = False,
+    ):
+        self.id = tool_id
+        self.name = name
+        self.binary = binary
+        self.category = category
+        self.subcategory = subcategory
+        self.ecosystem = ecosystem
+        self.mac_install = mac_install
+        self.linux_install = linux_install
+        self.description = description
+        self.status = status
+        self.requires_root = requires_root
+        self.requires_api = requires_api
+        self.requires_hardware = requires_hardware
+        self.notes = notes
+        self.source_url = source_url
+
+        # Termux specific fields
+        self.termux_status = termux_status
+        self.termux_package = termux_package
+        self.termux_install = termux_install
+        self.termux_notes = termux_notes
+        self.termux_root = termux_root
+        self.termux_api = termux_api
+        self.termux_hardware = termux_hardware
+
+    @property
+    def is_installed(self) -> bool:
+        return is_tool_installed(self.binary)
+
+    @property
+    def binary_path(self) -> Optional[str]:
+        return which_tool(self.binary)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "binary": self.binary,
+            "category": self.category,
+            "subcategory": self.subcategory,
+            "ecosystem": self.ecosystem,
+            "mac_install": self.mac_install,
+            "linux_install": self.linux_install,
+            "description": self.description,
+            "status": self.status,
+            "requires_root": self.requires_root,
+            "requires_api": self.requires_api,
+            "requires_hardware": self.requires_hardware,
+            "notes": self.notes,
+            "source_url": self.source_url,
+            "termux_status": self.termux_status,
+            "termux_package": self.termux_package,
+            "termux_install": self.termux_install,
+            "termux_notes": self.termux_notes,
+            "termux_root": self.termux_root,
+            "termux_api": self.termux_api,
+            "termux_hardware": self.termux_hardware,
+            "is_installed": self.is_installed,
+            "binary_path": self.binary_path,
+        }
+
+def get_bundled_catalog_path() -> Path:
+    """Resolves the canonical tools.tsv path from package data or repository root."""
+    pkg_data = Path(__file__).resolve().parent / "data" / "tools.tsv"
+    if pkg_data.exists():
+        return pkg_data
+    repo_data = get_project_root() / "catalog" / "tools.tsv"
+    if repo_data.exists():
+        return repo_data
+    return pkg_data
+
+Tool = ToolRecord
+
+class Catalog:
+    """Parses and indexes the canonical tool registry in catalog/tools.tsv."""
+
+    def __init__(self, tsv_path: Optional[Path] = None):
+        if tsv_path is None:
+            tsv_path = get_bundled_catalog_path()
+        self.tsv_path = Path(tsv_path)
+        self.tools: List[ToolRecord] = []
+        self._by_id: Dict[int, ToolRecord] = {}
+        self._by_bin: Dict[str, ToolRecord] = {}
+        self.load()
+
+    def __len__(self) -> int:
+        return len(self.tools)
+
+    def load(self) -> None:
+        if not self.tsv_path.exists():
+            return
+        self.tools.clear()
+        self._by_id.clear()
+        self._by_bin.clear()
+
+        with open(self.tsv_path, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for row in reader:
+                try:
+                    tid = int(row.get("id", "0"))
+                    record = ToolRecord(
+                        tool_id=tid,
+                        name=row.get("name", ""),
+                        binary=row.get("binary", ""),
+                        category=row.get("category", ""),
+                        subcategory=row.get("subcategory", ""),
+                        ecosystem=row.get("ecosystem", "native"),
+                        mac_install=row.get("mac_install", ""),
+                        linux_install=row.get("linux_install", ""),
+                        description=row.get("description", ""),
+                        status=row.get("status", "verified"),
+                        requires_root=row.get("requires_root", "no").lower() in ("yes", "true", "1"),
+                        requires_api=row.get("requires_api", "no").lower() in ("yes", "true", "1"),
+                        requires_hardware=row.get("requires_hardware", "no").lower() in ("yes", "true", "1"),
+                        notes=row.get("notes", ""),
+                        source_url=row.get("source_url", ""),
+                        termux_status=row.get("termux_status", "supported"),
+                        termux_package=row.get("termux_package", "-"),
+                        termux_install=row.get("termux_install", "-"),
+                        termux_notes=row.get("termux_notes", ""),
+                        termux_root=row.get("termux_root", "no").lower() in ("yes", "true", "1"),
+                        termux_api=row.get("termux_api", "no").lower() in ("yes", "true", "1"),
+                        termux_hardware=row.get("termux_hardware", "no").lower() in ("yes", "true", "1"),
+                    )
+                    self.tools.append(record)
+                    self._by_id[tid] = record
+                    self._by_bin[record.binary.lower()] = record
+                except Exception:
+                    continue
+
+    def get_by_id(self, tool_id: int) -> Optional[ToolRecord]:
+        return self._by_id.get(tool_id)
+
+    def get_by_binary(self, binary_name: str) -> Optional[ToolRecord]:
+        return self._by_bin.get(binary_name.lower())
+
+    def search(self, query: str) -> List[ToolRecord]:
+        q = query.lower().strip()
+        if not q:
+            return self.tools.copy()
+        results = []
+        for t in self.tools:
+            if (
+                q in t.name.lower()
+                or q in t.binary.lower()
+                or q in t.category.lower()
+                or q in t.subcategory.lower()
+                or q in t.description.lower()
+                or q in t.notes.lower()
+                or q in t.termux_notes.lower()
+                or q in t.termux_package.lower()
+            ):
+                results.append(t)
+        return results
+
+    def get_categories(self) -> List[str]:
+        seen = set()
+        cats = []
+        for t in self.tools:
+            if t.category and t.category not in seen:
+                seen.add(t.category)
+                cats.append(t.category)
+        return cats
+
+    def filter_by_category(self, category: str) -> List[ToolRecord]:
+        return [t for t in self.tools if t.category == category]
+
+    def filter_by_termux_status(self, termux_status: str) -> List[ToolRecord]:
+        return [t for t in self.tools if t.termux_status == termux_status]