trace/README.md

trace - Digital Evidence Log Utility

trace is a bare-bones, terminal-centric note-taking utility for digital forensics and incident response. It is designed for maximum operational efficiency, ensuring that the integrity of your log data is never compromised by the need to slow down.

This tool mandates minimal system overhead, relying solely on standard libraries where possible.

⚡ Key Feature: Hot Logging (CLI Shorthand)

The primary operational benefit of trace is its ability to accept input directly from the command line, bypassing the full interface. Once your active target context is set, you can drop notes instantly.

Configuration: Use the TUI to set a Case or Evidence ID as "Active" (a). This state persists across sessions.

Syntax for Data Injection:

# Log an immediate status update
trace "IR team gained shell access. Initial persistence checks running."

# Log data and tag it for later triage
trace "Observed outbound connection to 192.168.1.55 on port 80. #suspicious #network"

System Integrity Chain: Each command-line note is immediately stamped, concatenated with its content, and hashed using SHA256 before storage. This ensures a non-repudiable log entry.

Installation & Deployment

Platform: Linux / UNIX (including macOS)

Prerequisites: Python 3.x and the binary build utility (PyInstaller).

Deployment:

1. Build Binary: Execute the build script in the source directory.

   ./build_binary.sh
   

   The output executable will land in dist/trace.

2. Path Integration: For universal access, the binary must reside in a directory referenced by your $PATH environment variable (e.g., /usr/local/bin).

   # Place executable in system path
   sudo mv dist/trace /usr/local/bin/
   
   # Ensure execute bit is set
   sudo chmod +x /usr/local/bin/trace
   

   You are now cleared to run trace from any shell prompt.

Platform: Windows

Prerequisites: Python 3.x, pyinstaller, and the windows-curses library.

Deployment:

1. Build Binary: Run the build command in a PowerShell or CMD environment.

   pyinstaller --onefile --name trace --clean --paths . --hidden-import curses main.py
   

   The executable is located at dist\trace.exe.

2. Path Integration: The executable must be accessible via your user or system %PATH% variable for the hot-logging feature to function correctly.

   Option A: System Directory (Requires Administrator Privilege)

   Copy-Item dist\trace.exe C:\Windows\System32\
   

   Option B: User-Defined Bin Directory (Recommended)

   # Create the user bin location
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\bin"
   Copy-Item dist\trace.exe "$env:USERPROFILE\bin\"
   
   # Inject the directory into the User PATH variable
   [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\bin", "User")
   

   ATTENTION: You must cycle your command shell (exit and reopen) before the trace command will resolve correctly.

Core Feature Breakdown

Feature	Description	Operational Impact
Integrity Hashing	SHA256 applied to every log entry (content + timestamp).	Guaranteed log integrity. No modification possible post-entry.
GPG Signing	Optional PGP/GPG signature applied to notes.	Non-repudiation for formal evidence handling.
IOC Extraction	Automatic parsing of IPv4, FQDNs, URLs, hashes, and email addresses.	Immediate intelligence gathering from raw text.
Tag System	Supports #hashtags for classification and filtering.	Efficient triage of large log sets.
Minimal Footprint	Built solely on Python standard library modules.	Maximum portability on restricted forensic environments.

TUI Reference (Management Console)

Execute trace (no arguments) to enter the Text User Interface. This environment is used for setup, review, and reporting.

Key	Function	Detail
a	Set Active	Designate the current item as the target for CLI injection (hot-logging).
n	New Note	Enter the multi-line log editor. Use \text{Ctrl+G} to save block.
i	IOC Index	View extracted indicators. Option to export IOC list (e).
t	Tag Index	View classification tags and filter notes by frequency.
v	Full View	Scrollable screen showing all log entries with automatic IOC/Tag highlighting.
/	Filter	Initiate text-based search/filter on lists.
\text{Enter}	Drill Down	Access details for Case or Evidence.
q	Exit	Close the application.

Report Generation

To generate the Markdown report package, use the --export flag.

trace --export
# Creates trace_export.md in the current directory.

Data Persistence

Trace maintains a simple flat-file structure in the user's home directory.

• ~/.trace/data.json: Case log repository.
• ~/.trace/state: Active context pointer.

---

License: MIT