9 releases (5 breaking)

new 0.6.0 Jun 15, 2021
0.5.0 May 10, 2021
0.4.0 Apr 12, 2021
0.3.0 Apr 9, 2021
0.1.1-rc.2 Jan 25, 2021

#706 in Network programming

42 downloads per month

Custom license

22KB
324 lines

Security Aware Wire Protocol parsing library.

This library contains parsers for various wire protocols, and is intended to be used in network security sensors.

Each parser exposes a common interface that allows the sensor engine to feed bytes into the parser and receive parsed metadata back. The bytes are expected to be at the session layer, so the engine is responsible for assembling transport layer data into a session payload, which is then fed into this library.

This library aims to be resilient and parse as many messages as possible that are seen in the wild. If a message is invalid or out-of-spec, it should not be discarded by the parser. Parsers will set flags on the message when it fails validation instead of returning an error.

The interface to each parser is uniform and simple, consisting of only a few functions to:

  • test that a payload is or is not the protocol in question (eg. is this modbus?)
  • provide more bytes to the parser
  • set callbacks to invoke on per-protocol metadata events (todo)
  • indicate that some bytes are unavailable (ie. notify of packet loss) (todo)
  • indicate a session has ended (todo)

The library exposes Rust and C bindings for easy integration into existing and future network security sensor platforms. (todo)

Usage

Start using SAWP by including a parser in your project's Cargo.toml dependencies. The base library will also be required for using common types.

The minimum supported version of rustc is 1.41.1.

Example

[dependencies]
sawp-modbus = "0.6.0"
sawp = "0.6.0"

FFI Support

Some parsers have a foreign function interface for use in C/C++ projects. FFI Support can be enabled by building with the ffi feature.

A Makefile is also provided to ease the build process. Please refer to this file for more in-depth documentation.

# Install cbindgen which is required to generate headers
cargo install --force cbindgen

# Build headers and shared objects
make

Contributing

This project is actively maintained and accepting open source contributions. See CONTRIBUTING for more details.

Dependencies

~1.7–2.5MB
~52K SLoC