osql-experimental

What is osql-experimental?

osql-experimental is a community-oriented fork of osquery with support for CMake, public CI testing, and regular releases.

This repository contains the CMake build system for osql-experimental. The osquery-src folder is a submodule that contains Facebook's osquery experimental branch, unaltered.

Our development branch has the most updated version of Facebook's code. The master branch contains the latest release tag. The release branch contains the community release.

Slack channel?

You can find us in the #osql channel of the osquery Slack

Master (stable)

Platform	Build Status	Tests Status
Ubuntu 18.04
macOS 10.14
Windows

Development (unstable)

Platform	Build Status	Tests Status
Ubuntu 18.04
macOS 10.14
Windows

Migrating PRs from osquery

The build and release process, along with the merging strategy we propose, have been documented in detail in the following document. Reviews and suggestions from the community are well accepted.

We aim at providing stable and development releases in different flavours (i.e.: vanilla distribution, new features that we consider stable).
Please bear with us as we finalize the required infrastructure and CI changes.

How to build

osql-experimental supports Linux (Ubuntu 18.04/18.10), macOS, and Windows. Additional platforms are under consideration.

git, CMake (>= 3.13.3), clang 6.0, Python 2, and Python 3 are required to build. The rest of the dependencies are downloaded by CMake.

The default build type is RelWithDebInfo (optimizations active + debug symbols) and can be changed in the CMake configure phase by setting the CMAKE_BUILD_TYPE flag to Release or Debug.

The build type is chosen when building on Windows, not during the configure phase, through the --config option.

Linux

The root folder is assumed to be /home/<user>

Ubuntu 18.04

# Install the prerequisites
sudo apt install git llvm clang cmake libc++-dev libc++abi-dev liblzma-dev python python3

# Download and install a newer CMake (>= 3.13.3)
wget https://github.com/Kitware/CMake/releases/download/v3.13.4/cmake-3.13.4-Linux-x86_64.tar.gz
sudo tar xvf cmake-3.13.4-Linux-x86_64.tar.gz -C /usr/local --strip 1
# Verify that `/usr/local/bin` is in the `PATH` and comes before `/usr/bin`
# (optional) remove the old CMake system package with `sudo apt remove cmake`

# Download and build osql-experimental
cd $HOME; mkdir osql-experimental; cd osql-experimental
git clone --recurse-submodules https://github.com/osql/osql-experimental.git -b master src
mkdir build; cd build
cmake ../src -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build . -j # // where # is the number of parallel build jobs

Ubuntu 18.10

# Install the prerequisites
sudo apt install git llvm-6.0 clang-6.0 cmake libc++-dev libc++abi-dev liblzma-dev python python3

# Download and install a newer CMake (>= 3.13.3)
wget https://github.com/Kitware/CMake/releases/download/v3.13.4/cmake-3.13.4-Linux-x86_64.tar.gz
sudo tar xvf cmake-3.13.4-Linux-x86_64.tar.gz -C /usr/local --strip 1
# Verify that `/usr/local/bin` is in the `PATH` and comes before `/usr/bin`
# (optional) remove the old CMake system package with `sudo apt remove cmake`

# Download and build osql-experimental
cd $HOME; mkdir osql-experimental; cd osql-experimental
git clone --recurse-submodules https://github.com/osql/osql-experimental.git -b master src
mkdir build; cd build
cmake ../src -DCMAKE_C_COMPILER=clang-6.0 -DCMAKE_CXX_COMPILER=clang++-6.0 (-DBUILD_TESTING=ON for tests)
cmake --build . -j # // where # is the number of parallel build jobs

Windows

The root folder is assumed to be C:\Users\<user>

Step 1: Install the prerequisites

• CMake (>= 3.13.3): be sure to put it into the PATH
• Build Tools for Visual Studio 2017: from the installer choose the Workload Visual C++ build tools
• Git for Windows (or equivalent)
• Python 2
• Python 3

Step 2: Download and build osql-experimental

# Download using a PowerShell console
mkdir osql-experimental; cd osql-experimental
git clone --recurse-submodules https://github.com/osql/osql-experimental.git -b master src

# Configure
mkdir build; cd build
cmake ../src -G "Visual Studio 15 2017 Win64" -T host=x64

# Build
cmake --build . -j # // Number of projects to build in parallel

macOS

Please ensure homebrew has been installed. The root folder is assumed to be /Users/<user>

# Install prerequisites
brew install git cmake [email protected] [email protected] python

# Download and build osql-experimental
mkdir osql-experimental; cd osql-experimental
git clone --recurse-submodules https://github.com/osql/osql-experimental.git -b master src

# Configure
mkdir build; cd build
cmake ../src -DCMAKE_C_COMPILER=/usr/local/opt/[email protected]/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/[email protected]/bin/clang++

# Build
cmake --build . -j # // where # is the number of parallel build jobs

Tests

To build with tests active, add -DBUILD_TESTING=ON to the osql-experimental configure phase, then build the project. CTest will be used to run the tests and give a report.

Run tests on Windows

To run the tests and get just a summary report:
cmake --build . --config <RelWithDebInfo|Release|Debug> --target run_tests

To get more information when a test fails using powershell:

$Env:CTEST_OUTPUT_ON_FAILURE=1
cmake --build . --config <RelWithDebInfo|Release|Debug> --target run_tests

To run a single test, in verbose mode:
ctest -R <test name> -C <RelWithDebInfo|Release|Debug> -V

Run tests on Linux/macOS

To run the tests and get just a summary report:
cmake --build . --target test

To get more information when a test fails:
CTEST_OUTPUT_ON_FAILURE=1 cmake --build . --target test

To run a single test, in verbose mode:
ctest -R <test name> -V

License

The code in this repository is licensed under the Apache 2.0 license.