Skip to content

Commit 8db1394

Browse files
robfromboulderrobfromboulder
committed
Update README
1 parent 6b85125 commit 8db1394

File tree

1 file changed

+54
-86
lines changed

1 file changed

+54
-86
lines changed

‎README.md‎

Lines changed: 54 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,95 @@
11
# logger-ebpf
2-
Easily log **encrypted** API requests and responses to your own <a href="https://resurface.io">security data lake</a>.
2+
Easily log **encrypted** API calls to your own <a href="https://graylog.org/products/api-security/">security data lake</a>.
3+
4+
This open-source [eBPF](https://ebpf.io/) agent logs API requests and responses to [Graylog API Security](https://graylog.org/products/api-security/)
5+
for analysis and storage. This agent logs encrypted API calls without configuring any encryption keys or making any changes to client or server applications.
36

47
[![CodeFactor](https://www.codefactor.io/repository/github/resurfaceio/logger-ebpf/badge?s=1edfaf41d674519709d3abb9c1836e84b4c3a20f)](https://www.codefactor.io/repository/github/resurfaceio/logger-ebpf)
5-
[![License](https://img.shields.io/github/license/resurfaceio/logger-ebpf?s=1edfaf41d674519709d3abb9c1836e84b4c3a20f)](https://github.com/resurfaceio/logger-ebpf/blob/master/LICENSE)
68
[![Contributing](https://img.shields.io/badge/contributions-welcome-green.svg)](https://github.com/resurfaceio/logger-ebpf/blob/master/CONTRIBUTING.md)
9+
[![License](https://img.shields.io/github/license/resurfaceio/logger-ebpf?s=1edfaf41d674519709d3abb9c1836e84b4c3a20f)](https://github.com/resurfaceio/logger-ebpf/blob/master/LICENSE)
710

11+
⚠️ [Graylog API Security](https://graylog.org/products/api-security/) is licensed and installed separately, and runs as a remote service (on Kubernetes) that receives data from this eBPF agent.
812

913
## Contents
1014

1115
<ul>
12-
<li><a href="#dependencies">Dependencies</a></li>
13-
<li><a href="#usage">Usage</a></li>
14-
<li><a href="#logging-from-container">Capturing traffic from a containerized application</a></li>
15-
<li><a href="#build-from-source">Building from source</a></li>
16+
<li><a href="#system-requirements">System Requirements</a></li>
17+
<li><a href="#current-limitations">Current Limitations</a></li>
18+
<li><a href="#environment-variables">Environment Variables</a></li>
19+
<li><a href="#logging-from-linux-vm-or-physical-machine">Logging from Linux VM or Physical Machine</a></li>
20+
<li><a href="#logging-from-docker-container">Logging from Docker Container</a></li>
21+
<li><a href="#logging-from-kubernetes">Logging from Kubernetes</a></li>
1622
<li><a href="#privacy">Protecting User Privacy</a></li>
1723
</ul>
1824

25+
<a name="system-requirements"></a>
1926

20-
<a name="dependencies"></a>
21-
22-
## Dependencies
23-
24-
Requires Linux kernel v5.8+ and OpenSSL v1.0+
25-
26-
<a name="usage"></a>
27+
## System Requirements
2728

28-
## Usage
29-
30-
- Get the apropriate binary for your CPU arch from our [releases](https://github.com/resurfaceio/logger-ebpf/releases).
31-
32-
- Set the [variables](#environment-variables) used by the logger, according to your use case.
33-
34-
- Run binary as a privileged user
35-
36-
```sh
37-
sudo ./ebpf-logger
38-
```
29+
* 64-bit Intel or AMD CPU
30+
* Linux kernel v5.8 or higher
31+
* OpenSSL v1.0 or higher
32+
* Root privileges to run the eBPF agent binary
33+
* Network access to the Kubernetes cluster where [Graylog API Security](https://graylog.org/products/api-security/) is running
3934

40-
## Environment variables
35+
<a name="current-limitations"></a>
4136

42-
This plugin has access to five environment variables, but only two of them are required for the logger to work properly.
37+
## Current Limitations
4338

44-
#### ✔ All API calls are sent to the database running inside the `resurface` container
45-
The environment variable `USAGE_LOGGERS_URL` stores this address, which by default should be the string `"http://localhost:7701/message"`
46-
#### ✔ TLS traffic is captured directly from OpenSSL
47-
Encrypted traffic is captured by adding uprobes to symbols found in the OpenSSL shared library. The environment variable `USAGE_LOGGERS_EBPF_EXPATH` specifies the path to this file. This can be found by running the following command:
39+
* ARM64 chipsets are not yet supported
40+
* API calls made via HTTP are not logged yet (only HTTPS)
41+
* Only applications using OpenSSL are supported (additional encryption libraries coming soon)
42+
* HTTP v3, UDP, and streaming protocols are not supported
4843

49-
```sh
50-
ldconfig -p | grep ssl
51-
```
52-
#### ✔ All API calls are filtered using a set of rules (Optional)
53-
The environment variable `USAGE_LOGGERS_RULES` stores these [logging rules](#protecting-user-privacy) as a string. Even though this variable is optional, it is recommended to set it to `"include debug"` or `"allow_http_url"` when trying the plugin for the first time.
54-
#### ✔ The Logger can capture calls in client mode (Optional)
55-
You can set the environment variable `USAGE_LOGGERS_EBPF_ROLE` to `"client"` for the logger to capture API calls made from a client application (e.g. cURL).
56-
#### ✔ The Logger can be disabled at any time (Optional)
57-
By setting the environment variable `USAGE_LOGGERS_DISABLE` to `true` the logger will be disabled and no API calls will be logged.
44+
<a name="environment-variables"></a>
5845

46+
## Environment Variables
5947

60-
<a name="logging-from-container"></a>
48+
These environment variables are used to configure this eBPF agent and to control what information is logged.
6149

62-
## Capturing traffic from a containerized application
50+
| Variable Name | Default | Description |
51+
|---------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
52+
| USAGE_LOGGERS_DISABLE | false | When `true`, the eBPF agent is loaded but no calls are logged |
53+
| USAGE_LOGGERS_EBPF_EXPATH | (none) | Path to OpenSSL shared library<br>Use `ldconfig -p \| grep ssl` to find |
54+
| USAGE_LOGGERS_EBPF_ROLE | (none) | Use `server` for inbound calls, `client` for outbound calls |
55+
| USAGE_LOGGERS_RULES | (none) | [Logging rules](https://go2docs.graylog.org/apisecurity-current/logging_rules/logging_rules.htm) used to mask or remove specific details<br>Use `import debug` to log entire request and response |
56+
| USAGE_LOGGERS_URL | (none) | [Capture URL](https://go2docs.graylog.org/apisecurity-current/capture_api_calls/capture_api_calls.htm) for Graylog API Security instance<br>Looks like `https://GL_APISECURITY_HOST/fluke/message` |
6357

64-
### Logging from a running container
58+
<a name="logging-from-linux-vm-or-physical-machine"></a>
6559

66-
- Copy the binary to the container
67-
```sh
68-
docker cp ebpf-logger mycontainer:/
69-
```
60+
## Logging from Linux VM or Physical Machine
7061

71-
- Exec into the container
72-
```sh
73-
docker exec -it -u root mycontainer sh
62+
Download agent binary:
63+
```bash
64+
wget https://github.com/resurfaceio/logger-ebpf/releases/download/v1.1.0/ebpf-logger-amd64 && chmod +x ebpf-logger-amd64
7465
```
7566

76-
- Run the application
77-
```sh
78-
./ebpf-logger
67+
Run agent binary, with your value for `GL_APISECURITY_HOST`:
68+
```bash
69+
sudo USAGE_LOGGERS_EBPF_EXPATH="/lib/x86_64-linux-gnu/libssl.so.3" USAGE_LOGGERS_EBPF_ROLE="server" USAGE_LOGGERS_RULES="include debug" USAGE_LOGGERS_URL="https://GL_APISECURITY_HOST/fluke/message" ./ebpf-logger-amd64
7970
```
8071

72+
⚠️ Use `CRTL-C` to stop the agent.
8173

82-
### Building a new image
83-
84-
You can use your existing container images to build a new one that contains our binary:
74+
<a name="logging-from-docker-container"></a>
8575

86-
```dockerfile
87-
FROM yourapp:itstag
76+
## Logging from Docker Container
8877

89-
ENV USAGE_LOGGERS_URL="http://172.17.0.1:7701/message"
90-
ENV USAGE_LOGGERS_RULES="include debug"
91-
ENV USAGE_LOGGERS_EBPF_ROLE="server"
92-
# choose according to your CPU arch
93-
ENV USAGE_LOGGERS_EBPF_EXPATH="/lib/x86_64-linux-gnu/libssl.so.3"
94-
#ENV USAGE_LOGGERS_EBPF_EXPATH="/lib/aarch64-linux-gnu/libssl.so.3"
78+
coming soon!
9579

96-
COPY --chmod=755 ./ebpf-logger /usr/sbin/ebpf-logger
97-
RUN mkdir /var/log/graylog_ebpf_logger && touch /var/log/graylog_ebpf_logger/out.log /var/log/graylog_ebpf_logger/err.log
98-
ENTRYPOINT [ "/new-entrypoint.sh" ]
99-
```
80+
<a name="logging-from-kubernetes"></a>
10081

101-
With `new-entrypoint.sh` following this pattern:
82+
## Logging from Kubernetes
10283

103-
```
104-
#!/bin/sh
105-
106-
ebpf-logger >> /var/log/graylog_ebpf_logger/out.log 2>> /var/log/graylog_ebpf_logger/err.log &
107-
# call your usual entrypoint.sh from here
108-
```
109-
110-
<a name="build-from-source"></a>
111-
112-
## Building from source
113-
114-
Please, see our [CONTRIBUTING.md](https://github.com/resurfaceio/logger-ebpf/blob/master/CONTRIBUTING.md) guide.
84+
coming soon!
11585

11686
<a name="privacy"></a>
11787

11888
## Protecting User Privacy
11989

120-
Loggers always have an active set of <a href="https://resurface.io/rules.html">rules</a> that control what data is logged
121-
and how sensitive data is masked. All of the examples above apply a predefined set of rules, `include_debug`,
122-
but logging rules are easily customized to meet the needs of any application.
123-
124-
<a href="https://go2docs.graylog.org/apisecurity-current/logging_rules/logging_rules.htm">Logging rules documentation</a>
90+
Loggers always have an active set of [logging rules](https://go2docs.graylog.org/apisecurity-current/logging_rules/logging_rules.htm)
91+
that control what data is logged and how sensitive data is masked. All of the examples above apply a predefined set of rules (`include_debug`),
92+
but logging rules are easily customized to meet your privacy requirements.
12593

12694
---
127-
<small>&copy; 2025 <a href="https://resurface.io">Graylog, Inc.</a></small>
95+
<small>&copy; 2025 <a href="https://graylog.org/products/api-security/">Graylog, Inc.</a></small>

0 commit comments

Comments
 (0)