Tracefish

A terminal-first HAR file analysis and extraction tool written in pure Kotlin.

---

Overview

tracefish allows developers and analysts to slice, inspect, and extract data from recorded web browser network traffic entirely from the command line. It compiles down to a single, portable standalone JAR, making it easy to run and integrate into local developer workflows.

---

Features

• Resilient Parsing: Maps noisy browser HAR exports into clean, strongly-typed structures while ignoring system/browser-specific extensions.
• Request Inspection & Filtering: View, search, and filter network transactions by domain host, HTTP method, response status, or path fragment.
• Detailed Extraction: Inspect complete header payloads and automatically decode and pretty-print JSON response bodies.
• Latency Timeline Charting: Renders a horizontal ASCII waterfall timeline showing request execution overlaps and latency bottlenecks.
• Client Code Generation: Translate any logged network request into a runnable curl, Python requests, or native Kotlin java.net.http client snippet.
• Binary Asset Exporting: Extract and decode base64-encoded response assets (such as images, PDFs, or fonts) and write them directly to your disk.
• Traffic Metrics: Generate high-level analytics on total data transferred, average request latency, and status code distributions with the option to print complete records.
• Automated Scrubbing: Instantly strip sensitive headers and cookies to safely share sanitised logs.

---

Installation & Setup

Prerequisites

• Java Runtime: Java 21 or higher must be installed on your machine.

Quick Download & Run

Use wget to pull the compiled JAR file directly from this repository:

wget https://github.com/Professor-Archbishop/tracefish/raw/main/tracefish.jar

(Or if you prefer curl):

curl -L https://github.com/Professor-Archbishop/tracefish/raw/main/tracefish.jar -o tracefish.jar

Once downloaded, you can run any command directly using java -jar:

java -jar tracefish.jar -f samples/example.har inspect

---

Running tracefish From Anywhere (Optional)

To run the JAR file from any directory using just the tracefish command, you can set up a shell alias in your terminal profile:

1. Save the JAR to a local folder:

   mkdir -p ~/.local/bin
   mv tracefish.jar ~/.local/bin/

2. Add the alias configuration:

   • For Zsh (Default on macOS and modern Linux):

     echo 'alias tracefish="java -jar $HOME/.local/bin/tracefish.jar"' >> ~/.zshrc
     source ~/.zshrc

   • For Bash (Standard on older Linux setups):

     echo 'alias tracefish="java -jar $HOME/.local/bin/tracefish.jar"' >> ~/.bashrc
     source ~/.bashrc

3. Run the command directly:

   tracefish -f samples/example.har inspect

---

Command Reference

In all commands below, replace traffic.har with the path to your target HAR file.

1. View all requests (inspect)

Render a styled table showing all recorded connections (Index, Method, URL, Status, Size, Time).

java -jar tracefish.jar -f traffic.har inspect

2. Filter transactions (filter)

Isolate requests by domain host, HTTP verb, status code, or path fragment.

java -jar tracefish.jar -f traffic.har filter --method POST
java -jar tracefish.jar -f traffic.har filter --host fonts.gstatic.com

3. Render a concurrency timeline (timeline)

Generate an ASCII horizontal waterfall chart illustrating request concurrency and bottlenecks.

java -jar tracefish.jar -f traffic.har timeline

4. Extract detailed headers & bodies (extract)

View headers and formatted JSON response bodies of a request using its list index or a partial URL match.

java -jar tracefish.jar -f traffic.har extract 0
java -jar tracefish.jar -f traffic.har extract "/api/v1/auth"

5. Generate client snippets (codegen)

Build copy-pasteable requests in curl, python, or kotlin.

java -jar tracefish.jar -f traffic.har codegen 5 --lang python

6. Export binary assets (export-asset)

Decode and extract base64-encoded response payloads (such as icons or images) and save them to your machine.

java -jar tracefish.jar -f traffic.har export-asset 12 -o output_image.png

7. Analyze performance and traffic metrics (stats)

Display upload/download volumes, average response times, top active host domains, and top-hit endpoint paths.

# Compact dashboard
java -jar tracefish.jar -f traffic.har stats

# Full, unfiltered domain and path inventory
java -jar tracefish.jar -f traffic.har stats -a

8. Search across traces (grep)

Scans request URLs, request bodies, and response bodies for a string or regex, outputting formatted text matches.

java -jar tracefish.jar -f traffic.har grep "sodar"

9. Sanitize logs (scrub)

Redacts sensitive authentication keys, bearer tokens, passwords, and cookies, saving the safe result to a file.

java -jar tracefish.jar -f traffic.har scrub -o clean_trace.har

10. Audit credentials & cookies (headers / cookies)

Display security-sensitive attributes across the trace.

java -jar tracefish.jar -f traffic.har headers
java -jar tracefish.jar -f traffic.har cookies

11. Compile OpenAPI schema skeletons (export)

Compile your captured traffic history into an OpenAPI 3.0 YAML specification skeleton.

java -jar tracefish.jar -f traffic.har export -o openapi.yaml

---

License

Distributed under the Apache-2.0 License. See LICENSE for more information.

---

Developer

• Author: Dennis Nganga (professor Archbishop)
• GitHub: Professor-Archbishop
• Contact: beyonddennisdreams@gmail.com
• Repository: https://github.com/Professor-Archbishop/tracefish