- C++ 67.9%
- C 22.3%
- CMake 5.6%
- Objective-C++ 1.7%
- Python 1.7%
- Other 0.6%
0389185099## Summary - Extends the `yara` table to support scanning process memory via `yr_rules_scan_proc`, in addition to the existing file-path scanning - Adds a `pid` column to the table schema so users can target processes by PID - On Windows, temporarily elevates `SeDebugPrivilege` before scanning and restores it afterward, enabling scans of processes owned by other users - Adds `token_privileges.h` and `token_privileges.cpp` to facilitate token adjustment, as it is pretty common practice and could be seen as a utility function. - Adds unit tests for scan process - Some minor refactoring of `yara.cpp` Resolves: https://github.com/osquery/osquery/issues/8647 ## Example Usage I wrote a python script which will unpack an obfuscated string into memory, so that a string match rule would fail to match on the path, but will match on the process memory ### `test_yara_rule.yar` ```yara rule ProcessScanTestMarker { meta: description = "Matches unique marker string for osquery YARA process scan testing" author = "osquery test" date = "2026-03-02" strings: $marker = "OSQUERY_PROCESS_SCAN_TEST_MARKER_XYZZY_2026" condition: $marker } ``` ### `test_yara_target.py` ```python import os import sys import ctypes import base64 BASE_64_STRING = "T1NRVUVSWV9QUk9DRVNTX1NDQU5fVEVTVF9NQVJLRVJfWFlaWllfMjAyNg==" def main() -> None: try: # Decode the marker into a regular Python string – it now lives in # this process's heap memory where a YARA process scan can find it. marker = base64.b64decode(BASE_64_STRING) # Also stash it in a ctypes buffer to guarantee a contiguous C-string # representation in memory (useful for scanners that read raw memory). c_marker = ctypes.create_string_buffer(marker) # Reference both objects so they are not garbage-collected while waiting. _ = (marker, c_marker) print(f"[+] Marker decoded into memory: {marker.decode()}") print(f"[+] PID: {os.getpid()}") print("[*] Waiting — press Enter or Ctrl+C to exit...") input() except KeyboardInterrupt: print("\n[+] Exiting.") if __name__ == "__main__": main() ``` #### Run the target script ```cmd C:\git\osquery>python test_yara_target.py [+] Marker decoded into memory: OSQUERY_PROCESS_SCAN_TEST_MARKER_XYZZY_2026 [+] PID: 6084 [*] Waiting — press Enter or Ctrl+C to exit... ``` #### Demonstrate that the rule does not match against the file on disk ```sql osquery> SELECT * ...> FROM yara ...> WHERE path = 'C:\git\osquery\test_yara_target.py' ...> AND sigfile = 'C:\git\osquery\test_yara_rule.yar'; +------------------------------------+-----+---------+-------+-----------+-----------------------------------+---------+------+ | path | pid | matches | count | sig_group | sigfile | strings | tags | +------------------------------------+-----+---------+-------+-----------+-----------------------------------+---------+------+ | C:\git\osquery\test_yara_target.py | | | 0 | | C:\git\osquery\test_yara_rule.yar | | | +------------------------------------+-----+---------+-------+-----------+-----------------------------------+---------+------+ ``` #### Demonstrate that the rule does match against the running process ```sql osquery> SELECT yara.*, processes.cmdline ...> FROM yara ...> JOIN processes ...> USING(pid) ...> WHERE pid = 6084 ...> AND sigfile = 'C:\git\osquery\test_yara_rule.yar'; +------+------+-----------------------+-------+-----------+-----------------------------------+---------------------+------+-----------------------------+ | path | pid | matches | count | sig_group | sigfile | strings | tags | cmdline | +------+------+-----------------------+-------+-----------+-----------------------------------+---------------------+------+-----------------------------+ | | 6084 | ProcessScanTestMarker | 1 | | C:\git\osquery\test_yara_rule.yar | $marker:206464d9810 | | python test_yara_target.py | +------+------+-----------------------+-------+-----------+-----------------------------------+---------------------+------+-----------------------------+ ``` ``` |
||
|---|---|---|
| .cursor/rules | ||
| .github | ||
| cmake | ||
| docs | ||
| external | ||
| libraries | ||
| osquery | ||
| packs | ||
| plugins | ||
| specs | ||
| tests | ||
| tools | ||
| .artifactignore | ||
| .clang-format | ||
| .cursorignore | ||
| .gitignore | ||
| .gitmodules | ||
| .readthedocs.yml | ||
| .watchmanconfig | ||
| ASSURANCE.md | ||
| CHANGELOG.md | ||
| CMakeLists.txt | ||
| CODE_OF_CONDUCT.md | ||
| CODEOWNERS | ||
| CONTRIBUTING.md | ||
| Doxyfile | ||
| LICENSE | ||
| LICENSE-Apache-2.0 | ||
| LICENSE-GPL-2.0 | ||
| mkdocs.yml | ||
| README.md | ||
| SECURITY.md | ||
| SUPPORT.md | ||
| Vagrantfile | ||
osquery
osquery is a SQL powered operating system instrumentation, monitoring, and analytics framework.
Available for Linux, macOS, and Windows.
Information and resources
- Homepage: osquery.io
- Downloads: osquery.io/downloads
- Documentation: ReadTheDocs
- Stack Overflow: Stack Overflow questions
- Table Schema: osquery.io/schema
- Slack: Browse the archives or Join the conversation
- Build Status:
- CII Best Practices:
What is osquery?
osquery exposes an operating system as a high-performance relational database. This allows you to write SQL-based queries to explore operating system data. With osquery, SQL tables represent abstract concepts such as running processes, loaded kernel modules, open network connections, browser plugins, hardware events or file hashes.
SQL tables are implemented via a simple plugin and extensions API. A variety of tables already exist and more are being written: https://osquery.io/schema. To best understand the expressiveness that is afforded to you by osquery, consider the following SQL queries:
List the users:
SELECT * FROM users;
Check the processes that have a deleted executable:
SELECT * FROM processes WHERE on_disk = 0;
Get the process name, port, and PID, for processes listening on all interfaces:
SELECT DISTINCT processes.name, listening_ports.port, processes.pid
FROM listening_ports JOIN processes USING (pid)
WHERE listening_ports.address = '0.0.0.0';
Find every macOS LaunchDaemon that launches an executable and keeps it running:
SELECT name, program || program_arguments AS executable
FROM launchd
WHERE (run_at_load = 1 AND keep_alive = 1)
AND (program != '' OR program_arguments != '');
Check for ARP anomalies from the host's perspective:
SELECT address, mac, COUNT(mac) AS mac_count
FROM arp_cache GROUP BY mac
HAVING count(mac) > 1;
Alternatively, you could also use a SQL sub-query to accomplish the same result:
SELECT address, mac, mac_count
FROM
(SELECT address, mac, COUNT(mac) AS mac_count FROM arp_cache GROUP BY mac)
WHERE mac_count > 1;
These queries can be:
- performed on an ad-hoc basis to explore operating system state using the osqueryi shell
- executed via a scheduler to monitor operating system state across a set of hosts
- launched from custom applications using osquery Thrift APIs
Download & Install
To download the latest stable builds and for repository information and installation instructions visit https://osquery.io/downloads.
We use a simple numbered versioning scheme X.Y.Z, where X is a major version, Y is a minor, and Z is a patch.
We plan minor releases roughly every two months. These releases are tracked on our Milestones page. A patch release is used when there are unforeseen bugs with our minor release and we need to quickly patch.
A rare 'revision' release might be used if we need to change build configurations.
Major, minor, and patch releases are tagged on GitHub and can be viewed on the Releases page. We open a new Release Checklist issue when we prepare a minor release. If you are interested in the status of a release, please find the corresponding checklist issue, and note that the issue will be marked closed when we are finished the checklist. We consider a release 'in testing' during the period of hosting new downloads on our website and adding them to our hosted repositories. We will mark the release as 'stable' on GitHub when enough testing has occurred, this usually takes two weeks.
Build from source
Building osquery from source is encouraged! Check out our build guide. Also check out our contributing guide and join the community on Slack.
Osquery fleet managers
There are many osquery fleet managers out there. The osquery project does not endorse, recommend, or test these. They are provided as a starting point
| Project | License |
|---|---|
| Fleet | Open Core |
| Kolide | Commercial |
| OSCTRL | Open Source |
| Zentral | Open Source |
License
By contributing to osquery you agree that your contributions will be licensed as defined on the LICENSE file.
Vulnerabilities
We keep track of security announcements in our tagged version release notes on GitHub. We aggregate these into SECURITY.md too.
Learn more
The osquery documentation is available online. Documentation for older releases can be found by version number, as well.
If you're interested in learning more about osquery read the launch blog post for background on the project, visit the users guide.
Development and usage discussion is happening in the osquery Slack, grab an invite here!