traffico

2022-05-24T00:00:00+00:00

traffico is a collection of tools to shape traffic on a network using traffic control tc(8)</code>. It can be used via a CLI tool (traffico</code>) or as a CNI plugin (traffico-cni</code>). For a list of the available programs and what they do see theBuilt-in programs</a> section.

The built-in programs are very opinionated and made for the needs of the authors but the framework is flexible enough to be used for other purposes. You can add programs to the bpf/</code> directory to extend it to other use cases.

Contact§</a> </h2> If you have problems, questions, ideas or suggestions, please contact us by posting to https://github.com/leodido/traffico/issues. Download§</a> </h2> To download the very latest source do this: git clone https://github.com/leodido/traffico.git</code></pre>Authors§</a> </h2> Leonardo Di Donato</li> Lorenzo Fontana</li> </ul> Usage§</a> </h2> Traffico can be either used standalone or as a CNI plugin. traffico§</a> </h3> traffico</code> is a CLI tool that can be used to load and unload the programs. You can choose an interface and choose whether the program will be loaded in INGRESS</code> or EGRESS</code>. Start with a standalone block program when the policy targets specific traffic and should leave everything else alone: traffico --ifname=eth0 --at=INGRESS block_private_ipv4</code></pre> Programs that accept runtime input (marked [input]</code> in --help</code>) take it as a second positional argument: traffico --ifname=eth0 block_ipv4 10.0.0.1 traffico --ifname=eth0 block_port 443</code></pre> Use standalone allow programs when the interface should admit only the traffic described by that one program: traffico --ifname=eth0 allow_ipv4 10.0.0.10 traffico --ifname=eth0 allow_proto tcp+udp traffico --ifname=eth0 allow_ethertype ipv4+arp</code></pre> Use --chain</code> when the policy needs multiple ordered stages. Chains that contain L3/L4 programs must start with the L2 gate allow_ethertype</code>: traffico --ifname=eth0 --chain "allow_ethertype:ipv4+arp,allow_port:443"</code></pre> Chains compose checks linearly: each stage narrows the traffic that reaches the next stage. That works well for single-path policies such as HTTPS to one service: traffico --ifname=eth0 --at=EGRESS --chain \ "allow_ethertype:ipv4+arp,allow_ipv4:10.0.0.10,allow_proto:tcp,allow_port:443"</code></pre> Or DNS to one resolver: traffico --ifname=eth0 --at=EGRESS --chain \ "allow_ethertype:ipv4+arp,allow_dns:10.0.0.53"</code></pre> These examples are alternative linear policies, not an additive multi-flow allowlist. Full policies such as "DNS to resolver OR HTTPS to service" need explicit OR composition. Chain order is validated before attach. If a chain contains any L3/L4 program, slot 0 must be allow_ethertype</code>, and the layer order must be L2 -> L3 -> L4</code>. traffico-cni§</a> </h3> traffico-cni</code> is a meta CNI plugin that allows the traffico programs to be used in CNI. Meta means that traffico-cni</code> does not create any interface for you, it is intended to be used as a chained CNI plugin. The plugin block to use traffico-cni</code> is very similar to how traffico</code> is used as a CLI tool. { "type": "traffico-cni", "program": "block_private_ipv4", "attachPoint": "ingress" }</code></pre> Programs that accept runtime input use the "input"</code> field: { "type": "traffico-cni", "program": "block_ipv4", "input": "10.0.0.1", "attachPoint": "egress" }</code></pre> Here's an example CNI config file featuring traffico-cni</code>. { "name": "mynetwork", "cniVersion": "0.4.0", "plugins": [ { "type": "ptp", "ipMasq": true, "ipam": { "type": "host-local", "subnet": "10.10.10.0/24", "resolvConf": "/etc/resolv.conf", "routes": [ { "dst": "0.0.0.0/0" } ] }, "dns": { "nameservers": ["1.1.1.1", "1.0.0.1"] } }, { "type": "firewall" }, { "type": "traffico-cni", "program": "block_private_ipv4", "attachPoint": "ingress" }, { "type": "tc-redirect-tap" } ] }</code></pre>Design principles§</a> </h2> Principle</th> Description</th></tr></thead> Standalone vs chained</td> Standalone programs are the only filter on the interface and handle all traffic types themselves. Chained programs pass traffic they do not handle to the next program, trusting that an upstream filter (typically allow_ethertype</code>) already constrained it.</td></tr> Boundary failures</td> block_*</code> programs fail open (TC_ACT_OK</code>) on truncated headers, unsupported protocols, and subsequent fragments because they target specific traffic. allow_*</code> programs fail closed (TC_ACT_SHOT</code>) on the same failures because they define permitted traffic.</td></tr> L2 → L3 → L4 ordering</td> Chains run cheapest and broadest checks first: allow_ethertype</code> (L2), then allow_proto</code> (L3), then allow_port</code> or allow_dns</code> (L4). allow_ipv4</code> fits after L2 and alongside or after L3 protocol filtering.</td></tr> Non-IPv4 passthrough in chains</td> In chains, L3 and L4 programs pass non-IPv4 traffic to the next program via tail_call_next()</code>. L2 filtering is allow_ethertype</code>'s job; ARP, IPv6, and other non-IPv4 traffic allowed by L2 must not be silently dropped downstream.</td></tr> </tbody></table> Built-in programs§</a> </h2> Program</th> Description</th></tr></thead> allow_dns</code></td> Allows IPv4 DNS traffic (TCP/UDP port 53) to the input resolver. Other IPv4 traffic passes through. Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage.</td></tr> allow_ethertype</code></td> L2 gatekeeper: drops frames whose outer EtherType is not in the allowed set (e.g., ipv4+arp</code>). Required first when a chain contains L3/L4 programs.</td></tr> allow_ipv4</code></td> Allows IPv4 traffic to the input address, drops other IPv4 destinations except localhost (127.0.0.0/8). Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage.</td></tr> allow_port</code></td> Allows IPv4 TCP/UDP traffic to the input port. Other IPv4 protocols pass through. Standalone mode blocks non-IPv4; chain mode passes non-IPv4 to the next stage. TCP/UDP subsequent fragments are blocked.</td></tr> allow_proto</code></td> L3 gatekeeper: drops IPv4 packets whose IP protocol is not in the allowed set (e.g., tcp+udp</code>). It unwraps supported VLAN/QinQ tags before the IPv4 protocol check. Standalone mode blocks non-IPv4 after VLAN unwrap; chain mode passes it to the next stage.</td></tr> block_private_ipv4</code></td> Blocks private IPv4 addresses subnets allowing only SSH access on port 22</td></tr> block_ipv4</code></td> Drops packets with destination equal to the input IPv4 address</td></tr> block_port</code></td> Drops packets with the destination port equal to the input port number</td></tr> nop</code></td> A simple program that does nothing</td></tr> </tbody></table> Notes on allow_ethertype</code>§</a> </h3> Chain ordering: If a chain contains any L3/L4 program, slot 0 must be allow_ethertype</code>. Chain order must be non-decreasing by layer: L2 -> L3 -> L4</code>. Same-layer programs are allowed, and chains may skip L3 after the L2 gate, such as --chain "allow_ethertype:ipv4+arp,allow_port:443"</code>. VLAN-tagged networks: Standalone allow_ethertype</code> compares the EtherType in the outer Ethernet header only; it does not unwrap VLAN tags or match the inner payload EtherType. Symbolic names vlan</code> (0x8100) and qinq</code> (0x88A8) are available for standalone filters. In multi-program chains, VLAN TPIDs are rejected because VLAN-aware parsing is not uniform across downstream programs. Example (standalone): allow_ethertype ipv4+arp+vlan</code>. Notes on allow_proto</code>§</a> </h3> Chain ordering: In a chain, allow_proto</code> should be placed after allow_ethertype</code> and before allow_port</code>/allow_dns</code>. This gives L2 -> L3 -> L4</code> ordering with cheapest checks first. Example: --chain "allow_ethertype:ipv4+arp,allow_proto:tcp+udp,allow_port:8080"</code>. VLAN-tagged IPv4: allow_proto</code> unwraps supported 802.1Q and QinQ tags before reading the IPv4 protocol. Truncated VLAN headers and unsupported additional VLAN nesting fail closed. Non-IPv4 behavior: In standalone mode, non-IPv4 traffic is blocked after VLAN unwrap because the program is the complete policy. In chain mode, non-IPv4 traffic is passed to the next stage because L2 policy belongs to allow_ethertype</code>. Build§</a> </h2> To compile traffico from source you either provide your vmlinux.h</code> in the vmlinux/</code> directory (default option) or you configure the project to generate one from your current Linux kernel: xmake f --generate-vmlinux=y</code></pre> Now you will be able to build traffico from source by running: xmake</code></pre> In case you only want to compile the BPF programs you can do this: xmake -b bpf</code></pre>Test§</a> </h2> To run the test suite you can do this: xmake -b test xmake run test</code></pre> The full test suite includes Scapy-backed advanced packet tests that exercise IP options, fragmentation, and protocol-specific behavior. These require the python-scapy</code> (Arch) or python3-scapy</code> (Ubuntu) package. If Scapy is not installed, the advanced tests are skipped automatically. Code coverage for eBPF programs 2022-02-07T00:00:00+00:00 I bet we all have heard so much about eBPF</abbr> in recent years. Every day we hear about a new project or application using some eBPF black magic underneath. Data</a> shows that eBPF is quickly becoming the first choice for implementing tracing and security applications. However, one major challenge is that the eBPF ecosystem lacks tooling to make developers' lives easier. eBPF programs are written in C but compiled for a specific ISA later executed by the eBPF Virtual Machine. LLVM has a specific backend allowing us to write C and get eBPF ELF objects out. There are no tools helping developers to clearly understand which path their code took while running in the Linux kernel, which code regions, or, even better, code branches are uncovered, and maybe why. You may already be familiar with code coverage, which shows you which lines of code execute. Code coverage is usually applied to tests to discover which line gets run and which does not. But even testing the eBPF programs is a pain, given that BPF_PROG_TEST_RUN</code> does not support all the types of eBPF programs living in the Linux kernel. That's why I sat down and wrote bpfcov</a>: a tool to gather source-based coverage info for our eBPF programs running in the Linux kernel. Whether they are getting loaded via BPF_PROG_TEST_RUN</code> or by other ordinary means. Until today, there was no simple way to visualize how the flow of your eBPF program running in the kernel was. Hopefully, there is one starting today. So, let's jump straight into the topic. Source-based code coverage for eBPF§</a> </h2> Everyone reading this post probably knows what the code coverage is. Common line-level coverage gives us a sense of what line is executed. In some cases, it even tells us how many times a line got executed. When building this tool, driven by my experience fighting with BPF, I knew I wanted something more. Line-level granularity is often too coarse. We do not want an approximation of what code actually executed. We need something more precise to understand the execution path of our eBPF programs in the Linux kernel. We even want to know what part of an if</code> conditional executed</label>I suggest you watch this talk</a> by Alan Phipps to know more about branch coverage.. Source-based code coverage is what I wanted for this reason. Since it starts at code generation time in LLVM, it has the notion of regions of the code, branches, and so on. It even precisely counts things like short-circuited conditionals, thanks to the counter expression and arithmetics between them. It generates coverage summaries with very fine-grained code regions, helping us find gaps in the code and its execution flow. So, given eBPF programs are usually written in C, couldn't we just instrument them for source-based code coverage</a> as we would commonly do with Clang for our C programs? I bet this is the first argument popping into the head of many readers. It also was one of my thoughts when approaching this problem. Turns out that we definitely can, and we will do it. But it won't work as is. To understand why it won't work, we need to keep in mind that BPF programs are compiled via Clang</label>Thanks to the LLVM BPF target</a>. to BPF ELF object files, containing instructions specific to the chosen BPF instruction set, which need to be later loaded in the Linux kernel via the bpf()</a> syscall. Furthermore, it's paramount to mention that the BPF programs will be verified by an in-kernel verifier and then executed by the BPF VM. Such a lifecycle and environment imposes a set of constraints that make it infeasible to get them working with the plain instrumentation that LLVM applies to get source-based code coverage. In fact, when compiling a C program for source-based coverage with the -fprofile-instr-generate</code> and -fcoverage-mapping</code> Clang flags, LLVM instruments it with a bunch of global variables and, in some cases, functions. Observing the LLVM IR of a C program after compiling it with the -fprofile-instr-generate</code> flag, we can notice that, LLVM... defines the counters, in the form of __profc_<function_name></code> private global arrays whose size is the number of counters needed to cover all the regions and branches of such a function</li> marks those counters to be into the __llvm_prf_cnts</code> section of the ELF</li> defines (and initializes) __profd_<function_name></code> private global struct instances that contains an identifier of the function, the pointer to its counters, the pointer to the function itself, the number of the counters for the target function, and a bunch of other info needed to tie together the counters and the coverage mappings</li> marks the __profd_</code> globals to end up into the __llvm_prf_data</code> section of the ELF</li> defines (and initializes) a private constant (__llvm_prf_nm</code>) containing the names of the target functions</li> marks the names constant to end up in the __llvm_prf_names</code> section of the ELF</li> </ul> The first issue to address here is that we can't have random ELF sections (like__llvm_prf_cnts</code>, etc.) into valid BPF ELF files. We know that we can have eBPF global constants with a scalar type like __profc_</code> ones, at least on recent Linux kernels. At the same time, we know it's not wise to have global structs like __profd_</code> or whatever loader for our eBPF programs we will write, as we'll need the struct definitions. Too clunky. The -fprofile-instr-generate</code> flag also generates a global constructor and a set of global functions, all prefixed with __llvm_profile</code>, intended to set up the profiling runtime in the resulting binary so that when it dies or exits it will automatically generate a profraw file. Here we meet another stumbling block to overcome. The BPF verifier will refuse our BPF ELF containing strange global functions, not to mention "constructors"... We need to get rid of them and replace their functionality with a feasible approach for BPF. Clearly, LLVM also patches our instructions in the right spots, by placing the counters and incrementing them. As you can see in the following annotated screenshot: </a> If you write an eBPF program incrementing a counter (defined as an eBPF global variable) you will notice that the resulting instructions will be like those here in the screenshot. It means we can keep these the way they are generated by LLVM and let it do all its magic without interfering at the instructions level. Finally, some good news! Instead, focusing on the -fcoverage-mapping</code> Clang flag and inspecting the LLVM IR it outputs, we notice that it... defines (and initializes) __covrec_</code> global (constant) structs, most notably containing the same ID that the __profd_</code> variables contain, and a LEB128</label>The encoding of the coverage mapping values is LEB128</a>. encoded string containing all the region, branches, and generally the coverage mapping info</li> defines (and initializes) a __llvm_coverage_mapping</code></label>The Coverage Mapping</a> format. function containing meta info about the coverage mapping format (eg., the version), and the source file names</li> marks the __llvm_coverage_mapping</code> variable to be put into the __llvm_covmap</code> section of the ELF.</li> </ul> In this case, we have the same category of issues mentioned before. We need to keep at least the header of __llvm_coverage_mapping</code> because it contains the coverage mappings version, which we need for generating a valid profraw file</label>More on the profraw format in a previous blog post</a>.. Also, we need to put it in a custom BPF ELF section. Luckily, we can remove the __covrec_</code> structs from the BPF ELF meant to be loaded in the kernel. We can keep them in a second BPF ELF that would be intended to be given to tools needing the coverage mappings for generating the coverage reports, just like llvm-cov does. How it's done§</a> </h2> libBPFCov.so - A LLVM pass§</a> </h3> By analyzing the resulting LLVM IR for source-based coverage instrumented programs, we should now have a better understanding of what we need to do for having it on eBPF programs running in the Linux kernel. We now know what to completely get rid of and do differently, and what we need to patch to make it loadable and usable by the BPF VM in the kernel. The plan is simple: get Clang to instrument a BPF LLVM intermediate representation for source-based code coverage, then patch it to model it into a valid representation for BPF ELF. How do we need to transform it? First of all, we are so lucky we don't have to mess with the actual BPF instructions, namely the counters increments. We can keep them the way they are. This is a huge win because we let LLVM keep track of the global state of the registers and we avoid a lot of work this way. But for sure we have to strip any profile initialization stuff that Clang creates, things like __llvm_profile_runtime</code> and __llvm_profile_init</code> - when present - are no good for the BPF VM in the kernel. We also want to ensure the global variables, whether constants or not, have the right visibility (ie., dso_local</code>) and linkage, to have them in the libbpf skeletons if we plan to use them. For the global structs that we need for generating the profraw files, namely the __profd_</code> variables, we just transform them into different and single global variables, one for each field. For example, this is what I did for the __profd_*</code> variables which originally are a struct with 7 fields. For other global structs like the __covrec_</code> ones, we can just strip them from the BPF ELF that is meant to be loaded in the kernel. Anyway, the report generation phase (ie., llvm-cov or bpfcov out) will need them for knowing at which line and column a code region or a branch starts. For this reason, I decided to give the LLVM pass an option (enabled with the strip-initializers-only</code> flag) that keeps them, so we can later create a BPF ELF that is only meant for this phase and not for loading. This BPF ELF will have .bpf.obj</code> as an extension, rather than .bpf.o</code>. Finally, we know that libbpf</a> supports (on recent Linux kernels) eBPF global variables</label>Kernel patch: eBPF support for global data</a>., which are simply eBPF maps with one single value, and we are planning to use them. But, as already mentioned, it does not accept or recognize the ELF sections that the Clang instrumentation injects in the intermediate representation. So we need our LLVM pass to change them to custom eBPF sections</label>Kernel patch: libbpf: support global data/bss/rodata sections</a>.. The eBPF custom sections are in the form of .rodata.*</code> or .data.*</code> made to contain static and/or global data. We can change the section of the counters to be .data.profc</code>. The section of the __llvm_prf_nm</code> from _llvm_prf_names</code> to .rodata.profn</code>, and so on. You can find all this logic summarized in these bits of code</a>. So, assuming the following dummy eBPF program: </a> I think that the following snippet tells everything about what we obtain from the libBPFCov.so LLVM pass: </a> For example, you may notice that we have 2 __profc_</code> counters. The first is for the BPF_PROG</code> macro that expands to a function, the second for the actual BPF raw tracepoint program hook_sys_enter</code>. This one has size 3. That's because the hook_sys_enter</code> function has 3 main regions: the entry of the function, the if</code> conditional, and the for</code> cycle. You may also notice that the LLVM pass, for each one of the 2 functions we have, split the __profd_</code> global structs into 7 different global variables in the .rodata.profd</code> section. Someone who has an eye for it may also have noticed that the third field of __profd_</code> (now __profd_something.2</code>) does not contain anymore the address of its counters. I didn't want (nor I could) to expose kernel addresses, so I put here the offset of the counters in their section (.data.profc</code>). Finally, you can also see that, as anticipated before, we completely deleted the __covrec_</code> global constant structs from this IR that's meant to generate a valid and loadable BPF ELF. While the instructions incrementing the counters in the correct spots are not touched at all. So we don't need another screenshot to show them! The only missing moving part is how to generate a valid profraw file. We stripped any logic for doing it. We know that for generating it we need all the globals we left in this LLVM intermediate representation. But we have no sane way to hook the exit or the stop of an eBPF program in the Linux kernel. Suddenly, inspiration came: let's pin the globals to the BPF file system so that we can decouple the process of generating the profraw file from the running (and exiting) of the instrumented eBPF application! And that's what the bpfcov CLI does. Before moving to the next section, I suggest you go to the bpfcov repository</a> and start building the pass to obtain libBPFCov.so. You can find the instructions on how to build it here</a>. Instrument your eBPF program§</a> </h2> Now that we have built libBPFCov.so we can finally take action! Instrumenting an eBPF program for source-based coverage is not that different than compiling it normally with Clang and the BPF target. The only difference is that we ask Clang to output LLVM IR (either in textual or binary form), run the libBPFCov.so pass on it (with opt</code>), and finally compile it (with llc</code>) to a BPF ELF. clang -g -O2 \ -target bpf \ -D__TARGET_ARCH_x86 -I$(YOUR_INCLUDES) \ -fprofile-instr-generate -fcoverage-mapping \ -emit-llvm -S \ -c raw_enter.bpf.c -o raw_enter.bpf.ll opt -load-pass-plugin $(BUILD_DIR)/lib/libBPFCov.so -passes="bpf-cov" \ -S raw_enter.bpf.ll -o raw_enter.bpf.cov.ll llc -march=bpf -filetype=obj -o cov/raw_enter.bpf.o raw_enter.bpf.cov.ll</code></pre> You can see in the Makefile inside the examples/src</a> directory of the bpfcov GitHub repository</a> how to automate those steps. We now have a valid and coverage instrumented BPF ELF: cov/raw_enter.bpf.o</code>. From now on, you can instruct your loader and userspace code to use it, so to obtain a binary (eg., /cov/raw_enter</code>) that is your eBPF application. Use it§</a> </h3> bpfcov run + bpfcov gen§</a> </h4> What's left to do? Just three steps: Run our eBPF application with the bpfcov CLI run command</li> Generate its profraw file</li> Generate beautiful source-based coverage reports</li> </ol> So, let's run our eBPF application with: sudo ./bpfcov -v2 run cov/raw_enter</code></pre> This command acts similar to strace. It will detect the bpf()</code> syscalls with the BPF_MAP_CREATE</code> command. Meaning that it will detect the eBPF globals in the .profc</code>, .profd</code>, .profn</code>, and .covmap</code> custom eBPF sections and pin them to the BPF file system, as you can see in the following screenshot. </a> You may also notice that - since the LLVM pass annotated the counters correctly - libbpf can collect relocations for them... At this point, whether we stopped our eBPF application or it exited... We have eBPF maps pinned to our BPF file system. Let's check it: </a> </figure> Wonderful, we already know that the hook_sys_enter</code> function executed 1 time, the if</code> condition did not evaluate to true, while the for</code> iterated 9 times! It's time to put the counters, the function names, the functions data, in a profraw file now. This is why the bpfcov gen command exists: to dump the pinned maps in a profraw file. sudo ./bpfcov -v2 gen –unpin cov/raw_enter</code></pre> </a> </figure> And this is the resulting profraw file for our instrumented eBPF program! You can see it's made of four parts: a header, .rodata.profd</code>, .data.profc</code> (ie., the counters!), and the names (.rodata.profn</code>), plus some padding for alignment... </a> </figure> We can now either use the existing LLVM tools (llvm-profdata and llvm-cov) with it or simply use the bpfcov out subcommand. The bpfcov out command is an opinionated shortcut to generate HTML, JSON, or LCOV coverage reports even from multiple eBPF programs and their profraw files. It is very convenient because it avoids us having to generate profdata from the profraw, calling llvm-cov with a bunch of long and different options. And it even works with multiple profraw files coming from different eBPF applications... ./bpfcov out -o yey –f html cov/raw_enter.profraw ...</code></pre> It outputs a very nice HTML directory whose index file gives us summaries not only about function and line coverage but also and notably about region and branch coverages for our eBPF applications. </a> </figure> By clicking on any item in the table we end up visualizing very fine-grained, source-based coverage. A good example is the one in the following image: </a> </figure> Furthermore, it does work also on very complicated and real-life eBPF programs. For example, the following screenshot is a part of the coverage report obtained for a BPF LSM test (progs/lsm.c</a>, loaded by prog_tests/test_lsm.c</a>) living in the Linux kernel. </a> Thanks to this tool I can finally understand that over a total of eight executions of the lsm/file_mprotect</code> BPF LSM program on my kernel, its is_stack</code> variable was true two times out of eight, because six times the vma->vm_end >= vma->vm_mm->start_stack</code> branch condition (98:58) evaluated to false. Line 100, using is_stack</code> in another condition, confirms that it was indeed true two times out of six. And that, for this reason (first operand - 100:6 - is_stack</code> being false six times), the following check (100:18) on monitored_pid</code> was short-circuited and evaluated (to true, by the way) only two times. We finally have a tool helping us write and understand the way our eBPF programs run in the Linux kernel. I can't stress enough how this is something I dreamt of so many times during the past few years I've been working with BPF... Hope that the eBPF community and ecosystem will find bpfcov useful and cool the same way I do. Bits of the future§</a> </h2> The bpfcov</a> tool is open-source, and it will stay that way. It is still in its early days so it will probably need a bit more tests, examples, and fixes. Just like any new software out there. I will soon publish another project showcasing the coverage of the kernel BPF selftests, using this tool. This means there are a lot of contribution opportunities. I'd invite you to take a look at its source code</a> and send patches! :blush: Also, in case you want to start using it on your eBPF applications and repositories, feel free to contact me for support. I'd love to help you to use it. From a technical perspective these are the topics that are on top of my mind for its future: A project like bpfcov</a> must have a logo!</li> Write llvm-lit tests for the libBPFCov.so LLVM pass</li> Support newer LLVM versions</li> Workaround solutions to have it working on Linux kernels where BPF does not support custom eBPF sections and eBPF globals</li> Create a versioning and release process</li> Publish artifacts on GitHub (libBPFCov.so, bpfcov CLI binary)</li> Add more examples</li> Publish HTML reports of the example eBPF applications via GitHub pages</li> Maybe, contribute it upstream to the LLVM BPF target!</li> </ul> FOSDEM 2022§</a> </h2> In case you made it to the end, and you still want to hear more details on building source-based coverage for eBPF, I want to bring to your attention that I gave a talk</a> on bpfcov</a> at FOSDEM 2022</a>. I will update my speaking</a> section with the video recording as soon it'll be ready. In the meantime, you can take a look at the talk's deck</a></label>While you can find the slides in PDF and markdown format here, if you prefer</a>.. While at elastic/bpfcov</a> you can take a look at the project. Don't forget to star it, if you don't mind! :star: bpfcov 2022-01-10T00:00:00+00:00 This project provides 2 main components: libBPFCov.so</code> - an out-of-tree LLVM pass to instrument your eBPF programs for coverage.</li> bpfcov</code> - a CLI to collect source-based coverage from your eBPF programs.</li> </ol> </th> </th> </th></tr></thead> </a></td> </a></td> </a></td></tr> </a></td> </a></td> </a></td></tr> </a></td> </a></td> </a></td></tr> </tbody></table> Overview§</a> </h2> This section aims to provide a high-level overiew of the steps you need to get started with bpfcov. Compile the LLVM pass</a> obtaining libBPFCov.so</code></li> Instrument your eBPF program by compiling it and by running the LLVM pass (libBPFCov.so</code>) on it</li> Build the userspace code of your eBPF application</li> Execute your eBPF application in the kernel through the bpfcov run ...</code> command</li> Generate the .profraw</code> file from the run through the bpfcov gen ...</code> command Having a .profraw</code> makes this tool fully interoperable</li> Having a .profraw</code> allows you to generate a variety of coverage reports in different formats</li> </ol> </li> Use the LLVM toolchain to create coverage reports as documented in the LLVM docs</a></li> </ol> In case you are impatient and want to jump straight into getting your hands dirty, then the examples</a> directory contains a few dummy eBPF programs to showcase what bpfcov does. It basically automates steps 2 and 3. Its README</a> contains more details. While the README of the cli directory</a> gives you more details about the steps 4 and 5 (and also 6). Usage§</a> </h2> Here I will highlight the manual steps to use it. I suggest you to automate most of them like I did in the examples Makefile</a>. Anyway, assuming you have built</a> the LLVM pass, you can then use your fresh libBPFCov.so</code> to instrument your eBPF programs for coverage (steps 2 and 3 above). How to do it? First, you need to compile your eBPF program almost as usual but to LLVM IR... clang -g -O2 \ -target bpf -D__TARGET_ARCH_x86 -I$(YOUR_INCLUDES) \ -fprofile-instr-generate -fcoverage-mapping \ -emit-llvm -S \ -c program.bpf.c \ -o program.bpf.ll</code></pre> Notice it doesn't matter if you use the textual (*.ll</code>) or the binary form (*.bc</code>). Obviously, the former is more readable. The same logic applies to opt</code>: by default it generates *.bc</code>. Using the -S</code> flag you can obtain the output in textual form (*.ll</code>). Anyhow, it's time to run the LLVM pass on the LLVM IR we obtained. Let's do it: opt -load-pass-plugin $(BUILD_DIR)/lib/libBPFCov.so -passes="bpf-cov" \ -S program.bpf.ll \ -o program.bpf.cov.ll</code></pre> We should have obtained a new LLVM IR that's now valid and loadable from the BPF VM in the Linux kernel. Almost there, YaY! From it, we can obtain a valid BPF ELF now: llc -march=bpf -filetype=obj -o cov/program.bpf.o program.bpf.cov.ll</code></pre> While we are at it, it is also worth running the LLVM pass again (with a flag) to obtain another BPF ELF containing all the profiling and coverage mapping info. It will come in handy later with llvm-cov</code>. opt -load $(BUILD_DIR)/lib/libBPFCov.so -strip-initializers-only -bpf-cov \ program.bpf.ll | \ llc -march=bpf -filetype=obj -o cov/program.bpf.obj</code></pre> At this point, we can compile our userspace application loading the eBPF instrumented program (cov/program.bpf.o</code>). Doing this when using libbpf</code> and skeletons is very easy. Nothing different from the common steps: bpftool</code>, cc</code>, etc. In the examples</a> directory, you can find further explainations. So assuming we got our instrumented binary ready (cov/program</code>), we can run it via the bpfcov</code> CLI. sudo ./bpfcov run cov/program # Wait for it to exit, or stop it with CTRL+C sudo ./bpfcov gen --unpin cov/program</code></pre> Again, in case you wanna know more about these 2 steps, refer this time to the CLI README</a>. Now we have a magic cov/program.profraw</code> file... And we can use the LLVM toolchain to generate very fine-grained coverage reports like those in the screenshots! Refer to the LLVM docs</a> to learn how to do it. But no worries, it's just about invoking llvm-profdata</code> and llvm-cov</code>: lvm-profdata merge -sparse cov/program.profraw -o cov/program.profdata llvm-cov show \ --format=html \ --show-line-counts-or-regions --show-region-summary --show-branch-summary \ --instr-profile=cov/profdata.profdata \ -object cov/program.bpf.obj \ --output-dir=cov/html_report</code></pre> Anyayws, bpfcov also provides you an opinionated shortcut command to generate HTML, JSON, and LCOV coverage reports: ./bpfcov out --format=html cov/program.profraw</code></pre>Development Environment§</a> </h2> In order to build the BPFCov library (libBPFCov.so</code>) you will need: LLVM 12+</li> CMake 3.13.4+</li> C++ compiler that supports C++14</li> </ul> In order to use it, you will need: clang 12 (to generate the input LLVM files)</li> its opt</a> binary to run the LLVM pass</li> </ul> This project has been tested on 5.15 Linux kernels. Building§</a> </h2> Build as follows: mkdir -p build && cd build cmake -DLT_LLVM_INSTALL_DIR=/path/to/llvm/installation .. make</code></pre> Notice that the LT_LLVM_INSTALL_DIR</code> variable should be set to the root of either the installation (usually /usr</code>) or the build directory of LLVM. It is used to locate the corresponding LLVMConfig.cmake</code> script that is used to set the include and the library paths. Testing§</a> </h2> TBD To run the tests you will need to install llvm-lit. Usually, you can install it with pip: pip install lit</code></pre> Running the tests is as simple as: lit build/test</code></pre> falco 2016-01-19T00:00:00+00:00 </a> Falco</a> is a cloud native runtime security tool for Linux operating systems. It is designed to detect and alert on abnormal behavior and potential security threats in real-time. At its core, Falco is a kernel monitoring and detection agent that observes events, such as syscalls, based on custom rules. Falco can enhance these events by integrating metadata from the container runtime and Kubernetes. The collected events can be analyzed off-host in SIEM or data lake systems. Falco, originally created by Sysdig</a>, is a graduated project under the Cloud Native Computing Foundation</a> (CNCF) used in production by various organisations</a>. For detailed technical information and insights into the cyber threats that Falco can detect, visit the official Falco</a> website. For comprehensive information on the latest updates and changes to the project, please refer to the Change Log</a>. The Falco Project§</a> </h2> The Falco Project codebase is maintained under the falcosecurity GitHub organization</a>. The primary repository, falcosecurity/falco</a>, holds the source code for the Falco binary, while other sub-projects are hosted in dedicated repositories. This approach of isolating components into specialized repositories enhances modularity and focused development. Notable core repositories</a> include: falcosecurity/libs</a>: This repository hosts Falco's core libraries, which constitute the majority of the binary’s source code and provide essential features, such as kernel drivers.</li> falcosecurity/rules</a>: It contains the official ruleset for Falco, offering pre-defined detection rules for various security threats and abnormal behaviors.</li> falcosecurity/plugins</a>: This repository supports integration with external services through plugins that extend Falco's capabilities beyond syscalls and container events, with plans for evolving specialized functionalities in future releases.</li> falcosecurity/falcoctl</a>: A command-line utility designed for managing and interacting with Falco.</li> falcosecurity/charts</a>: This repository provides Helm charts for deploying Falco and its ecosystem, simplifying the installation and management process.</li> </ul> For further insights into our repositories and additional details about our governance model, please visit the official hub of The Falco Project: falcosecurity/evolution</a>. Getting Started with Falco§</a> </h2> If you're new to Falco, begin your journey with our Getting Started</a> guide. For production deployments, please refer to our comprehensive Setup</a> documentation. As final recommendations before deploying Falco, verify environment compatibility, define your detection goals, optimize performance, choose the appropriate build, and plan for SIEM or data lake integration to ensure effective incident response. Demo Environment§</a> </h3> A demo environment is provided via a docker-compose file that can be started on a docker host which includes falco, falcosidekick, falcosidekick-ui and its required redis database. For more information see the docker-compose section</a> Join the Community§</a> </h2> To get involved with the Falco Project please visit the Community</a> repository to find more information and ways to get involved. If you have any questions about Falco or contributing, do not hesitate to file an issue or contact the Falco maintainers and community members for assistance. How to reach out? Join the #falco</a> channel on the Kubernetes Slack</a>.</li> Join the Falco mailing list</a>.</li> File an issue</a> or make feature requests.</li> </ul> Commitment to Falco's Own Security§</a> </h2> Full reports of various security audits can be found here</a>. In addition, you can refer to the falco</a> and libs</a> security sections for detailed updates on security advisories and policies. To report security vulnerabilities, please follow the community process outlined in the documentation found here</a>. Building§</a> </h2> For comprehensive, step-by-step instructions on building Falco from source, please refer to the official documentation</a>. Testing§</a> </h2> Expand Testing Instructions</summary> Falco's Build Falco from source</a> is the go-to resource to understand how to build Falco from source. In addition, the falcosecurity/libs</a> repository offers additional valuable information about tests and debugging of Falco's underlying libraries and kernel drivers. Here's an example of a cmake</code> command that will enable everything you need for all unit tests of this repository: cmake \ -DUSE_BUNDLED_DEPS=ON \ -DBUILD_DRIVER=ON \ -DBUILD_FALCO_MODERN_BPF=ON \ -DCREATE_TEST_TARGETS=ON \ -DBUILD_FALCO_UNIT_TESTS=ON ..;</code></pre> Build and run the unit test suite: nproc=$(grep processor /proc/cpuinfo | tail -n 1 | awk '{print $3}'); make -j$(($nproc-1)) falco_unit_tests; # Run the tests sudo ./unit_tests/falco_unit_tests;</code></pre> Optionally, build the driver of your choice and test run the Falco binary to perform manual tests. Lastly, The Falco Project has moved its Falco regression tests to falcosecurity/testing</a>. </details> How to Contribute§</a> </h2> Please refer to the Contributing</a> guide and the Code of Conduct</a> for more information on how to contribute. FAQs§</a> </h2> Why is Falco in C++ rather than Go or {language}?§</a> </h3> Expand Information</summary> The first lines of code at the base of Falco were written some time ago, where Go didn't yet have the same level of maturity and adoption as today.</li> The Falco execution model is sequential and mono-thread due to the statefulness requirements of the tool, and so most of the concurrency-related selling points of the Go runtime would not be leveraged at all.</li> The Falco code deals with very low-level programming in many places, and we all know that interfacing Go with C is possible but brings tons of complexity and tradeoffs to the table.</li> As a security tool meant to consume a crazy high throughput of events per second, Falco needs to squeeze performance in all hot paths at runtime and requires deep control on memory allocation, which the Go runtime can't provide (there's also garbage collection involved).</li> Although Go didn't suit the engineering requirements of the core of Falco, we still thought that it could be a good candidate for writing Falco extensions through the plugin system. This is the main reason we gave special attention and high priority to the development of the plugin-sdk-go.</li> Go is not a requirement for having statically-linked binaries. In fact, we provide fully-static Falco builds since few years. The only issue with those is that the plugin system can't be supported with the current dynamic library model we currently have.</li> The plugin system has been envisioned to support multiple languages, so on our end maintaining a C-compatible codebase is the best strategy to ensure maximum cross-language compatibility.</li> In general, plugins have GLIBC requirements/dependencies because they have low-level C bindings required for dynamic loading. A potential solution for the future could be to also support plugin to be statically-linked at compilation time and so released as bundled in the Falco binary. Although no work started yet in this direction, this would solve most issues you reported and would provide a totally-static binary too. Of course, this would not be compatible with dynamic loading anymore, but it may be a viable solution for our static-build flavor of Falco.</li> Memory safety is definitely a concern and we try our best to keep an high level of quality even though C++ is quite error prone. For instance, we try to use smart pointers whenever possible, we build the libraries with an address sanitizer in our CI, we run Falco through Valgrind before each release, and have ways to stress-test it to detect performance regressions or weird memory usage (e.g. https://github.com/falcosecurity/event-generator). On top of that, we also have third parties auditing the codebase by time to time. None of this make a perfect safety standpoint of course, but we try to maximize our odds. Go would definitely make our life easier from this perspective, however the tradeoffs never made it worth it so far due to the points above.</li> The C++ codebase of falcosecurity/libs, which is at the core of Falco, is quite large and complex. Porting all that code to another language would be a major effort requiring lots of development resource and with an high chance of failure and regression. As such, our approach so far has been to choose refactors and code polishing instead, up until we'll reach an optimal level of stability, quality, and modularity, on that portion of code. This would allow further developments to be smoother and more feasibile in the future.</li> </ol> </details> What's next for Falco?§</a> </h3> Stay updated with Falco's evolving capabilities by exploring the Falco Roadmap</a>, which provides insights into the features currently under development and planned for future releases. License§</a> </h2> Falco is licensed to you under the Apache 2.0</a> open source license. Resources§</a> </h2> Governance</a></li> Code Of Conduct</a></li> Maintainers Guidelines</a></li> Maintainers List</a></li> Repositories Guidelines</a></li> Repositories List</a></li> Adopters List</a></li> Release Process</a></li> Setup documentation</a></li> Troubleshooting</a></li> </ul>

License §</a> </h2>
Apache License 2.0</a>. Project attribution in NOTICE</a>, per Apache 2.0 §4(d).</p>

traffico

Code coverage for eBPF programs

bpfcov

falco

Demo Environment §</a> </h3>
A demo environment is provided via a docker-compose file that can be started on a docker host which includes falco, falcosidekick, falcosidekick-ui and its required redis database. For more information see the docker-compose section</a></p>

Building §</a> </h2>
For comprehensive, step-by-step instructions on building Falco from source, please refer to the official documentation</a>.</p>

How to Contribute §</a> </h2>
Please refer to the Contributing</a> guide and the Code of Conduct</a> for more information on how to contribute.</p>

What's next for Falco?§</a> </h3>
Stay updated with Falco's evolving capabilities by exploring the Falco Roadmap</a>, which provides insights into the features currently under development and planned for future releases.</p>

License §</a> </h2>
Falco is licensed to you under the Apache 2.0</a> open source license.</p>

Resources §</a> </h2>

Governance</a></li>
Code Of Conduct</a></li>
Maintainers Guidelines</a></li>
Maintainers List</a></li>
Repositories Guidelines</a></li>
Repositories List</a></li>
Adopters List</a></li>
Release Process</a></li>
Setup documentation</a></li>
Troubleshooting</a></li> </ul>

leodido.dev - eBPF

kfeatures

Stability§</a> </h2>
Pre-1.0. The public API may change between minor versions; breaking changes are called out explicitly in CHANGELOG.md</a>. The `FromELF</code> contract (signature, determinism, fail-closed semantics) is frozen; seeCONTRIBUTING.md</a>.</p>`

leodido.dev - eBPF

kfeatures

Stability§</a> </h2> Pre-1.0. The public API may change between minor versions; breaking changes are called out explicitly in CHANGELOG.md</a>. The FromELF</code> contract (signature, determinism, fail-closed semantics) is frozen; see CONTRIBUTING.md</a>.</p>

traffico

Code coverage for eBPF programs

Use it§</a> </h3> bpfcov run + bpfcov gen§</a> </h4> What's left to do? Just three steps:</p> Run our eBPF application with the bpfcov</mark> CLI</strong> run command</li> Generate its profraw</mark> file</li>

bpfcov run + bpfcov gen§</a> </h4> What's left to do? Just three steps:</p> Run our eBPF application with the bpfcov</mark> CLI</strong> run command</li> Generate its profraw</mark> file</li>

bpfcov

falco

Stability§</a> </h2>
Pre-1.0. The public API may change between minor versions; breaking changes are called out explicitly in CHANGELOG.md</a>. The `FromELF</code> contract (signature, determinism, fail-closed semantics) is frozen; seeCONTRIBUTING.md</a>.</p>`