{"id":13677752,"url":"https://github.com/google/gwpsan","last_synced_at":"2025-04-29T11:31:42.424Z","repository":{"id":242488479,"uuid":"807307623","full_name":"google/gwpsan","owner":"google","description":"GWPSan: Sampling-Based Sanitizer Framework","archived":false,"fork":false,"pushed_at":"2025-03-20T17:46:40.000Z","size":379,"stargazers_count":316,"open_issues_count":0,"forks_count":9,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-19T22:27:23.993Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","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/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-28T21:13:43.000Z","updated_at":"2025-04-14T14:27:50.000Z","dependencies_parsed_at":"2024-06-12T06:43:53.169Z","dependency_job_id":"38b20ced-3e1d-4370-b8a3-22ef1e3d57bb","html_url":"https://github.com/google/gwpsan","commit_stats":null,"previous_names":["google/gwpsan"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fgwpsan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fgwpsan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fgwpsan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fgwpsan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/gwpsan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251493932,"owners_count":21598198,"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-08-02T13:00:46.557Z","updated_at":"2025-04-29T11:31:41.261Z","avatar_url":"https://github.com/google.png","language":"C++","funding_links":[],"categories":["Profiling"],"sub_categories":[],"readme":"# GWPSan: Sampling-Based Sanitizer Framework\n\nGWPSan is a framework for low-overhead sampling-based dynamic binary\ninstrumentation, designed for implementing various bug detectors (also called\n\"sanitizers\") suitable for production uses. GWPSan does not modify the executed\ncode, but instead performs dynamic analysis from signal handlers.\n\nCompared with non-sampling dynamic analysis, GWPSan trades performance for\nprecision, allowing it to be enabled where more expensive dynamic analysis\nwould otherwise not be feasible (such as in production). The idea is that with\nenough total uptime, GWPSan will detect bugs in code not typically covered by\nnon-production test workloads. One way to quickly achieve a large enough total\nuptime is when deployed across a fleet of machines.\n\n\u003e Note: GWPSan is inspired by\n\u003e [GWP-ASan](https://github.com/google/sanitizers/tree/master/gwp-asan/icse2024),\n\u003e but their design and implementation are completely different. GWP-ASan is\n\u003e much simpler and only provides sampling-based heap memory-safety error\n\u003e detection, and is typically embedded in the system heap allocator.\n\u003e\n\u003e GWPSan and GWP-ASan complement each other, where GWPSan aims to be a more\n\u003e generic framework to implement dynamic analysis.\n\u003e\n\u003e The acronym \"GWP\" in both tools' names is originally derived from\n\u003e [Google-Wide\n\u003e Profiling](https://research.google/pubs/google-wide-profiling-a-continuous-profiling-infrastructure-for-data-centers/),\n\u003e due to relying on sampling, but otherwise have no relation with GWP.\n\nMore documentation can be found [here](docs/).\n\n## Usage\n\nTo use GWPSan, you have to build GWPSan and link it (statically or dynamically)\ninto a binary of interest. For most GWPSan \"tools\", the target binary must be\ncompiled with additional compiler flags, to add required [metadata\nsections](https://llvm.org/docs/PCSectionsMetadata.html). GWPSan currently\nrequires Clang 18 or later, and Linux kernel 6.4 or later\n([details](docs/dependencies.md)); support for the x86-64 and arm64\narchitectures is currently implemented. [Bazel](https://bazel.build/) is\nrequired to build GWPSan.\n\nTo build GWPSan static and dynamic runtime libraries:\n\n```\nCC=\u003cpath to clang-18 or later\u003e\nCXX=\u003cpath to clang++-18 or later\u003e\nbazel build --action_env=CC=\"$CC\" --action_env=CXX=\"$CXX\" -c opt \\\n\t\t$( [[ $(uname -m) == \"x86_64\" ]] \u0026\u0026 echo --config=x86_64 ) \\\n\t\t//gwpsan/unified:libgwpsan.so //gwpsan/unified:gwpsan_archive\n```\n\nIf the `clang` and `clang++` binaries in your `PATH` are already version 18 or\nlater, you may omit explicitly setting CC and CXX. Some combinations of the GNU\nC++ Library (libstdc++) and Clang versions may be incompatible; if you run into\nproblems, try with the LLVM C++ Library (libc++) by additionally passing\n`--config=libc++` to the Bazel command.\n\nTo build the target binary with statically linked runtime (adapt to your build\nsystem):\n\n```\nGWPSAN_CFLAGS=-fexperimental-sanitize-metadata=atomics,uar\nclang++ $GWPSAN_CFLAGS -c example.cpp -o example.o\n...\nclang++ -o example example.o ... \\\n        -Wl,--whole-archive \"${GWPSAN_ROOT}/bazel-bin/gwpsan/unified/libgwpsan.a\" -Wl,--no-whole-archive\n```\n\nTo use the dynamically linked GWPSan runtime with a binary that has been build\nwith `GWPSAN_CFLAGS` but does not link the runtime statically:\n\n```\nclang++ $GWPSAN_CFLAGS -c example.cpp -o example.o\n...\nclang++ -o example example.o ...\nLD_PRELOAD=\"${GWPSAN_ROOT}/bazel-bin/gwpsan/unified/libgwpsan.so\" ./example\n```\n\n### Tunable flags\n\nGWPSan has a number of tunable flags with reasonable defaults. If necessary,\nthe flags can be tuned with `GWPSAN_OPTIONS` environment variable. To see all\navailable flags, set `GWPSAN_OPTIONS=help` and run a binary with the GWPSan\nruntime linked in; this will show help for all flags and immediately exit\nwithout running the main program. Multiple flags can be separated by `:`.\n\n\u003e Note: Boolean flags can be enabled with either `GWPSAN_OPTIONS=foobar` or\n\u003e `GWPSAN_OPTIONS=foobar=1`; to explicitly disable, `GWPSAN_OPTIONS=foobar=0`.\n\n### Enabling sampling and tools\n\nBy default, GWPSan is completely disabled and none of its bug detectors (also\ncalled *tools*) are enabled. To enable GWPSan sampling, and crash on errors (in\nproduction you may not always want to set `halt_on_error`):\n\n```\n# Sample once per second, and crash on detected errors:\nexport GWPSAN_OPTIONS=sample_interval_usec=1000000:halt_on_error\n```\n\nWith that, GWPSan only enables periodic sampling, but no tools are enabled yet.\n\n\u003e Note: Sampling without enabled tools may be useful to test that a program\n\u003e tolerates receiving signals while in system calls. Error handling of system\n\u003e calls and C library functions must properly handle EINTR; retrying on EINTR\n\u003e should be sufficient (see\n\u003e [TEMP_FAILURE_RETRY](https://www.gnu.org/software/libc/manual/html_node/Interrupted-Primitives.html)).\n\nThe following [tools](docs/tools.md) are available:\n\n-   `tsan` detects [data\n    races](https://en.cppreference.com/w/cpp/language/multithread#Data_races).\n    Enabled/disabled with `GWPSAN_OPTIONS=tsan=0/1`.\n-   `uar` detects use-after-return bugs. Enabled/disabled with\n    `GWPSAN_OPTIONS=uar=0/1`.\n-   `lmsan` detects uses of uninit values (experimental). Enabled/disabled with\n    `GWPSAN_OPTIONS=lmsan=0/1`.\n\nFor example, to enable all tools:\n\n```\n# Sample once per second, crash on detected errors, and enable all tools:\nexport GWPSAN_OPTIONS=sample_interval_usec=1000000:halt_on_error:tsan:uar:lmsan\n```\n\n## Testing\n\nTo test GWPSan changes, or new toolchains and kernels:\n\n```\nCC=\u003cpath to clang-18 or later\u003e\nCXX=\u003cpath to clang++-18 or later\u003e\nbazel test --action_env=CC=\"$CC\" --action_env=CXX=\"$CXX\" --config=dev \\\n\t\t$( [[ $(uname -m) == \"x86_64\" ]] \u0026\u0026 echo --config=x86_64 ) \\\n        //gwpsan/...\n```\n\n## License\n\nThe GWPSan library is licensed under the terms of the Apache license. See\nLICENSE for more information.\n\n## Disclaimer\n\nThis is not an officially supported Google product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fgwpsan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fgwpsan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fgwpsan/lists"}