{"id":19579741,"url":"https://github.com/wolfssl/wolfsentry","last_synced_at":"2025-04-27T08:31:53.229Z","repository":{"id":39621480,"uuid":"359942102","full_name":"wolfSSL/wolfsentry","owner":"wolfSSL","description":"wolfSSL Intrusion Detection and Prevention System (IDPS)","archived":false,"fork":false,"pushed_at":"2025-02-21T21:02:40.000Z","size":11552,"stargazers_count":33,"open_issues_count":1,"forks_count":16,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-04T23:11:12.589Z","etag":null,"topics":["anti-bot","attack-prevention","ban-hosts","c-library","embedded","embedded-systems","firewall","firewall-configuration","firewall-rules","idps","ids","intrusion-detection","intrusion-detection-system","iot","iot-security","monitoring","security","security-tools","wolfssl"],"latest_commit_sha":null,"homepage":"https://www.wolfssl.com/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfSSL.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-20T20:24:46.000Z","updated_at":"2025-03-12T07:03:11.000Z","dependencies_parsed_at":"2023-09-29T02:32:38.548Z","dependency_job_id":"5b868dcd-f309-46bd-8adb-9319855eb3f8","html_url":"https://github.com/wolfSSL/wolfsentry","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfsentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfsentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfsentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfsentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfSSL","download_url":"https://codeload.github.com/wolfSSL/wolfsentry/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251112529,"owners_count":21538162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anti-bot","attack-prevention","ban-hosts","c-library","embedded","embedded-systems","firewall","firewall-configuration","firewall-rules","idps","ids","intrusion-detection","intrusion-detection-system","iot","iot-security","monitoring","security","security-tools","wolfssl"],"created_at":"2024-11-11T07:18:50.782Z","updated_at":"2025-04-27T08:31:48.421Z","avatar_url":"https://github.com/wolfSSL.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wolfSentry -- The Wolfssl Embedded Firewall/IDPS\n\n## Description\n\nwolfSentry is the wolfSSL embedded IDPS (Intrusion Detection and Prevention\nSystem).  In simple terms, wolfSentry is an embedded firewall engine (both\nstatic and fully dynamic), with prefix-based and wildcard-capable lookup of\nknown hosts/netblocks qualified by interface, address family, protocol, port,\nand other traffic parameters.  Additionally, wolfSentry can be used as a\ndynamically configurable logic hub, arbitrarily associating user-defined events\nwith user-defined actions, contextualized by connection attributes.  The\nevolution of client-server relationships can thus be tracked in detail, freely\npassing traffic matching expected usage patterns, while efficiently rejecting\nabusive traffic.\n\nwolfSentry is fully integrated with the lwIP stack, through a patchset in the\n`lwip/` subdirectory of the source tree, and has basic integration with the\nwolfSSL library for application-level filtering of inbound and outbound\nconnections.\n\nThe wolfSentry engine is dynamically configurable programmatically through an\nAPI, or from a textual input file in JSON supplied to the engine, or dynamically\nand incrementally with JSON fragments, or any combination of these methods.\nReconfiguration is protected by transactional semantics, and advanced internal\nlocks on threaded targets assure seamless service availability with atomic\npolicy transition.  Callbacks allow for transport-agnostic remote logging,\ne.g. through MQTT, syslog, or DDS message buses.\n\nwolfSentry is designed from the ground up to function well in\nresource-constrained, bare-metal, and realtime environments, with algorithms to\nstay within designated maximum memory footprints and maintain deterministic\nthroughput.  This allows full firewall and IDPS functionality on embedded\ntargets such as FreeRTOS, Nucleus, NUTTX, Zephyr, VxWorks, and Green Hills\nIntegrity, and on ARM and other common embedded CPUs and MCUs.  wolfSentry with\ndynamic firewalling can add as little as 64k to the code footprint, and 32k to\nthe volatile state footprint, and can fully leverage the existing logic and\nstate of applications and sibling libraries.\n\n\n## Documentation\n\nBasic application integration on FreeRTOS-lwIP is documented, with usable code fragments, in [doc/freertos-lwip-app.md](doc/freertos-lwip-app.md).\n\nJSON configuration is documented in detail by [doc/json_configuration.md](doc/json_configuration.md).\n\nWith `doxygen` installed, the HTML version of the full API reference manual can\nbe generated from the top of the wolfSentry source tree with `make doc-html`.\nThis, and the source code itself, are the recommended API references.\n\nThe PDF version of the API reference manual is pregenerated and included with source\ndistributions in the `doc/` subdirectory at `doc/wolfSentry_refman.pdf`.  The latest version is always\navailable [on GitHub](https://raw.githubusercontent.com/wolfSSL/wolfsentry/master/doc/wolfSentry_refman.pdf).\n\nThe latest changes and additions are noted in the [ChangeLog.md](ChangeLog.md) at the top of the repository.\n\n\n## Dependencies\n\nIn its default build, wolfSentry depends on a POSIX runtime, specifically the\nheap allocator, clock_gettime, stdio, semaphore, pthreads, and string APIs.\nHowever, these dependencies can be avoided with various build-time options.  The recipe\n\n`make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS=\"-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN\"`\n\nbuilds a libwolfsentry.a that depends on only a handful of basic string\nfunctions and the `inet_ntop()` library function (from POSIX.1-2001, and also\nimplemented by lwIP).  Allocator and time callbacks must then be set in a\n`struct wolfsentry_host_platform_interface` supplied to `wolfsentry_init()`.\n\nThe wolfSentry `Makefile` depends on a modern (v4.0+) Gnu `make`.  The library\nitself can be built outside `make`, within another project/framework, by\ncreating a user settings macro file and passing its path to the compiler with\nthe `WOLFSENTRY_USER_SETTINGS_FILE` macro.\n\n\n## Building\n\nwolfSentry was written with portability in mind, with provisions for non-POSIX\nand C89 targets.  For example, all its dependencies can be met with the\nFreeRTOS/newlib-nano/lwIP runtime.  If you have difficulty building wolfSentry,\nplease don’t hesitate to seek support through our [support\nforums](\u003chttps://www.wolfssl.com/forums\u003e) or contact us directly at\n[support@wolfssl.com](mailto:support@wolfssl.com).\n\nThe current wolfSentry release can be downloaded from [the wolfSSL\nwebsite as a ZIP file](https://www.wolfssl.com/download), and developers can\n[browse the release history](https://github.com/wolfSSL/wolfsentry/tags) and\nclone [the wolfSentry Git repository](https://github.com/wolfSSL/wolfsentry) for\nthe latest pre-release updates.\n\nThere are several flags that can be passed to `make` to control the build\nparameters.  `make` will store them at build time in\n`wolfsentry/wolfsentry_options.h` in the build tree. If you are not\nusing `make`, then the C macro `WOLFSENTRY_USER_SETTINGS_FILE` should be\ndefined to the path to a file containing settings, both when building wolfSentry\nand when building the application.\n\nThe following feature control variables are recognized.  True/false features\n(`LWIP`, `NO_STDIO`, `NO_JSON`, etc.) are undefined by default, and activated\nwhen defined.  Macros can be supplied using the `EXTRA_CFLAGS` option, or by\nplacing them in a `USER_SETTINGS_FILE`.  More detailed documentation for macros\nis available in the reference manual \"Startup/Configuration/Shutdown Subsystem\"\ntopic.\n\n| `make` Option | Macro Option | Description |\n| -------------- | ------------ | ----------- |\n| `SHELL` | | Supplies an explicit/alternative path to `bash`. |\n| `AWK` | | Supplies an explicit/alternative path to Gnu `awk`. |\n| `V` | | Verbose `make` output \u003cbr\u003e e.g. `make V=1 -j test` |\n| `USER_MAKE_CONF` | | User-defined make clauses to include at the top of the main Makefile \u003cbr\u003e e.g. `make -j USER_MAKE_CONF=Makefile.settings` |\n| `EXTRA_CFLAGS` | | Additional arguments to be passed verbatim to the compiler |\n| `EXTRA_LDFLAGS` | | Additional arguments to be passed verbatim to the linker |\n| `SRC_TOP` | | The source code top level directory (default `pwd -P`) |\n| `BUILD_TOP` | | Build with artifacts in an alternate location (outside or in a subdirectory of the source tree) \u003cbr\u003e e.g. `make BUILD_TOP=./build -j test`|\n| `DEBUG` | | Compiler debugging flag to use (default `-ggdb`) |\n| `OPTIM` | | The optimizer flag to use (default `-O3`) |\n| `HOST` | | The target host tuple, for cross-compilation (default unset, i.e. native targeting) |\n| `RUNTIME` | | The target runtime ecosystem -- default unset, `FreeRTOS-lwIP` and `Linux-lwIP` are recognized |\n| `C_WARNFLAGS` | | The warning flags to use (overriding the generally applicable defaults) |\n| `STATIC` | | Build statically linked unit tests |\n| `STRIPPED` | | Strip binaries of debugging symbols |\n| `FUNCTION_SECTIONS` | | Cull any unused object code (with function granularity) to minimize total size. |\n| `BUILD_DYNAMIC` | | Build dynamically linked library |\n| `VERY_QUIET` | | Inhibit all non-error output during build |\n| `TAR` | | Path to GNU tar binary for `make dist`, should be set to `gtar` for macOS |\n| `VERSION` | | The version to package for `make dist` |\n| `LWIP` | `WOLFSENTRY_LWIP` | True/false -- Activates appropriate build settings for lwIP |\n| `NO_STDIO_STREAMS` | `WOLFSENTRY_NO_STDIO_STREAMS` | Define to omit functionality that depends on `stdio` stream I/O |\n| | `WOLFSENTRY_NO_STDIO_H` | Define to inhibit inclusion of `stdio.h` |\n| `NO_ADDR_BITMASK_MATCHING` | `WOLFSENTRY_NO_ADDR_BITMASK_MATCHING` | Define to omit support for bitmask matching of addresses, i.e. support only prefix matching. |\n| `NO_IPV6` | `WOLFSENTRY_NO_IPV6` | Define to omit support for the IPv6 address family. |\n| `NO_JSON` | `WOLFSENTRY_NO_JSON` | Define to omit JSON configuration support |\n| `NO_JSON_DOM` | `WOLFSENTRY_NO_JSON_DOM` | Define to omit JSON DOM API |\n| `CALL_TRACE` | `WOLFSENTRY_DEBUG_CALL_TRACE` | Define to activate runtime call stack logging (profusely verbose) |\n| `USER_SETTINGS_FILE` | `WOLFSENTRY_USER_SETTINGS_FILE` | A substitute settings file, replacing autogenerated `wolfsentry_settings.h` |\n| `SINGLETHREADED` | `WOLFSENTRY_SINGLETHREADED` | Define to omit thread safety logic, and replace thread safety functions and macros with no-op macros. |\n| | `WOLFSENTRY_NO_PROTOCOL_NAMES` | If defined, omit APIs for rendering error codes and source code files in human readable form. They will be rendered numerically. |\n| | `WOLFSENTRY_NO_GETPROTOBY` | Define to disable lookup and rendering of protocols and services by name. |\n| | `WOLFSENTRY_NO_ERROR_STRINGS` | If defined, omit APIs for rendering error codes and source code files in human readable form. They will be rendered numerically. |\n| | `WOLFSENTRY_NO_MALLOC_BUILTINS` | If defined, omit built-in heap allocator primitives; the `wolfsentry_host_platform_interface` supplied to wolfSentry APIs must include implementations of all functions in `struct wolfsentry_allocator`. |\n| | `WOLFSENTRY_HAVE_NONGNU_ATOMICS` | Define if gnu-style atomic intrinsics are not available. `WOLFSENTRY_ATOMIC_*()` macro definitions for intrinsics will need to be supplied in `WOLFSENTRY_USER_SETTINGS_FILE` (see `wolfsentry_util.h`). |\n| | `WOLFSENTRY_NO_CLOCK_BUILTIN` | If defined, omit built-in time primitives; the `wolfsentry_host_platform_interface` supplied to wolfSentry APIs must include implementations of all functions in `struct wolfsentry_timecbs`. |\n| | `WOLFSENTRY_NO_SEM_BUILTIN` | If defined, omit built-in semaphore primitives; the `wolfsentry_host_platform_interface` supplied to wolfSentry APIs must include implementations of all functions in `struct wolfsentry_semcbs`. |\n| | `WOLFSENTRY_USE_NONPOSIX_SEMAPHORES` | Define if POSIX semaphore API is not available. If no non-POSIX builtin implementation is present in `wolfsentry_util.c`, then #WOLFSENTRY_NO_SEM_BUILTIN must be set, and the `wolfsentry_host_platform_interface` supplied to wolfSentry APIs must include a full semaphore implementation (shim set) in its `wolfsentry_semcbs` slot. |\n| | `WOLFSENTRY_SEMAPHORE_INCLUDE` | Define to the path of a header file declaring a semaphore API. |\n| | `WOLFSENTRY_USE_NONPOSIX_THREADS` | Define if POSIX thread API is not available. `WOLFSENTRY_THREAD_INCLUDE`, `WOLFSENTRY_THREAD_ID_T`, and `WOLFSENTRY_THREAD_GET_ID_HANDLER` will need to be defined. |\n| | `WOLFSENTRY_THREAD_INCLUDE` | Define to the path of a header file declaring a threading API. |\n| | `WOLFSENTRY_THREAD_ID_T` | Define to the appropriate type analogous to POSIX `pthread_t`. |\n| | `WOLFSENTRY_THREAD_GET_ID_HANDLER` | Define to the name of a void function analogous to POSIX `pthread_self`, returning a value of type `WOLFSENTRY_THREAD_ID_T`. |\n| | `FREERTOS` | Build for FreeRTOS |\n\n### Build and Self-Test Examples\n\nBuilding and testing libwolfsentry.a on Linux:\n\n`make -j test`\n\nBuild verbosely:\n\n`make V=1 -j test`\n\nBuild with artifacts in an alternate location (outside or in a subdirectory of the source tree):\n\n`make BUILD_TOP=./build -j test`\n\nInstall from an alternate build location to a non-standard destination:\n\n`make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install`\n\nBuild libwolfsentry.a and test it in various configurations:\n\n`make -j check`\n\nBuild and test libwolfsentry.a without support for multithreading:\n\n`make -j SINGLETHREADED=1 test`\n\nOther available make flags are `STATIC=1`, `STRIPPED=1`, `NO_JSON=1`, and\n`NO_JSON_DOM=1`, and the defaults values for `DEBUG`, `OPTIM`, and `C_WARNFLAGS`\ncan also be usefully overridden.\n\nBuild with a user-supplied makefile preamble to override defaults:\n\n`make -j USER_MAKE_CONF=Makefile.settings`\n\n(`Makefile.settings` can contain simple settings like `OPTIM := -Os`, or\nelaborate makefile code including additional rules and dependency mechanisms.)\n\nBuild the smallest simplest possible library:\n\n`make -j SINGLETHREADED=1 NO_STDIO=1 DEBUG= OPTIM=-Os EXTRA_CFLAGS=\"-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN -DWOLFSENTRY_NO_ERROR_STRINGS -Wno-error=inline -Wno-inline\"`\n\nBuild and test with user settings:\n\n`make -j USER_SETTINGS_FILE=user_settings.h test`\n\nBuild for FreeRTOS on ARM32, assuming FreeRTOS and lwIP source trees are located as shown:\n\n`make -j HOST=arm-none-eabi RUNTIME=FreeRTOS-lwIP FREERTOS_TOP=../third/FreeRTOSv202212.00 LWIP_TOP=../third/lwip EXTRA_CFLAGS=-mcpu=cortex-m7`\n\n\n## Project Examples\n\nIn the `wolfsentry/examples/` subdirectory are a set of example ports and\napplications, including a demo pop-up notification system implementing a toy\nTLS-enabled embedded web server, integrating with the Linux D-Bus facility.\n\nMore comprehensive examples of API usage are in\n`tests/unittests.c`, particularly `test_static_routes()`, `test_dynamic_rules()`,\nand `test_json()`, and the JSON configuration files at `tests/test-config*.json`.\n\nIn [the wolfSSL repository](https://github.com/wolfSSL/wolfssl), see code in\n`wolfssl/test.h` gated on `WOLFSSL_WOLFSENTRY_HOOKS`, including\n`wolfsentry_store_endpoints()`, `wolfSentry_NetworkFilterCallback()`,\n`wolfsentry_setup()`, and `tcp_connect_with_wolfSentry()`.  See also code in\n`examples/server/server.c` and `examples/client/client.c` gated on\n`WOLFSSL_WOLFSENTRY_HOOKS`.  Configure wolfssl with `--enable-wolfsentry` to\nbuild with wolfSentry integration, and use `--with-wolfsentry=/the/install/path`\nif wolfSentry is installed in a nonstandard location.  The wolfSSL test\nclient/server can be loaded with user-supplied wolfSentry JSON configurations\nfrom the command line, using `--wolfsentry-config \u003cfile\u003e`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfssl%2Fwolfsentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfssl%2Fwolfsentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfssl%2Fwolfsentry/lists"}