-
Notifications
You must be signed in to change notification settings - Fork 1
Get Started
CTRLRLTY edited this page Nov 9, 2024
·
50 revisions
Currently, JARY is provided as an ELF64 shared module and must be compiled from the source code. Users must then load the libjary.so binary dynamically to use the module. The signature of all exposed functionality are all written in the jary.h header file within the include/jary/ directory of the project source code.
Compiling the shared module requires a couple of packages to be installed on your GNU/Linux system:
- cmake >= 3.22
- gcc >= 13.3
- libsqlite3 >= 3.4
Tested using the following gentoo configuration:
# equery list baselayout
* Searching for baselayout ...
[IP-] [ ] sys-apps/baselayout-2.15:0
# eselect kernel list
Available kernel symlink targets:
[1] linux-6.6.13-gentoo-dist *Compile the following packages:
# qlist -I -U -v cmake sqlite
dev-build/cmake-3.30.2 -dap -doc -gui ncurses -qt6 -test -verify-sig
dev-db/sqlite-3.46.0 -abi_mips_n32 -abi_mips_n64 -abi_mips_o32 -abi_s390_32 -abi_s390_64 abi_x86_32 abi_x86_64 -abi_x86_x32 -debug -doc icu readline -secure-delete -static-libs -tcl -test -toolsEmerge information
Portage 3.0.65 (python 3.12.3-final-0, default/linux/amd64/23.0/split-usr/desktop, gcc-13, glibc-2.39-r6, 6.6.13-gentoo-dist x86_64)
=================================================================
System uname: Linux-6.6.13-gentoo-dist-x86_64-11th_Gen_Intel-R-_Core-TM-_i5-11400H_@_2.70GHz-with-glibc2.39
KiB Mem: 32600216 total, 22577444 free
KiB Swap: 4194300 total, 4194300 free
Timestamp of repository gentoo: Sat, 28 Sep 2024 04:30:00 +0000
Head commit of repository gentoo: 57862311248969f2fd7dc61642cfb9fc146f3549
sh bash 5.2_p26-r6
ld GNU ld (Gentoo 2.42 p3) 2.42.0
app-misc/pax-utils: 1.3.7::gentoo
app-shells/bash: 5.2_p26-r6::gentoo
dev-build/autoconf: 2.13-r8::gentoo, 2.71-r7::gentoo
dev-build/automake: 1.16.5-r2::gentoo
dev-build/cmake: 3.30.2::gentoo
dev-build/libtool: 2.4.7-r4::gentoo
dev-build/make: 4.4.1-r1::gentoo
dev-build/meson: 1.5.1::gentoo
dev-lang/perl: 5.40.0::gentoo
dev-lang/python: 3.11.9_p2::gentoo, 3.12.3-r1::gentoo
dev-lang/rust-bin: 1.79.0::gentoo
sys-apps/baselayout: 2.15::gentoo
sys-apps/openrc: 0.54.2::gentoo
sys-apps/sandbox: 2.38::gentoo
sys-devel/binutils: 2.41-r3::gentoo, 2.42-r1::gentoo
sys-devel/binutils-config: 5.5::gentoo
sys-devel/clang: 16.0.6::gentoo, 17.0.6::gentoo, 18.1.8::gentoo
sys-devel/gcc: 13.3.1_p20240614::gentoo
sys-devel/gcc-config: 2.11::gentoo
sys-devel/lld: 17.0.6::gentoo, 18.1.8::gentoo
sys-devel/llvm: 16.0.6::gentoo, 17.0.6::gentoo, 18.1.8-r1::gentoo
sys-kernel/linux-headers: 6.6-r1::gentoo (virtual/os-headers)
sys-libs/glibc: 2.39-r6::gentoo
Repositories:
gentoo
location: /var/db/repos/gentoo
sync-type: rsync
sync-uri: rsync://rsync.gentoo.org/gentoo-portage
priority: -1000
volatile: False
sync-rsync-verify-metamanifest: yes
sync-rsync-verify-max-age: 3
sync-rsync-verify-jobs: 1
sync-rsync-extra-opts:
Binary Repositories:
gentoobinhost
priority: 1
sync-uri: https://gentoo.osuosl.org/releases/amd64/binpackages/23.0/x86-64
ACCEPT_KEYWORDS="amd64"
ACCEPT_LICENSE="*"
CBUILD="x86_64-pc-linux-gnu"
CFLAGS="-march=native -O2 -pipe"
CHOST="x86_64-pc-linux-gnu"
CONFIG_PROTECT="/etc /usr/lib64/libreoffice/program/sofficerc /usr/share/gnupg/qualified.txt"
CONFIG_PROTECT_MASK="/etc/ca-certificates.conf /etc/dconf /etc/env.d /etc/fonts/fonts.conf /etc/gconf /etc/gentoo-release /etc/revdep-rebuild /etc/sandbox.d /etc/terminfo"
CXXFLAGS="-march=native -O2 -pipe"
DISTDIR="/var/cache/distfiles"
ENV_UNSET="CARGO_HOME DBUS_SESSION_BUS_ADDRESS DISPLAY GDK_PIXBUF_MODULE_FILE GOBIN GOPATH PERL5LIB PERL5OPT PERLPREFIX PERL_CORE PERL_MB_OPT PERL_MM_OPT XAUTHORITY XDG_CACHE_HOME XDG_CONFIG_HOME XDG_DATA_HOME XDG_RUNTIME_DIR XDG_STATE_HOME"
FCFLAGS="-march=native -O2 -pipe"
FEATURES="assume-digests binpkg-docompress binpkg-dostrip binpkg-logs binpkg-multi-instance buildpkg-live config-protect-if-modified distlocks ebuild-locks fixlafiles ipc-sandbox merge-sync merge-wait multilib-strict network-sandbox news parallel-fetch pid-sandbox pkgdir-index-trusted preserve-libs protect-owned qa-unresolved-soname-deps sandbox sfperms strict unknown-features-warn unmerge-logs unmerge-orphans userfetch userpriv usersandbox usersync xattr"
FFLAGS="-march=native -O2 -pipe"
GENTOO_MIRRORS="ftp://ftp.uni-stuttgart.de/gentoo-distfiles/ rsync://mirror.rackspace.com/gentoo/"
LANG="en_US.utf8"
LDFLAGS="-Wl,-O1 -Wl,--as-needed -Wl,-z,pack-relative-relocs"
LEX="flex"
MAKEOPTS="-j12 -l12"
PKGDIR="/var/cache/binpkgs"
PORTAGE_CONFIGROOT="/"
PORTAGE_RSYNC_OPTS="--recursive --links --safe-links --perms --times --omit-dir-times --compress --force --whole-file --delete --stats --human-readable --timeout=180 --exclude=/distfiles --exclude=/local --exclude=/packages --exclude=/.git"
PORTAGE_TMPDIR="/var/tmp"
SHELL="/bin/bash"
USE="X a52 aac acl acpi alsa amd64 bluetooth branding bzip2 cairo cdda cdr cet crypt cups dbus dri dts dvd dvdr elogind encode exif flac gdbm gif gpm gtk gui iconv icu ipv6 jpeg kf6compat lcms libnotify libtirpc mad milter mng mp3 mp4 mpeg multilib ncurses nls ogg opengl openmp pam pango pcre pdf png policykit postproc ppds pulseaudio qml qt5 qt6 readline savedconfig sdl seccomp sound spell split-usr ssl startup-notification svg test-rust tiff truetype udev udisks unicode upower usb vorbis vulkan wayland wxwidgets x264 xattr xcb xft xinerama xml xv xvid zlib" ABI_X86="64" ADA_TARGET="gcc_12" APACHE2_MODULES="authn_core authz_core socache_shmcb unixd actions alias auth_basic authn_anon authn_dbm authn_file authz_dbm authz_groupfile authz_host authz_owner authz_user autoindex cache cgi cgid dav dav_fs dav_lock deflate dir env expires ext_filter file_cache filter headers include info log_config logio mime mime_magic negotiation rewrite setenvif speling status unique_id userdir usertrack vhost_alias" CALLIGRA_FEATURES="karbon sheets words" COLLECTD_PLUGINS="df interface irq load memory rrdtool swap syslog" CPU_FLAGS_X86="mmx mmxext sse sse2 aes avx avx2 avx512bw avx512cd avx512dq avx512f avx512vbmi avx512vl f16c fma3 pclmul popcnt rdrand sha sse3 sse4_1 sse4_2 ssse3" ELIBC="glibc" GPSD_PROTOCOLS="ashtech aivdm earthmate evermore fv18 garmin garmintxt gpsclock greis isync itrax mtk3301 ntrip navcom oceanserver oncore rtcm104v2 rtcm104v3 sirf skytraq superstar2 tsip tripmate tnt ublox" GRUB_PLATFORMS="efi-64" GUILE_SINGLE_TARGET="3-0" GUILE_TARGETS="3-0" INPUT_DEVICES="libinput synaptics" KERNEL="linux" LCD_DEVICES="bayrad cfontz glk hd44780 lb216 lcdm001 mtxorb text" LUA_SINGLE_TARGET="lua5-1" LUA_TARGETS="lua5-1" OFFICE_IMPLEMENTATION="libreoffice" PHP_TARGETS="php8-2" POSTGRES_TARGETS="postgres16" PYTHON_SINGLE_TARGET="python3_12" PYTHON_TARGETS="python3_12" RUBY_TARGETS="ruby31 ruby32" VIDEO_CARDS="nvidia intel" XTABLES_ADDONS="quota2 psd pknock lscan length2 ipv4options ipp2p iface geoip fuzzy condition tarpit sysrq proto logmark ipmark dhcpmac delude chaos account"
Unset: ADDR2LINE, AR, ARFLAGS, AS, ASFLAGS, CC, CCLD, CONFIG_SHELL, CPP, CPPFLAGS, CTARGET, CXX, CXXFILT, ELFEDIT, EMERGE_DEFAULT_OPTS, EXTRA_ECONF, F77FLAGS, FC, GCOV, GPROF, INSTALL_MASK, LC_ALL, LD, LFLAGS, LIBTOOL, LINGUAS, MAKE, MAKEFLAGS, NM, OBJCOPY, OBJDUMP, PORTAGE_BINHOST, PORTAGE_BUNZIP2_COMMAND, PORTAGE_COMPRESS, PORTAGE_COMPRESS_FLAGS, PORTAGE_RSYNC_EXTRA_OPTS, PYTHONPATH, RANLIB, READELF, RUSTFLAGS, SIZE, STRINGS, STRIP, YACC, YFLAGSTested using the following Kali configuration:
# uname -r
6.8.11-amd64
# cat /etc/os-release
PRETTY_NAME="Kali GNU/Linux Rolling"
NAME="Kali GNU/Linux"
VERSION_ID="2024.3"
VERSION="2024.3"
VERSION_CODENAME=kali-rolling
ID=kali
ID_LIKE=debian
HOME_URL="https://www.kali.org/"
SUPPORT_URL="https://forums.kali.org/"
BUG_REPORT_URL="https://bugs.kali.org/"
ANSI_COLOR="1;31"
Install the following packages:
apt install cmake libsqlite3-devPackage detail
# apt show cmake
Package: cmake
Version: 3.30.5-1
Priority: optional
Section: devel
Maintainer: Debian CMake Team <pkg-cmake-team@lists.alioth.debian.org>
Installed-Size: 40.2 MB
Depends: cmake-data (= 3.30.5-1), procps, libarchive13t64 (>= 3.3.3), libc6 (>= 2.38), libcurl4t64 (>= 7.16.2), libexpat1 (>= 2.0.1), libgcc-s1 (>= 3.0), libjsoncpp26 (>= 1.9.6), librhash1 (>= 1.2.6), libstdc++6 (>= 14), libuv1t64 (>= 1.38.0), zlib1g (>= 1:1.1.4)
Recommends: gcc, make
Suggests: cmake-doc, cmake-format, elpa-cmake-mode, ninja-build
Homepage: https://cmake.org/
Tag: devel::buildtools, implemented-in::c++, interface::commandline,
interface::text-mode, role::program, scope::utility,
uitoolkit::ncurses, works-with::software:source
Download-Size: 11.4 MB
APT-Manual-Installed: yes
APT-Sources: http://http.kali.org/kali kali-rolling/main amd64 Packages
Description: cross-platform, open-source make system
CMake is used to control the software compilation process using
simple platform and compiler independent configuration files. CMake
generates native makefiles and workspaces that can be used in the
compiler environment of your choice. CMake is quite sophisticated: it
is possible to support complex environments requiring system
configuration, pre-processor generation, code generation, and template
instantiation.
# apt show libsqlite3-dev
Package: libsqlite3-dev
Version: 3.46.1-1
Priority: optional
Section: libdevel
Source: sqlite3
Maintainer: Laszlo Boszormenyi (GCS) <gcs@debian.org>
Installed-Size: 3,469 kB
Depends: libsqlite3-0 (= 3.46.1-1), libc-dev
Suggests: sqlite3-doc
Homepage: https://www.sqlite.org/
Tag: devel::library, role::devel-lib
Download-Size: 1,107 kB
APT-Manual-Installed: yes
APT-Sources: http://http.kali.org/kali kali-rolling/main amd64 Packages
Description: SQLite 3 development files
SQLite is a C library that implements an SQL database engine.
Programs that link with the SQLite library can have SQL database
access without running a separate RDBMS process.
.
This package contains the development files (headers, static libraries)The source code can be downloaded from the repo using git:
git clone https://github.com/CTRLRLTY/JARY.gitThen switch to the 0.x branch:
cd JARY
git switch 0.xConfigure the cmake project into a build folder as a release build:
cmake -DCMAKE_BUILD_TYPE=Release -S . -B ./buildOther options that can effect the build process can be checked by using the -LH flag on the build directory:
cmake -LH ./build/Reconfigure the build directory to include other options. Finally compile the shared module and install it:
sudo cmake --build ./build --target=jary --target=mark
sudo cmake --install ./build
sudo ldconfigReaders are required to understand C to follow this section
Let's see a simple example on how to use the Library. First, setup the project directory:
mkdir example
cd exampleCreate a rule.jary rule file containing the following code:
import mark
// define the expected structure of the user event
ingress user {
field:
name string
activity string
}
rule count_root_fail_login {
match:
// Match only if the name of the user is root
$user.name exact "root"
// Match only if the activity of the user is "failed login"
$user.activity exact "failed login"
// only check for user event within the last 10 seconds
$user within 10s
action:
// increment failed_root counter by 1
mark.mark("failed_root")
}
rule auth_brute_force {
match:
// Match only if the activity of the user is "failed login"
$user.activity exact "failed login"
$user within 10s
condition:
// check if failed_<user> counter > 5
mark.count("failed_" .. $user.name) > 5
output: // The values here will be returned to the callback
"must've been the wind" // 0th index
action:
// reset the counter to 0
mark.unmark("failed_" .. $user.name)
}
The rule above essentially just created 2 rules named count_root_fail_login and auth_brute_force. The first rule will increment a counter by 1 whenever a user named root had a failed login activity. The second rule then will output the string "must've been the wind" if the counter for that failed user reached 5 or more and then reset the counter.
Rules are executed top to bottom
Next we'll need to create a program that'll feed the runtime with 10 user events.
#include <jary.h>
#include <stdio.h>
#include <string.h>
// This function will be called each time auth_brute_force rule gets triggered.
// PARAM1 data : Any value given as the 4th argument to jary_rule_clbk
// PARAM2 output: Contain values set by the output section in the rule
static int callback(void *data, const struct jyOutput *output)
{
// Every outputted value lifetime ends when this function ends.
// Do not refer outside of this function. Always copy.
const char *value;
// Get the first value of the output section as string
if (jary_output_str(output, 0, &value) != JARY_OK)
return JARY_INT_CRASH; // crash the runtime
// Copy the value into the msg variable
*(char **) data = strdup(value);
return JARY_OK;
}
int main(int argc, const char **argv)
{
const char *filepath = argv[1];
// will be allocated if there's a compile error. Must be deallocated
// using jary_free().
char *compile_errmsg;
// opaque pointer to the jary context
struct jary *jary;
if (jary_open(&jary) != JARY_OK)
goto PANIC;
switch (jary_compile_file(jary, filepath, &compile_errmsg)) {
case JARY_OK:
break;
case JARY_ERR_COMPILE:
goto COMPILE_FAIL;
default:
goto PANIC;
}
// create 10 user event
for (int i = 0; i < 10; ++i) {
// numeric handle to the created event
// used to reference the event
unsigned int event;
// queue a user event
if (jary_event(jary, "user", &event) != JARY_OK)
goto PANIC;
// set user.name = "root"
if (jary_field_str(jary, event, "name", "root") != JARY_OK)
goto PANIC;
// set user.activity = "failed login"
if (jary_field_str(jary, event, "activity", "failed login")
!= JARY_OK)
goto PANIC;
}
// This will contain the 1st value of the output section
char *msg = "nothing?";
// Attach a callback to auth_brute_force rule
if (jary_rule_clbk(jary, "auth_brute_force", callback, &msg) != JARY_OK)
goto PANIC;
// Execute all rules
if (jary_execute(jary) != JARY_OK)
goto PANIC;
printf("output: %s\n", msg);
goto FINISH;
PANIC:
fprintf(stderr, "%s\n", jary_errmsg(jary));
goto FINISH;
COMPILE_FAIL:
fprintf(stderr, "%s\n", compile_errmsg);
jary_free(compile_errmsg);
FINISH:
jary_close(jary);
return 0;
}Finally all we need to do is compile and run it:
gcc ./main.c -ljary -o example
./example ./rule.jaryIf you see the following strings printed on your terminal, then congrats! You just used Jary for the first time.
output: must've been the wind
Check out the following documentation to understand the previous example in detail:
- API reference page:
JARY/doc/c_api_reference.md - Rule reference:
JARY/doc/rule_reference.md