Skip to content

Commit

Permalink
fix: broken links in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
banditopazzo committed Oct 25, 2022
1 parent 1b731a6 commit 4e4e110
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 19 deletions.
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,10 +84,10 @@ We do not recommend build Pulsar from source. Building from source is only neces
## Resources

- [Read the docs](https://pulsar.sh/docs): understand how to install and set up Pulsar.
- [Concepts](https://pulsar.sh/docs/concepts): dive deep into Pulsar architecture and main concepts.
- [Tutorials](https://pulsar.sh/docs/tutorial): learn how to use Pulsar with practical examples.
- [Develop new modules](https://github.com/Exein-io/pulsar/blob/main/bpf-common/ProbeTutorial.md): build new eBPF probes and integrate them into Pulsar through the modules system;
- [Roadmap](https://github.com/Exein-io/projects/6): check out the plan for next Pulsar releases;
- [Concepts](https://pulsar.sh/docs/category/concepts): dive deep into Pulsar architecture and main concepts.
- [Tutorials](https://pulsar.sh/docs/category/tutorials): learn how to use Pulsar with practical examples.
- [Develop new eBPF modules](https://pulsar.sh/docs/developers/tutorials/create-ebpf-probe-module): build new eBPF probes and integrate them into Pulsar through the modules system;
- [Roadmap](https://github.com/orgs/Exein-io/projects/14): check out the plan for next Pulsar releases;
- [Support](https://discord.gg/MQgaTPef7a): join the Discord server for community support.

## Contributing
Expand Down
27 changes: 12 additions & 15 deletions bpf-common/ProbeTutorial.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# New eBPF probe tutorial
# Create eBPF probe module

This tutorial goes through the development of a simple Pulsar module
that watches for new file creations. For a complete and working example,
see the [file-system-monitor](../modules/file-system-monitor/) module.
see the [file-system-monitor](https://github.com/Exein-io/pulsar/tree/main/modules/file-system-monitor) module.

## Locating the best hook point with bpftrace

Expand All @@ -12,14 +12,11 @@ various eBPF connection points. If you haven't yet, go check the

When trying out new things, you start by looking for existing solutions. Key examples include the
[bpftrace](https://github.com/iovisor/bpftrace#tools)
and [bcc](https://github.com/iovisor/bcc/#tools) tool collections. You may then consider moving
to other tracing and security software using eBPF such as
[Tracee](https://github.com/aquasecurity/tracee/blob/main/pkg/ebpf/c/tracee.bpf.c),
[lockc](https://github.com/lockc-project/lockc) or others.
and [bcc](https://github.com/iovisor/bcc/#tools) tool collections.

Going back to our example, it turns out we can intercept file creations using the `security_inode_create` function:

```
```sh
sudo bpftrace -e 'kfunc:security_inode_create { printf("%s: %s\n", comm, str(args->dentry->d_name.name))}'
```

Expand All @@ -32,7 +29,7 @@ With all the necessary information gathered with the help of `bpftrace`, we can

We create a new Rust crate and we'll call it `file_created`.

```
```toml
[package]
name = "file_created"
version = "0.1.0"
Expand All @@ -55,6 +52,7 @@ The most important dependency is `bpf-common`, which re-exports [aya](https://gi
and contains some useful utilities for running, building and testing probes.

Next we create write a simple eBPF program, we'll name it `probe.bpf.c`.

```c
#include "common.bpf.h"

Expand Down Expand Up @@ -120,7 +118,7 @@ The central part of the module is the `program` function, which:
Just pass it down to `bpf_common::ProgramBuilder::new`.
- takes a `BpfSender`—the channel where we'll send the generated events. It's a trait so that
you can use whatever data structure you want for your application: modules can be used inside Pulsar,
but can also be used by themself. The [probe](../pulsar/bin/probe.rs) binary shows how
but can also be used by themself. The [probe](https://github.com/Exein-io/pulsar/blob/main/pulsar/src/bin/probe.rs) binary shows how
you can use our modules without running the full agent.
- returns a `bpf_common::Program`. The application will keep sending `EventT` events over the `sender`
channel until the program handle is dropped.
Expand All @@ -137,12 +135,11 @@ can be used to forward all generated events to the sender channel.
In case it's needed, `Program` also has a `poll` method for consuming eBPF HashMaps.

The application is almost ready to use and you should refer to the
[`probe` binary](https://github.com/Exein-io/pulsar-experiments/blob/cleanup/pulsar/bin/probe.rs)
for a simple way to link a and run it.
[probe](https://github.com/Exein-io/pulsar/blob/main/pulsar/src/bin/probe.rs) binary for a simple way to link a and run it.

We can now implement `probe.bpf.c` to get this example to work.

```C
```c
#include "common.bpf.h"

char LICENSE[] SEC("license") = "Dual BSD/GPL";
Expand Down Expand Up @@ -240,7 +237,7 @@ pub mod test_suite {
}
```

Finally, since this is a new module, you have to add it to the [test-suite main file](./src/main.rs):
Finally, since this is a new module, you have to add it to the [test-suite main file](https://github.com/Exein-io/pulsar/blob/main/test-suite/src/main.rs):
```rust
// List of modules we want to test
let modules = [
Expand Down Expand Up @@ -305,7 +302,7 @@ pub mod pulsar {
`file_created_task` is the async function that runs our module until the Pulsar agent sends us
the shutdown signal. By dropping `_program` we shut down the eBPF program and stop producing events.

All modules communicate using the agent's message bus, where [events](../pulsar-core/src/event.rs)
All modules communicate using the agent's message bus, where [events](https://github.com/Exein-io/pulsar/blob/main/pulsar-core/src/event.rs)
are sent and received.
Since we're writing a producer module, we'll get a sender with the `ModuleContext::get_sender()` method.
We can use that channel as a `BpfSender` for `bpf_common::Program` because we've implemented a conversion
Expand All @@ -324,4 +321,4 @@ Key take-aways:
and help writing tests.
- A module can be used as part of Pulsar or by itself. A generic Rust application could reuse a
particular probe without depending on the Pulsar agent.
- Writing tests first is the best way to develop a new probe.
- Writing tests first is the best way to develop a new probe.

0 comments on commit 4e4e110

Please sign in to comment.