Skip to content

Latest commit

 

History

History
96 lines (73 loc) · 4.93 KB

README.md

File metadata and controls

96 lines (73 loc) · 4.93 KB

Binary Internals Viewer

An application to show binary file internals visually & interactively for the meaning of every bit.

Supported Formats

Sample

  • Here is a screen shot opening java.lang.String.class file

Sample Class

Download

User guide

  • We need the java command to run this tool
    • java -jar binaryinternals.viewer-3.7.jar
    • Menu item: File > Open...
    • Choose the binary file to view

Web Server and API

  • The BinaryInternalsWeb module provides the same file view in a web page, and an HTTP API, using the same format plug-ins
  • Run with Docker, from the repository root
    • docker build -f BinaryInternalsWeb/Dockerfile -t binaryinternals-web .
    • docker run --rm -p 8080:8080 --read-only --tmpfs /tmp --memory 512m --cpus 1 binaryinternals-web
    • Open http://localhost:8080
  • Run with Docker Compose, from the repository root
    • docker compose -f BinaryInternalsWeb/docker-compose.yml up -d --build, settings in docker-compose.yml
    • docker compose -f BinaryInternalsWeb/docker-compose.yml down to stop
  • Run without Docker, after ./mvnw install
    • java -jar BinaryInternalsWeb/target/binaryinternals.web-3.7.jar
    • Or, as a Java module: java -p BinaryInternalsWeb/target/libs:BinaryInternalsWeb/target/binaryinternals.web-3.7.jar -m org.binaryinternals.web/org.binaryinternals.web.WebServer
  • API
    • GET /api/v1/formats - the supported formats and file extensions
    • POST /api/v1/parse?name=Foo.class - the request body is the file content, the response is the JSON tree of the file
      • curl --compressed --data-binary @Foo.class "http://localhost:8080/api/v1/parse?name=Foo.class"
      • Each node: {"text": "magic: CAFEBABE", "start": 0, "length": 4, "icon": "Magic", "description": "...", "children": [...]}
      • icon, description and children are left out when absent; description is HTML
      • Errors: {"status": 415, "error": "..."} with status 400, 405, 413 (too large), 415 (unsupported type), 422 (invalid file), 503 (busy), 504 (timeout)
    • GET /health - health check
    • Uploaded files are only kept in a temporary file during the parsing
  • Settings, by environment variables
    • HOST (default 127.0.0.1, 0.0.0.0 in Docker), PORT (default 8080)
    • MAX_UPLOAD_MB (default 20), MAX_CONCURRENT_PARSES (default: number of processors), PARSE_TIMEOUT_SECONDS (default 30)
    • CORS_ORIGIN (default *, empty to disable)

Build the Source Code

  • Prerequisite
    • Java Version: JDK 25 or higher
    • Set JAVA_HOME environment variable
      • If not set use the export statements in the build.sh script
    • Build Tool: no Maven installation needed, the Maven Wrapper (./mvnw, mvnw.cmd on Windows) downloads the Maven version set in maven-wrapper.properties on its first run, and checks it against distributionSha256Sum
    • To change the Maven version, update both values in maven-wrapper.properties, e.g. for Maven 3.10.0:
      • ./mvnw wrapper:wrapper -Dmaven=3.10.0 -DdistributionSha256Sum=<sha256>, without -DdistributionSha256Sum the check is removed
      • <sha256>: curl -sO https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.10.0/apache-maven-3.10.0-bin.zip && shasum -a 256 apache-maven-3.10.0-bin.zip, after checking the zip against its published .sha512
  • MacOS need to install the Linux style commands
    • brew install coreutils
    • brew install parallel
    • brew install graphviz
  • Build
    • ./mvnw clean install, or ./mvnw -Prelease clean install with the javadoc and sources jars
    • ./build.sh (Linux/MacOS/Windows Git Bash)
    • build.ps1 (Windows PowerShell)

Structure

  • This application does not have 3rd party dependency other than JDK, easy to add it to your existing project

Dependency Graph

Java Class Viewer

  • The original Java Class Viewer has been renamed and merged into Binary Internals Viewer since Apr 2021

Standalone Libs

The FormatXXXX.jar files can be used in your project when needed.