From a86c5f7cae7ec9a3398300555a0b644689d946a1 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 19 Sep 2024 06:14:53 +0200 Subject: Merging upstream version 4.4.0. Signed-off-by: Daniel Baumann --- doc/logray-quick-start.adoc | 70 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 doc/logray-quick-start.adoc (limited to 'doc/logray-quick-start.adoc') diff --git a/doc/logray-quick-start.adoc b/doc/logray-quick-start.adoc new file mode 100644 index 00000000..d9007c37 --- /dev/null +++ b/doc/logray-quick-start.adoc @@ -0,0 +1,70 @@ += Logray Quick Start + +Logray is a sibling application for Wireshark which focuses on system calls and log messages. +It helps people understand, troubleshoot, and secure their systems via system calls and log messages similar to the way Wireshark helps people understand, troubleshoot, and secure their networks via packets. + +This document provides brief instructions for obtaining, using, and building Logray until more complete documentation comparable to the Wireshark Developer’s and User’s Guides can be written. + +== Getting Logray + +You can get Windows and macOS development packages from https://www.wireshark.org/download/automated/. +Native system call captures aren't yet supported on those platforms, but they do come with the https://github.com/falcosecurity/plugins/blob/main/plugins/cloudtrail/README.md[CloudTrail plugin], which can pull AWS CloudTrail logs from an S3 bucket or SQS/SNS. + +If you wish to use Logray on Linux you will have to built it yourself. +Instructions for doing that can be found in the <> section below. + +== Using Logray + +Logray shares a great deal of code with Wireshark, including most of its UI elements. +If you are familiar with Wireshark, its interface and workflows should be familiar. + +One issue that you might run into initially is that system calls and logs deal with different information. +As a result, the event list column preferences need to be configured to match the kind of data that you are analyzing. +Logray's default configuration profile assumes that you are analyzing system calls. +It ships with a "Cloudtrail" configuration profile which is geared toward CloudTrail events. +You can find more information on working with configuration profiles in the https://www.wireshark.org/docs/wsug_html_chunked/ChCustConfigProfilesSection.html[Configuration Profiles] section in the Wireshark User's Guide. +If you switch back and forth between system call and CloudTrail captures on a regular basis, you might find the "Automatic Profile Switching" feature useful. + +You can obtain system call captures using the https://github.com/draios/sysdig[sysdig command line tool] or by using Logray on a Linux system. + +The https://gitlab.com/wireshark/wireshark/-/blob/master/doc/falcodump.adoc[falcodump manpage] provides information how to use Falco Plugin extcap interface. + +== Building Logray[[building_logray]] + +Logray requires the same build environment as Wireshark. +See the https://www.wireshark.org/docs/wsdg_html_chunked/[Wireshark Developer’s Guide] for instructions on setting that up. + +It additionally requires libsinsp and libscap from https://github.com/falcosecurity/libs/[falcosecurity/libs] and any desired plugins from https://github.com/falcosecurity/plugins/[falcosecurity/plugins]. + +In order to build Logray, do the following: + +1. https://falco.org/docs/getting-started/source/[Build falcosecurity/libs]. + +2. Build any desired https://github.com/falcosecurity/plugins/[Falco plugins] and copy them somewhere, such as `/usr/local/lib/falcosecurity/plugins`. + +3. Build the Wireshark sources with the following CMake options: ++ +-- +[horizontal] +BUILD_logray:: Must be enabled, e.g. set to ON +BUILD_falcodump:: Must be enabled, e.g. set to ON +CMAKE_PREFIX_PATH:: If you installed libsinsp and libscap to a non-standard directory, https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html[this should point there]. +FALCO_PLUGINS:: Semicolon-separated paths to individual Falco plugins, e.g. `/path/to/libcloudtrail.so`. +-- + +.Example 1: Building on Linux using Make +[sh] +---- +# This assumes that falcosecurity-libs and the CloudTral plugin were installed in +# `/opt/falco-libs/0.17.1`. +cmake \ + -DBUILD_logray=ON \ + -DBUILD_falcodump=ON \ + -DCMAKE_PREFIX_PATH=/opt/falco-libs/0.17.1 \ + -DFALCO_PLUGINS=/opt/falco-libs/0.17.1/lib/falcosecurity/plugins/libcloudtrail.so \ + .. +make -j $(getconf _NPROCESSORS_ONLN) +---- + + +If you want to add other Falco plugins later you can copy them to a `falco` subfolder in the Global Plugins folder. The path to the Global Plugins folder is shown in the About Logray Folders dialog. -- cgit v1.2.3