{"id":18894092,"url":"https://github.com/trailofbits/blight","last_synced_at":"2025-04-04T17:04:17.942Z","repository":{"id":37063743,"uuid":"274726054","full_name":"trailofbits/blight","owner":"trailofbits","description":"A framework for instrumenting build tools","archived":false,"fork":false,"pushed_at":"2024-12-01T17:15:52.000Z","size":396,"stargazers_count":85,"open_issues_count":22,"forks_count":7,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-28T16:04:30.581Z","etag":null,"topics":["build-system","build-tool","compiler-wrapper","hacktoberfest","instrumentation"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/blight","language":"Python","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/trailofbits.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-24T17:12:32.000Z","updated_at":"2025-03-28T08:02:47.000Z","dependencies_parsed_at":"2024-03-22T01:42:19.731Z","dependency_job_id":"d6af52af-2730-429f-b81e-8764fa1aaa13","html_url":"https://github.com/trailofbits/blight","commit_stats":{"total_commits":244,"total_committers":8,"mean_commits":30.5,"dds":"0.32377049180327866","last_synced_commit":"73d29b73addf1871e3cd05fadb7efd2da4445f38"},"previous_names":["trailofbits/canker"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fblight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fblight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fblight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fblight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/blight/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217173,"owners_count":20903008,"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":["build-system","build-tool","compiler-wrapper","hacktoberfest","instrumentation"],"created_at":"2024-11-08T08:17:49.073Z","updated_at":"2025-04-04T17:04:17.919Z","avatar_url":"https://github.com/trailofbits.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# blight\n\n![CI](https://github.com/trailofbits/blight/workflows/CI/badge.svg)\n[![PyPI version](https://badge.fury.io/py/blight.svg)](https://badge.fury.io/py/blight)\n[![Downloads](https://pepy.tech/badge/blight)](https://pepy.tech/project/blight)\n\n`blight` is a framework for wrapping and instrumenting build tools and build\nsystems. It contains:\n\n1. A collection of high-fidelity models for various common build tools (e.g.\n   the C and C++ compilers, the standard linker, the preprocessor, etc.);\n1. A variety of \"actions\" that can be run on each build tool or specific\n   classes of tools (e.g. \"whenever the build system invokes `$CC`, add this\n   flag\");\n1. Command-line wrappers (`blight-env` and `blight-exec`) for instrumenting\n   builds.\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Quickstart](#quickstart)\n- [Cookbook](#cookbook)\n- [Goals](#goals)\n- [Anti-goals](#anti-goals)\n- [Contributing](#contributing)\n\n## Installation\n\n`blight` is available on PyPI and is installable via `pip`:\n\n```bash\npython -m pip install blight\n```\n\nPython 3.8 or newer is required.\n\n## Usage\n\n`blight` comes with two main entrypoints:\n\n- `blight-exec`: directly execute a command within a `blight`-instrumented\n  environment\n- `blight-env`: write a `sh`-compatible environment definition to `stdout`,\n  which the shell or other tools can consume to enter a `blight`-instrumented\n  environment\n\nIn most cases, you'll probably want `blight-exec`. `blight-env` can be thought\nof as the \"advanced\" or \"plumbing\" interface.\n\n\u003c!-- @begin-blight-exec-help@ --\u003e\n\n```text\nUsage: blight-exec [OPTIONS] TARGET [ARGS]...\n\nOptions:\n  --guess-wrapped      Attempt to guess the appropriate programs to wrap\n  --swizzle-path       Wrap via PATH swizzling\n  --stub STUB          Stub a command out while swizzling\n  --shim SHIM          Add a custom shim while swizzling\n  --action ACTION      Enable an action\n  --journal-path PATH  The path to use for action journaling\n  --help               Show this message and exit.\n```\n\n\u003c!-- @end-blight-exec-help@ --\u003e\n\n\u003c!-- @begin-blight-env-help@ --\u003e\n\n```text\nUsage: blight-env [OPTIONS]\n\nOptions:\n  --guess-wrapped  Attempt to guess the appropriate programs to wrap\n  --swizzle-path   Wrap via PATH swizzling\n  --stub TEXT      Stub a command out while swizzling\n  --shim TEXT      Add a custom shim while swizzling\n  --unset          Unset the tool variables instead of setting them\n  --help           Show this message and exit.\n```\n\n\u003c!-- @end-blight-env-help@ --\u003e\n\n## Quickstart\n\nThe easiest way to get started with `blight` is to use `blight-exec` with\n`--guess-wrapped` and `--swizzle-path`. These flags tell `blight` to configure\nthe environment with some common-sense defaults:\n\n- `--guess-wrapped`: guess the appropriate underlying tools to invoke from\n  the current `PATH` and other runtime environment;\n- `--swizzle-path`: rewrite the `PATH` to put some common build tool shims\n  first, e.g. redirecting `cc` to `blight-cc`.\n\nFor example, the following will run `cc -v` under `blight`'s instrumentation,\nwith the [`Demo`](https://trailofbits.github.io/blight/blight/actions.html#Demo)\naction:\n\n```bash\nblight-exec --action Demo --swizzle-path --guess-wrapped -- cc -v\n```\n\nwhich should produce something like:\n\n```console\n[demo] before-run: /usr/bin/cc\nApple clang version 14.0.0 (clang-1400.0.29.202)\nTarget: x86_64-apple-darwin22.2.0\nThread model: posix\nInstalledDir: /Library/Developer/CommandLineTools/usr/bin\n[demo] after-run: /usr/bin/cc\n```\n\nWe can also see the effect of `--swizzle-path` by running `which cc` under\n`blight`, and observing that it points to a temporary shim rather than the\nnormal `cc` location:\n\n```bash\n$ blight-exec --swizzle-path --guess-wrapped -- which cc\n/var/folders/zj/hy934vnj5xs68zv6w4b_f6s40000gn/T/tmp5uahp6tg@blight-swizzle@/cc\n\n$ which cc\n/usr/bin/cc\n```\n\nAll the `Demo` action does is print a message before and after each tool run,\nallowing you to diagnose when a tool is or isn't correctly instrumented.\nSee the [actions documentation below](#enabling-actions) for information on\nusing and configuring more interesting actions.\n\n## Cookbook\n\n### Running `blight` against a `make`-based build\n\nMost `make`-based builds use `$(CC)`, `$(CXX)`, etc., which means that they\nshould work out of the box with `blight-exec`:\n\n```bash\nblight-exec --guess-wrapped -- make\n```\n\nIn some cases, poorly written builds may hard-code `cc`, `clang`, `gcc`, etc.\nrather than using their symbolic counterparts. For these, you can use\n`--swizzle-path` to interpose shims that redirect those hardcoded tool\ninvocations back to `blight`'s wrappers:\n\n```bash\nblight-exec --guess-wrapped --swizzle-path -- make\n```\n\nSee [Taming an uncooperative build with shims and stubs](#taming-an-uncooperative-build-with-shims-and-stubs)\nfor more advanced techniques for dealing with poorly written build systems.\n\n### Enabling actions\n\nActions are where `blight` really shines: they allow you to run arbitrary Python\ncode before and after each build tool invocation.\n\n`blight` comes with built-in actions, which are\n[documented here](https://trailofbits.github.io/blight/blight/actions.html).\nSee each action's Python module for its documentation.\n\nActions can be enabled in two different ways:\n\n- With the `--action` flag, which can be passed multiple times. For example,\n  `--action SkipStrip --action Record` enables both the\n  [`SkipStrip`](https://trailofbits.github.io/blight/blight/actions.html#SkipStrip)\n  and [`Record`](https://trailofbits.github.io/blight/blight/actions.html#Record)\n  actions.\n\n- With the `BLIGHT_ACTIONS` environment variable, which can take multiple\n  actions delimited by `:`. For example, `BLIGHT_ACTIONS=SkipStrip:Record`\n  is equivalent to `--action SkipStrip --action Record`.\n\nActions are run in the order of specification with duplicates removed, meaning\nthat `BLIGHT_ACTIONS=Foo:Bar:Foo` is equivalent to `BLIGHT_ACTIONS=Foo:Bar`\nbut **not** `BLIGHT_ACTIONS=Bar:Foo`. This is important if actions have side\neffects, which they may (such as modifying the tool's flags).\n\n#### Action configuration\n\nSome actions accept or require additional configuration, which is passed\nthrough the `BLIGHT_ACTION_{ACTION}` environment variable in `key=value`\nformat, where `{ACTION}` is the uppercased name of the action.\n\nFor example, to configure `Record`'s output file:\n\n```bash\nBLIGHT_ACTION_RECORD=\"output=/tmp/output.jsonl\"\n```\n\n#### Action outputs\n\nThere are two ways to get output from actions under `blight`:\n\n- Many actions support an `output` configuration value, which should be a\n  filename to write to. This allows each action to write its own output\n  file.\n- `blight` supports a \"journaling\" mode, in which all action outputs\n  are written to a single file, keyed by action name.\n\nThe \"journaling\" mode is generally encouraged over individual outputs,\nand can be enabled with either `BLIGHT_JOURNAL_PATH=/path/to/output.jsonl`\nin the environment or `blight-exec --journal-path /path/to/output.jsonl`.\n\n### Configuring an environment with `blight-env`\n\n`blight-env` behaves exactly the same as `blight-exec`, except that it\nstops before actually executing anything. You can use it to set up an\nenvironment for use across multiple build system runs.\n\nBy default, `blight-env` will just export the appropriate environment\nfor replacing `CC`, etc., with their `blight` wrappers:\n\n```bash\n$ blight-env\nexport CC=blight-cc\nexport CXX=blight-c++\nexport CPP=blight-cpp\nexport LD=blight-ld\nexport AS=blight-as\nexport AR=blight-ar\nexport STRIP=blight-strip\nexport INSTALL=blight-install\n```\n\n`--guess-wrapped` augments this by adding a best-guess underlying tool for\neach wrapper:\n\n```bash\n$ blight-env --guess-wrapped\nexport BLIGHT_WRAPPED_CC=/usr/bin/cc\nexport BLIGHT_WRAPPED_CXX=/usr/bin/c++\nexport BLIGHT_WRAPPED_CPP=/usr/bin/cpp\nexport BLIGHT_WRAPPED_LD=/usr/bin/ld\nexport BLIGHT_WRAPPED_AS=/usr/bin/as\nexport BLIGHT_WRAPPED_AR=/usr/bin/ar\nexport BLIGHT_WRAPPED_STRIP=/usr/bin/strip\nexport BLIGHT_WRAPPED_INSTALL=/usr/bin/install\nexport CC=blight-cc\nexport CXX=blight-c++\nexport CPP=blight-cpp\nexport LD=blight-ld\nexport AS=blight-as\nexport AR=blight-ar\nexport STRIP=blight-strip\nexport INSTALL=blight-install\n```\n\n`--guess-wrapped` also respects `CC`, etc. in the environment:\n\n```bash\n$ CC=/some/custom/cc blight-env --guess-wrapped\nexport BLIGHT_WRAPPED_CC=/some/custom/cc\nexport BLIGHT_WRAPPED_CXX=/usr/bin/c++\nexport BLIGHT_WRAPPED_CPP=/usr/bin/cpp\nexport BLIGHT_WRAPPED_LD=/usr/bin/ld\nexport BLIGHT_WRAPPED_AS=/usr/bin/as\nexport BLIGHT_WRAPPED_AR=/usr/bin/ar\nexport BLIGHT_WRAPPED_STRIP=/usr/bin/strip\nexport BLIGHT_WRAPPED_INSTALL=/usr/bin/install\nexport CC=blight-cc\nexport CXX=blight-c++\nexport CPP=blight-cpp\nexport LD=blight-ld\nexport AS=blight-as\nexport AR=blight-ar\nexport STRIP=blight-strip\nexport INSTALL=blight-install\n```\n\n`--swizzle-path` further modifies the environment by rewriting `PATH`:\n\n```bash\n$ blight-env --guess-wrapped-swizzle-path\nexport BLIGHT_WRAPPED_CC=/usr/bin/cc\nexport BLIGHT_WRAPPED_CXX=/usr/bin/c++\nexport BLIGHT_WRAPPED_CPP=/usr/bin/cpp\nexport BLIGHT_WRAPPED_LD=/usr/bin/ld\nexport BLIGHT_WRAPPED_AS=/usr/bin/as\nexport BLIGHT_WRAPPED_AR=/usr/bin/ar\nexport BLIGHT_WRAPPED_STRIP=/usr/bin/strip\nexport BLIGHT_WRAPPED_INSTALL=/usr/bin/install\nexport PATH='/var/folders/zj/hy934vnj5xs68zv6w4b_f6s40000gn/T/tmpxh5ryu22@blight-swizzle@:/bin:/usr/bin:/usr/local/bin'\nexport CC=blight-cc\nexport CXX=blight-c++\nexport CPP=blight-cpp\nexport LD=blight-ld\nexport AS=blight-as\nexport AR=blight-ar\nexport STRIP=blight-strip\nexport INSTALL=blight-install\n```\n\nThe swizzled addition can be identified by its `@blight-swizzle@` directory name.\n\n### Taming an uncooperative build with shims and stubs\n\nSometimes build systems need more coaxing than just `--guess-wrapped` and\n`--swizzle-path`. Common examples include:\n\n- Hard-coding a particular tool or tool version rather than using the symbolic\n  name (e.g. `clang-7 example.c` instead of `$(CC) example.c`);\n- Running lots of \"junk\" commands that can be suppressed (e.g. lots of `echo`\n  invocations)\n\nYou can use _shims_ and _stubs_ to smooth out these cases:\n\n- _shims_ replace a command with a build tool that `blight` knows about, e.g.\n  `clang-3.8` with `cc`.\n- _stubs_ replace a command with an invocation of `true`, meaning that it\n  does nothing and never fails.\n\nShims are specified with `--shim cmd:tool`, while stubs are specified with\n`--stub cmd`. Both require `--swizzle-path`, since the `PATH` must be rewritten\nto inject additional commands.\n\nFor example, to instrument a build system that hardcodes `tcc` everywhere\nand that spews way too much output with `echo`:\n\n```bash\nblight-exec --guess-wrapped --swizzle-path --shim tcc:cc --stub echo -- make\n```\n\n## Goals\n\n- Wrapping `CC`, `CXX`, `CPP`, `LD`, `AS`, `AR`, `STRIP`, and `INSTALL`.\n- Providing a visitor-style API for each of the above, pre- and post-execution.\n- Providing a nice set of default actions.\n- Being as non-invasive as possible.\n\n## Anti-goals\n\n- Using `LD_PRELOAD` to capture every `exec` in a build system,\n  a la [Bear](https://github.com/rizsotto/Bear).\n- Supporting `cl.exe`.\n- Detailed support for non C/C++ languages.\n\n## Contributing\n\nCheck out our [CONTRIBUTING.md](./CONTRIBUTING.md)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fblight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fblight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fblight/lists"}