Skip to content

README.md

Latest commit

 

History

History
245 lines (185 loc) · 7.23 KB

README.md

File metadata and controls

245 lines (185 loc) · 7.23 KB
Raw

Razorback

The Razorback mascot

Razorback® is an open source framework for an intelligence driven security solution. malware & other malicious threats.

Installation Instructions

We recommend running Razorback on Ubuntu LTS.

Quick Install

Install with default options and configuration:

## If using a git checkout (not required from release tarball).
./autojunk.sh
./configure
make
make install

Long/Developer Install

Debugging can be enabled with:

./configure --enable-debug --enable-assert

For all avaliable options see:

./configure --help

Dependencies:

Ubuntu focal:

  • automake
  • automake
  • autoconf
  • libtool
  • pkg-config
  • uuid-dev
  • libcurl4-openssl-dev
  • libssl-dev
  • libconfig-dev
  • libssh-dev
  • libjson-c-dev
  • check - Unit testing framework (Required for testing, not runtime)
  • jv - JSON validator (Required for testing, not runtime) go install github.com/santhosh-tekuri/jsonschema/cmd/jv@latest

Library Initialization

Applications using the Razorback API must call RZB_Init_API() exactly once before calling any other Razorback API entry point. Razorback no longer performs this initialization automatically from a shared-library constructor or Windows DLL attach hook.

#include <razorback/api.h>

int main(void)
{
    RZB_Init_API();
    /* ... */
}

Tooling

The API build now installs two helper binaries for nugget development and operation.

rzb-worker loads a single nugget module through the existing initNug() / shutdownNug() interface and keeps it running with the normal Razorback runtime:

src/rzb-worker --debug --health-port=8080 /path/to/nugget.so

rzb-dev also loads a nugget through initNug() / shutdownNug(), but it enables an internal local-only dev mode first so the created context does not require broker connections or other external Razorback services. It runs one file through the nugget's inspection hook and prints the resulting judgments and submissions:

src/rzb-dev --type=image/svg+xml /path/to/nugget.so /path/to/input.file

If --type is omitted, rzb-dev will infer the datatype only when the nugget registers exactly one inspection datatype.

Health Checks

Razorback provides a small process-wide health subsystem for library consumers that need Kubernetes-style probes.

The HTTP listener is opt-in. After calling RZB_Init_API(), start it explicitly and mark startup complete when your application finishes its own initialization:

#include <razorback/api.h>
#include <razorback/health.h>

int main(void)
{
    RazorbackHealthServerConfig_t health = {
        .bindAddress = "127.0.0.1",
        .port = 8080,
        .requireContextsForReady = true,
    };

    RZB_Init_API();
    Razorback_Health_Start(&health);
    Razorback_Health_SetStartupComplete(true);
}

Supported endpoints:

  • /livez
  • /readyz
  • /startupz
  • /healthz

The three probe endpoints return 200 when healthy and 503 when unhealthy. /healthz returns a small JSON summary of the built-in liveness, readiness, and startup states. Consumers may also extend any of those checks with Razorback_Health_RegisterCheck().

Telemetry

Razorback is instrumented with OpenTelemetry and requires opentelemetry-cpp with OTLP HTTP exporter support at build time. When the application calls RZB_Init_API(), Razorback initializes telemetry and creates spans for:

  • queue sends
  • queue receives
  • message processing

Trace context is propagated across Razorback message headers using W3C Trace Context (traceparent / tracestate). The current implementation exports traces only; metrics and logs are not configured by this library.

Telemetry Environment Variables

Razorback-specific behavior:

  • OTEL_SDK_DISABLED Disables telemetry initialization. If this is set to true, 1, or yes, Razorback leaves tracing disabled.
  • OTEL_SERVICE_NAME Overrides the exported service.name resource attribute. If unset, Razorback uses razorback-api.

Standard OTLP HTTP trace exporter configuration:

This build always instantiates the OTLP HTTP trace exporter. Use OTLP/HTTP configuration variables; there is no Razorback-side switch to OTLP/gRPC.

  • OTEL_EXPORTER_OTLP_ENDPOINT Base OTLP endpoint. For OTLP/HTTP, the exporter derives the trace URL from this base endpoint.
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT Trace-specific OTLP endpoint. Use this when traces should be sent to a different URL than other signals.
  • OTEL_EXPORTER_OTLP_HEADERS Comma-separated HTTP headers applied to all OTLP requests.
  • OTEL_EXPORTER_OTLP_TRACES_HEADERS Comma-separated HTTP headers applied only to trace exports.
  • OTEL_EXPORTER_OTLP_TIMEOUT Export timeout, in milliseconds, for OTLP requests.
  • OTEL_EXPORTER_OTLP_TRACES_TIMEOUT Export timeout, in milliseconds, for trace exports.
  • OTEL_EXPORTER_OTLP_COMPRESSION OTLP request compression setting.
  • OTEL_EXPORTER_OTLP_TRACES_COMPRESSION Trace-specific OTLP request compression setting.
  • OTEL_EXPORTER_OTLP_CERTIFICATE Path to the CA certificate file used to validate the OTLP server.
  • OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE Trace-specific CA certificate path.
  • OTEL_EXPORTER_OTLP_CLIENT_KEY Path to the client private key for mTLS.
  • OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY Trace-specific client private key path.
  • OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE Path to the client certificate or certificate chain for mTLS.
  • OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE Trace-specific client certificate path.

Batch span processor tuning:

  • OTEL_BSP_MAX_QUEUE_SIZE Maximum number of spans buffered before new spans are dropped.
  • OTEL_BSP_SCHEDULE_DELAY Delay, in milliseconds, between export attempts.
  • OTEL_BSP_EXPORT_TIMEOUT Export timeout, in milliseconds, used by the batch span processor.
  • OTEL_BSP_MAX_EXPORT_BATCH_SIZE Maximum number of spans sent in a single export batch.

The exporter is created with the default opentelemetry-cpp OTLP HTTP options, so the standard OpenTelemetry trace exporter environment variables supported by that SDK are used directly.

Linking to the Razorback API

PKG-CONFIG: The install target installs a package metadata file in ${libdir}/pkgconfig (/usr/local/lib/pkkconfig by default). The pkg-config utility can be used to acquire the correct CFLAGS and LDFLAGS needed to compile a nugget.

pkg-config --cflags razorback pkg-config --libs razorback

The PKG_CHECK_MODULES macro can be used to acquire the CFLAGS and LDFLAGS from within a nugget configure script.

PKG_CHECK_MODULES([RZB], [razorback])

The above call will provide RZB_CFLAGS and RZB_LDFLAGS to use in the autoconf/automake process.

Want to make a contribution?

The Razorback development team welcomes code contributions, improvements to our documentation, and also bug reports.

Thanks for joining us!

Licensing

Razorback is licensed for public/open source use under the GNU General Public License, Version 2 (GPLv2).

See LICENSE for a copy of the license.