Adding New Modules ​

This document provides a comprehensive guide for implementing new capture modules in the ecapture system. It covers the module architecture, interface requirements, eBPF integration, and step-by-step implementation process.

For information about the overall system architecture, see Architecture. For details on the existing capture modules, see Capture Modules. For eBPF program development specifics, see eBPF Programs.

Module Architecture Overview ​

The ecapture module system is built around a plugin-like architecture where each module implements the IModule interface to capture specific types of network traffic or system events. All modules follow a consistent pattern of eBPF program management, event processing, and data output.

Sources: user/module/imodule.go:38-66, user/module/probe_openssl.go:83-106, user/module/probe_bash.go:42-49

Core Interface Requirements ​

Every module must implement the IModule interface and embed the Module base struct. The interface defines the essential lifecycle and functionality methods:

The base Module struct provides common functionality including event processing, BTF detection, and eBPF program lifecycle management.

Sources: user/module/imodule.go:38-66, user/module/imodule.go:74-97

Module Implementation Pattern ​

All concrete modules follow a consistent implementation pattern with specific struct fields and initialization steps:

Sources: user/module/probe_openssl.go:83-106, user/module/probe_bash.go:42-49, user/module/probe_nspr.go:38-44

eBPF Program Integration ​

Modules integrate with eBPF programs through the manager.Manager system, which handles program loading, attachment, and map management. Each module must define its probe configuration and map requirements:

Sources: user/module/probe_bash.go:147-236, user/module/probe_openssl.go:285-355, user/module/probe_nspr.go:135-247

Event Processing Pipeline ​

Modules integrate with the event processing system by providing event maps and decode functions. The pipeline handles event routing, parsing, and output formatting:

Sources: user/module/imodule.go:267-333, pkg/event_processor/processor.go:66-89, pkg/event_processor/iworker.go:87-94

Module Registration System ​

Modules self-register using a factory pattern with the RegisteFunc() system. This enables dynamic module discovery and instantiation:

Sources: user/module/probe_bash.go:311-320, user/module/probe_openssl.go:782-791, user/module/probe_nspr.go:273-282

Step-by-Step Implementation Guide ​

1. Create Module Structure ​

Create a new file user/module/probe_yourmodule.go with the basic module structure:

type MYourModuleProbe struct {
    Module                    // Embed base module
    bpfManager        *manager.Manager
    bpfManagerOptions manager.Options
    eventFuncMaps     map[*ebpf.Map]event.IEventStruct
    eventMaps         []*ebpf.Map
    // Add module-specific fields here
}

2. Implement Core Interface Methods ​

Implement the required IModule interface methods:

3. Configure eBPF Programs ​

Implement setupManagers() to define probe attachment points and maps:

4. Implement Event Handling ​

Create event structures and decoder mappings in initDecodeFun():

5. Register Module ​

Add registration code at the end of your module file:

func init() {
    RegisteFunc(NewYourModuleProbe)
}

func NewYourModuleProbe() IModule {
    mod := &MYourModuleProbe{}
    mod.name = ModuleNameYourModule
    mod.mType = ProbeTypeUprobe
    return mod
}

Sources: user/module/probe_bash.go:52-63, user/module/probe_bash.go:72-104, user/module/probe_bash.go:243-258

Event Structure Development ​

Create event structures that implement event.IEventStruct to handle data from your eBPF programs:

Sources: user/event/event_bash.go, user/event/event_nspr.go, pkg/event_processor/iworker.go:32-46

Testing and Debugging ​

Use the following approaches to test and debug your new module:

Common Issues and Solutions ​

Sources: user/module/probe_bash.go:65-104, user/module/imodule.go:267-333, pkg/event_processor/processor.go:187-200

This comprehensive guide provides the framework for implementing new capture modules in ecapture. Follow the established patterns and interface requirements to ensure proper integration with the existing system architecture.