{"id":14008327,"url":"https://github.com/nh2/hatrace","last_synced_at":"2025-07-20T08:32:45.104Z","repository":{"id":66391004,"uuid":"171150513","full_name":"nh2/hatrace","owner":"nh2","description":"scriptable strace","archived":false,"fork":false,"pushed_at":"2020-07-22T21:37:29.000Z","size":710,"stargazers_count":123,"open_issues_count":17,"forks_count":24,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-05T21:34:24.262Z","etag":null,"topics":["haskell","strace","system-call-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nh2.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2019-02-17T17:27:17.000Z","updated_at":"2025-04-06T09:37:21.000Z","dependencies_parsed_at":"2023-05-09T14:18:32.442Z","dependency_job_id":null,"html_url":"https://github.com/nh2/hatrace","commit_stats":{"total_commits":256,"total_committers":22,"mean_commits":"11.636363636363637","dds":0.53515625,"last_synced_commit":"7258134d87915f035efd36babc685c80fb1df8cc"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nh2/hatrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nh2%2Fhatrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nh2%2Fhatrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nh2%2Fhatrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nh2%2Fhatrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nh2","download_url":"https://codeload.github.com/nh2/hatrace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nh2%2Fhatrace/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266092330,"owners_count":23875440,"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":["haskell","strace","system-call-analysis"],"created_at":"2024-08-10T11:01:35.281Z","updated_at":"2025-07-20T08:32:45.048Z","avatar_url":"https://github.com/nh2.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"[![CircleCI](https://circleci.com/gh/nh2/hatrace.svg?style=svg)](https://circleci.com/gh/nh2/hatrace)\n\n# hatrace - scripted `strace`\n\nIncludes:\n\n* `hatrace` executable similar to [`strace`](https://strace.io/)\n* Haskell library to write sophisticated scripts\n\n## Use cases\n\n* **General**\n  * Get all syscalls in a list and process them programmatically.\n  * Audit high-assurance software systems.\n  * Debug difficult bugs that occur only in certain rare situations.\n  * Change the results of system calls as seen by the traced program.\n* **Bug reproducers**\n  * Demonstrate how a program fails when a given syscall returns certain data.\n  * Kill your build tool at the 3rd `write()` syscall to an `.o` file, checking whether it will recover from that in the next run.\n* **Testing**\n  * Write test suites that assert how your code uses system calls, for correctness or performance.\n  * Mock syscalls to test how your program would behave in situations that are difficult to create in the real world, for example [verifying fault-tolerance in specific scenarios](https://tgrez.github.io/posts/2019-09-04-simulate-network-failures.html)\n  * Implement anomaly test suites [like `sqlite` does](https://www.sqlite.org/testing.html#i_o_error_testing), exhaustively testing whether your program can recover from a crash in _any_ syscall.\n* **Fuzzing**\n  * Insert garbage data into the program by changing syscall results or directly changing its memory contents.\n  * Speed up your fuzzing by having full insight into the fuzzed program's behaviour.\n* **Adding features to existing programs**\n  * Add \"magic\" support for new file systems without modifying existing programs (like [this paper](https://www.usenix.org/legacy/events/expcs07/papers/22-spillane.pdf) shows).\n  * Add logging capabilities to programs that were designed without.\n\n## Building / Installing\n\n* Clone: `git clone --recursive https://github.com/nh2/hatrace \u0026\u0026 cd hatrace`\n* After fetching new changes, update submodules with: `git submodule init \u0026\u0026 git submodule update --init --recursive`\n* Building for development:\n  * With [Stack](https://docs.haskellstack.org/en/stable/README/): `stack build` or even better `stack test`\n  * With [Cabal](https://www.haskell.org/cabal/): `cabal build` or even better `cabal test`\n  * Use a _recent_ version of these tools, e.g. at least Stack \u003e= 2.\n* Installing:\n  * With Stack: `stack install`\n  * With Cabal: `cabal install`\n\n## Work in progress\n\nThis software is work in progress.\n\nThe `hatrace` executable is extremely basic and can't do much.\n\nWhile syscall names are automatically generated, detail data needs to be implemented by hand and is done for only a few so far.\nHelp to add more is appreciated.\n\nHowever, the Haskell API to write scripts can already do a lot. Take a look at the test suite for examples.\n\n### TODO list for contributors\n\nIf you find any of the below topics interesting give it a shot!\nIt is recommended to file an issue when picking up one of the tasks to coordinate and avoid doing duplicate work.\n\n* [ ] Implement all the syscalls\n* [X] Remembering syscall arguments in a PID/TID map\n* [ ] Support for `sysenter`\n* [ ] reading tracee memory more efficiently (see [how strace does it](https://github.com/strace/strace/blob/d091f1a9e27756b3c399da1c500c915f473a56f3/ucopy.c#L45))\n* [ ] Helpers for modifying memory\n* [ ] One real-world example each for the use cases on `Use cases` above\n* [ ] `hatrace` executable features:\n  * [X] JSON output\n  * [ ] Coloured output\n  * [ ] Timing `strace -ttt` and `-T`\n  * [ ] special run modes tailored to specific tasks (e.g. execve tree)\n    * [ ] Show hanging syscalls\n    * [ ] Filter away GHC's spammy output around `sched_yield`, `futex` and signals\n* [ ] Support for setting options (for example enabling/disabling tracing into subprocesses, like `strace -f`)\n* [ ] Equivalent to `strace -y` (tracking origin of file descriptors, printing paths)\n* [ ] Equivalent to `strace -c` (keeping counts, summary statistics)\n* [ ] Something similar to `strace -y` but telling which PID is which executable from `/proc/PID/exe`\n* [ ] Extraction of `PTRACE_EVENT` detail information (see section `PTRACE_SETOPTIONS` in `man 2 ptrace`)\n* [ ] Filtering based on string buffer contents\n* [ ] PID remapping (e.g. to a range starting from 0) for better diffability of the output of multiple runs\n* [ ] Handling of `exit()` of the direct child (grand-child daemonisation)\n* [ ] Don't die on `peekBytes` returning `EIO` when the tracee passes invalid memory to the kernel; instead, peek only what's possible and print some info. That makes it possible to correctly trace processes that rely on e.g. `SIGSEGV` handlers.\n* [ ] Re-using strace's test suite for per-syscall tests\n* [ ] other TODOs in the code\n* Use it to do specific investigations in other programs:\n  * [ ] investigate [big GHC linker speed differences](https://github.com/nh2/hatrace/pull/9#issuecomment-477573945)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnh2%2Fhatrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnh2%2Fhatrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnh2%2Fhatrace/lists"}