{"id":19888936,"url":"https://github.com/paypal/heap-dump-tool","last_synced_at":"2025-04-04T21:06:07.961Z","repository":{"id":43721449,"uuid":"338195378","full_name":"paypal/heap-dump-tool","owner":"paypal","description":"Tool to sanitize data from Java heap dumps.","archived":false,"fork":false,"pushed_at":"2025-03-15T05:04:25.000Z","size":499,"stargazers_count":121,"open_issues_count":0,"forks_count":21,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T20:05:50.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paypal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-12T01:11:12.000Z","updated_at":"2025-03-27T08:56:53.000Z","dependencies_parsed_at":"2023-11-28T07:29:52.906Z","dependency_job_id":"bcd77d13-e0b2-4775-9deb-c41265a29ae1","html_url":"https://github.com/paypal/heap-dump-tool","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fheap-dump-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fheap-dump-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fheap-dump-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fheap-dump-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paypal","download_url":"https://codeload.github.com/paypal/heap-dump-tool/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T18:08:41.914Z","updated_at":"2025-04-04T21:06:07.937Z","avatar_url":"https://github.com/paypal.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heap Dump Tool\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.paypal/heap-dump-tool/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.paypal/heap-dump-tool)\n\nHeap Dump Tool can capture and, more importantly, sanitize sensitive data from Java heap dumps. Sanitization is accomplished\nby replacing field values in the heap dump file with zero values. Heap dump can then be more freely shared freely and analyzed.\n\nA typical scenario is when a heap dump needs to be sanitized before it can be given to another person or moved to a different\nenvironment. For example, an app running in production environment may contain sensitive data (passwords, credit card\nnumbers, etc) which should not be viewable when the heap dump is copied to a development environment for analysis with a\ngraphical program.\n\n\u003cimg src=\"https://github.com/paypal/heap-dump-tool/raw/statics/heap-dump-file.png\"/\u003e\n\n---\n\n\u003cimg src=\"https://github.com/paypal/heap-dump-tool/raw/statics/sanitized-heap-dump-file.png\"/\u003e\n\n## TOC\n  * [Examples](#examples)\n  * [Usage](#usage)\n  * [License](#license)\n\t\n## Examples\n\nThe tool can be run in several ways depending on tool's packaging and where the target to-be-captured app is running.\n\n#### [Jar] Capture sanitized heap dump manually\n\nSimplest way to capture sanitized heap dump of an app is to run:\n\n```\n# capture plain heap dump of Java process with given pid\n$ jcmd {pid} GC.heap_dump /path/to/plain-heap-dump.hprof\n\n# then sanitize the heap dump\n$ wget -O heap-dump-tool.jar https://repo1.maven.org/maven2/com/paypal/heap-dump-tool/1.3.0/heap-dump-tool-1.3.0-all.jar\n$ java -jar heap-dump-tool.jar sanitize /path/to/plain-dump.hprof /path/to/sanitized-dump.hprof\n```\n\n\u003cbr/\u003e\n\n#### [Jar] Capture sanitized heap dump of a containerized app\n\nSuppose the tool is a packaged jar on the host, and the target app is running as the only Java process within a container.\n\nThen, to capture sanitized heap dump of a containerized app, run:\n\n```\n# list docker containers\n$ docker ps\nCONTAINER ID        IMAGE                                [...]   NAMES\n06e633da3494        registry.example.com/my-app:latest   [...]   my-app\n\n# capture and sanitize\n$ wget -O heap-dump-tool.jar https://repo1.maven.org/maven2/com/paypal/heap-dump-tool/1.3.0/heap-dump-tool-1.3.0-all.jar\n$ java -jar heap-dump-tool.jar capture my-app\n```\n\nNote that a plain stack dump is also captured.\n\n\u003cbr/\u003e\n\n#### [Docker] Capture sanitized heap dump of a containerized app\n\nSuppose the tool is a Docker image, and the target app is running as the only Java process within a container.\n\nThen, to capture sanitized heap dump of another containerized app, run:\n\n```\n# list docker containers\n$ docker ps\nCONTAINER ID        IMAGE                                [...]   NAMES\n06e633da3494        registry.example.com/my-app:latest   [...]   my-app\n\n# capture and sanitize\n$ docker run heapdumptool/heapdumptool capture my-app | bash\n```\n\nIf the container runs multiple Java processes, pid can be specified:\n```\n# list docker containers\n$ docker ps\nCONTAINER ID        IMAGE                                [...]   NAMES\n06e633da3494        registry.example.com/my-app:latest   [...]   my-app\n\n# find pid\n$ jps\n$ ps aux\n\n# capture and sanitize\n$ docker run heapdumptool/heapdumptool capture my-app -p {pid} | bash\n```\n\n\u003cbr/\u003e\n\n#### Sanitize hs_err* Java fatal error logs\n\nTo sanitize environment variables in hs_err* files, you can run:\n\n```\n# with java -jar\n$ wget -O heap-dump-tool.jar https://repo1.maven.org/maven2/com/paypal/heap-dump-tool/1.3.0/heap-dump-tool-1.3.0-all.jar\n$ java -jar heap-dump-tool.jar sanitize-hserr input-hs_err.log outout-hs_err.log\n\n# Or, with docker\n$ docker run heapdumptool/heapdumptool sanitize-hserr input-hs_err.log outout-hs_err.log | bash\n```\n\n### [Library] Embed within an app\n\nTo use it as a library and embed it within another app, you can declare it as dependency in maven:\n\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.paypal\u003c/groupId\u003e\n  \u003cartifactId\u003eheap-dump-tool\u003c/artifactId\u003e\n  \u003cversion\u003e1.3.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n## Usage\n\n```\njava -jar heap-dump-tool.jar  help\nUsage: heap-dump-tool [-hV] [COMMAND]\nTool for capturing or sanitizing heap dumps\n  -h, --help      Show this help message and exit.\n  -V, --version   Print version information and exit.\nCommands:\n  capture   Capture sanitized heap dump of a containerized app\n  sanitize  Sanitize a heap dump by replacing byte and char array contents\n  sanitize-hserr  Sanitize fatal error log by censoring environment variable values\n  help      Displays help information about the specified command\n```\n\nAdditional usage for sub-commands can be found by running `help {sub-command}`. For example:\n\n```\n$ java -jar heap-dump-tool.jar help capture\nUsage: heap-dump-tool sanitize [OPTIONS] \u003cinputFile\u003e \u003coutputFile\u003e\nSanitize a heap dump by replacing byte and char array contents\n      \u003cinputFile\u003e    Input heap dump .hprof. File or stdin\n      \u003coutputFile\u003e   Output heap dump .hprof. File, stdout, or stderr\n  -a, --tar-input    Treat input as tar archive\n  -b, --buffer-size=\u003cbufferSize\u003e\n                     Buffer size for reading and writing\n                       Default: 100MB\n  -d, --docker-registry=\u003cdockerRegistry\u003e\n                     docker registry hostname for bootstrapping heap-dump-tool docker image\n  -e, --exclude-string-fields=\u003cexcludeStringFields\u003e\n                     String fields to exclude from sanitization. Value in com.example.MyClass#fieldName format\n                       Default: java.lang.Thread#name,java.lang.ThreadGroup#name\n  -f, --force-string-coder-match=\u003cforceMatchStringCoder\u003e\n                     Force strings coder values to match sanitizationText.coder value\n                       Default: true\n  -s, --sanitize-byte-char-arrays-only\n                     Sanitize byte/char arrays only\n                       Default: true\n  -S, --sanitize-arrays-only\n                     Sanitize arrays only\n                       Default: false\n  -t, --text=\u003csanitizationText\u003e\n                     Sanitization text to replace with\n                       Default: \\0\n  -z, --zip-output   Write zipped output\n                       Default: false\n```\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n\n## Whitepaper\n\nSee [whitepaper (pdf)](https://github.com/paypal/heap-dump-tool/blob/statics/whitepaper.pdf)\n\n## License\n\nHeap Dump Tool is Open Source software released under the Apache 2.0 license.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Fheap-dump-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaypal%2Fheap-dump-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Fheap-dump-tool/lists"}