{"id":13577641,"url":"https://github.com/trailofbits/osquery-extensions","last_synced_at":"2025-10-27T15:05:41.958Z","repository":{"id":27525230,"uuid":"112785593","full_name":"trailofbits/osquery-extensions","owner":"trailofbits","description":"osquery extensions by Trail of Bits","archived":false,"fork":false,"pushed_at":"2023-04-12T18:13:08.000Z","size":10004,"stargazers_count":264,"open_issues_count":18,"forks_count":36,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-07-05T19:09:54.605Z","etag":null,"topics":["intrusion-detection","monitoring","osquery","security","sql"],"latest_commit_sha":null,"homepage":"https://blog.trailofbits.com/2017/12/14/announcing-the-trail-of-bits-osquery-extension-repository/","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/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}},"created_at":"2017-12-01T20:51:22.000Z","updated_at":"2025-07-01T06:36:35.000Z","dependencies_parsed_at":"2024-01-15T19:45:36.917Z","dependency_job_id":"653cf166-f713-4583-9d58-a19cc3ede9cb","html_url":"https://github.com/trailofbits/osquery-extensions","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/trailofbits/osquery-extensions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fosquery-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fosquery-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fosquery-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fosquery-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/osquery-extensions/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fosquery-extensions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274847801,"owners_count":25360978,"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","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["intrusion-detection","monitoring","osquery","security","sql"],"created_at":"2024-08-01T15:01:23.200Z","updated_at":"2025-10-27T15:05:36.927Z","avatar_url":"https://github.com/trailofbits.png","language":"C","readme":"# Trail of Bits osquery Extensions\n\nThis repository includes [osquery](https://osquery.io/) [extensions](https://osquery.readthedocs.io/en/stable/development/osquery-sdk/) developed and maintained by [Trail of Bits](https://www.trailofbits.com/). If you would like to sponsor the development of an extension, [please contact us](https://www.trailofbits.com/contact/).\n\n[Extensions](https://osquery.readthedocs.io/en/stable/deployment/extensions/) are a type of osquery add-on that can be loaded at runtime to provide new virtual tables. The extensions interface allows organizations to implement proprietary detection methods, or address their individual needs. Here, we use it to demonstrate other pioneering use cases of osquery.\n\nIn extensions, we can add capabilities that go beyond what would be possible in osquery core. Trail of Bits has developed extensions to provide tables that can _manage_ service configurations as well as _view_ them, or that can cross-check information on the host with external third-party services.\n\nTo learn more about osquery extensions development and why developing outside of 'core' is encouraged for demonstrating new use cases or novel functionality, view our talk ([slides](https://github.com/trailofbits/presentations/tree/master/Osquery%20Extensions), [video](https://www.youtube.com/watch?v=g46rjoP18EE)) from QueryCon 2018.\n\n## Extensions\n\n| Extension            | Description | Supported Endpoints |\n|          :-:         |    :-:      |         :-:         |\n| efigy                | Integrates osquery with the Duo Labs EFIgy API to determine if the EFI firmware on your Mac fleet is up-to-date. | macOS |\n| santa                | Integrates osquery with the Santa application whitelisting solution. Check DENY events and manage the whitelist/blacklist rules. | macOS |\n| fwctl                | Provides osquery with the ability to view and manage the OS-native firewall rules and `/etc/hosts` file (port and host blocking). | macOS, Linux, Windows |\n| ntfs_forensics       | Provides osquery with NTFS-specific forensic information for incident responders. | Windows |\n| windows_sync_objects | Provides osquery with the ability of listing and locking Windows synchronization objects (mutants, events, semaphores). | Windows |\n| mdm_enrollment       | Provides a table that reports MDM enrollment status.                                       | macOS |\n| iptables             | Provides a superset of the information supplied by the default `iptables` table | Linux |\n| (more to come)       | ...  | ...   |\n\n## Experimental extensions\n\n| Extension            | Description | Supported Endpoints |\n|          :-:         |    :-:      |         :-:         |\n| network_monitor      | Provides an event-based table that lists DNS requests performed by the endpoint. Uses libpcap and Pcap++ to capture and parse network requests.  | Linux   |\n\n\n## Retired extensions\n\n| Extension            | Description | Supported Endpoints | Notes |\n|          :-:         |    :-:      |         :-:         |  :-:  |\n| darwin_unified_log   | Provided an event driven table that contains entries from the unified system log on MacOS. | macOS | API updates on macOS 10.15 permit moving this functionality into core osquery. |\n\n## Building\n\nNote: the [releases](https://github.com/trailofbits/osquery-extensions/releases) page has download links for our extensions. The instructions below are only necessary for those interested in building from source.\n\nAt a high-level, the steps are:\n1. Follow the osquery guide at https://osquery.readthedocs.io/en/latest/development/building/\n   to install pre-requisites and build but stop just before the configure step.\n2. Clone the osquery-extensions repo.\n3. Symlink the osquery-extensions folder into `osquery/external/extension_trailofbits`.\n4. Resume following the osquery build guide to build osquery and now the extensions too.\n\nHere are example steps for each platform:\n\n### Linux/macOS\n\n```shell\n# Follow https://osquery.readthedocs.io/en/latest/development/building/\n# and stop before the configure step\ncd ../../\ngit clone --recurse-submodules https://github.com/trailofbits/osquery-extensions.git\n\ncd osquery\nln -s ../../osquery-extensions external/extension_trailofbits  # note: the link's target path is relative to the link, not cwd\n\ncd build\n# Resume following the osquery build guide\n```\n\n### Windows 10\n\n```powershell\n# Follow https://osquery.readthedocs.io/en/latest/development/building/\n# and stop before the configure step\ncd ..\\..\\\ngit clone --recurse-submodules https://github.com/trailofbits/osquery-extensions.git\n\ncd osquery\nNew-Item -ItemType SymbolicLink -Name external\\extension_trailofbits -Target C:\\osquery-extensions\n\ncd build\n# Resume following the osquery build guide\n```\n\n### Specifying the extensions to be built\n\nBy default, all of our extensions for a given OS are built into one executable. It's also possible to select which extensions to build, using the `TRAILOFBITS_EXTENSIONS_TO_BUILD` environment variable and specifying a comma separated list of extension names. For example, if you wish to build both the `windows_sync_objects` and `fwctl` extensions on Windows, you can set it to:\n\n```shell\n$env:TRAILOFBITS_EXTENSIONS_TO_BUILD = \"windows_sync_objects,fwctl\"\n```\n\n**Note:** The `network_monitor` extension stands alone as a separate executable, because it's a network listener that drops its own privileges at runtime.\n\n### Finding the executable binary\n\nThis is where the extension should be available once it has been built:\n\n * Linux: `osquery/build/external/extension_trailofbits/trailofbits_osquery_extensions.ext` (except `network_monitor`, which is in `osquery/build/external/extension_trailofbits/extensions/network_monitor/network_monitor.ext`)\n * macOS: `osquery/build/external/extension_trailofbits/trailofbits_osquery_extensions.ext`\n * Windows: `osquery\\build\\external\\Release\\trailofbits_osquery_extensions.ext.exe`\n\n### Running the automated tests\n\nmacOS or Linux: once osquery has been built with tests enabled (*i.e.*, *with* `-DOSQUERY_BUILD_TESTS=ON` CMake option), enter the build folder and run the following command: `cmake --build . --target trailofbits_extensions_tests`.\n\nWindows: tests are not yet supported on Windows.\n\n## Usage\n\nTo quickly test an extension, you can either start it from the `osqueryi` shell, or launch it manually and wait for it to connect to the running osquery instance. An example of the former: `\u003e osqueryi --extension build/external/extension_trailofbits/trailofbits_osquery_extensions.ext`\n\nNote that the `network_monitor` extension, because it drops its privileges at runtime, is not compatible with being bundled together in the single extension with the others. It must be loaded separately from its own extension file in `build/external/extension_trailofbits/extensions/network_monitor/network_monitor.ext`.\n\nBy default, osquery does not want to load extensions that are not owned by root. You can either change the ownership of the `.ext` file to root, or run osquery with the `--allow_unsafe` flag.\n\n```shell\n$ sudo osqueryi --extension osquery/build/external/extension_trailofbits/trailofbits_osquery_extensions.ext\nUsing a virtual database. Need help, type '.help'\nosquery\u003e SELECT * FROM efigy;\n+--------------------+-----------------+--------------------+-------------------+------------+---------------------+\n| latest_efi_version | efi_version     | efi_version_status | latest_os_version | os_version | build_number_status |\n+--------------------+-----------------+--------------------+-------------------+------------+---------------------+\n| MBP142.0167.B00    | MBP142.0167.B00 | success            | 10.12.6           | 10.12.6    | success             |\n+--------------------+-----------------+--------------------+-------------------+------------+---------------------+\nosquery\u003e\n```\n\nSee the [osquery documentation on extensions](https://osquery.readthedocs.io/en/stable/deployment/extensions) for further information.\n\n## Contributing\n\nDo you have an idea for an osquery extension? Please [file an issue](https://github.com/trailofbits/osquery-extensions/issues/new) for it. We welcome contributions of bug fixes, bug reports, feature requests, and new extensions. For more information on how you can contribute, see our [Contributing Guidelines](https://github.com/trailofbits/osquery-extensions/blob/master/CONTRIBUTING.md).\n\n## Troubleshooting\n\nWhen troubleshooting, ensure you are running `osqueryd`/`osqueryi` with the `--verbose` flag.\n\nAs mentioned above, if you encounter the following error, you need change the owner of the `trailofbits_osquery_extensions.ext` file to be the root account, or else run osquery with the `--allow_unsafe` flag: `watcher.cpp:535] [Ref #1382] Extension binary has unsafe permissions:1`\n\n## License\n\nThe code in this repository is licensed under the [Apache 2.0 license](LICENSE).\n","funding_links":[],"categories":["C","osquery extensions"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fosquery-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fosquery-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fosquery-extensions/lists"}