nsave Network Packet Capture Tool

Expert guidance for working with nsave, a high-performance network packet capture and storage tool written in Rust that efficiently captures network traffic and saves it to disk with advanced querying capabilities.

What This Skill Does

This skill provides comprehensive guidance for developing, building, testing, and maintaining the nsave packet capture tool. It covers the multi-crate architecture (main application, eBPF programs, common utilities), packet capture mechanisms (AF_XDP with eBPF, PCAP fallback), storage system (chunk-based, time-indexed), flow management, and CLI tooling.

Instructions

When working with the nsave codebase, follow these guidelines:

1. Understanding the Architecture

Before making changes, understand the system architecture:

**Key data structures to be familiar with**:

2. Build and Development Commands

**Standard development build**:

```bash

cargo build

```

**Build with debug features**:

```bash

cargo build --features debug_mode

```

**Run tests**:

```bash

All tests

cargo test

Specific module

cargo test --package nsave mmapbuf

With output

cargo test -- --nocapture

eBPF tests

cargo test --package ebpf

```

**Code quality checks**:

```bash

Format check

cargo fmt --check

Linting

cargo clippy --tests

```

3. Running the Application

**Start packet capture daemon** (requires root):

```bash

cargo run --bin nsave --config 'target."cfg(all())".runner="sudo -E"'

```

**CLI query examples**:

5-tuple search:

```bash

nsave-cli search -s 2024-03-28-12:00:00 -e 2024-03-28-22:00:00 --sip 192.168.1.1 -D 192.168.1.2 -P tcp

```

BPF filter search:

```bash

nsave-cli bpf_search -s 2024-07-28-21:10:00 -e 2024-07-28-21:15:00 --bpf "tcp or udp"

```

Export to pcap:

```bash

nsave-cli search -s 2024-05-18-15:36:36 -e 2024-05-18-15:36:47 --sip 10.11.20.255 -D 10.11.20.14 -P udp -f ~/dump.pcap

```

4. Configuration Management

The tool requires a TOML configuration file (`.nsave_conf.toml` in home directory). Key sections:

Configuration is handled in `configure.rs` with validation.

5. Making Code Changes

**CRITICAL**: Before implementing any changes:

1. **List all modification points**: Create a detailed list of every file and function that needs to be modified

2. **Wait for approval**: Present the modification plan and wait for user confirmation

3. **Implement incrementally**: After approval, ask for confirmation before modifying each item

4. **Test thoroughly**: Run relevant tests after each change

**Example workflow**:

```

User: "Add support for filtering by port range"

You: "I need to modify the following components:

1. nsave/src/cli/main.rs - Add port range arguments

2. nsave/src/flow.rs - Update PacketKey matching logic

3. nsave/src/store.rs - Modify query function

4. nsave/src/bin/cli/main.rs - Update CLI parsing

Should I proceed with these changes?"

[Wait for approval]

You: "Starting with 1/4: Modifying nsave/src/cli/main.rs to add --sport-range and --dport-range arguments. Proceed?"

[Continue incrementally after each approval]

```

6. Key Module Locations

**Entry points**:

**Core modules**:

7. eBPF Integration

The eBPF integration requires special attention:

8. Platform Compatibility

**Requirements**:

9. Error Handling Patterns

Follow the existing error handling conventions:

10. Testing Strategy

When adding new features:

1. Write unit tests for individual functions

2. Add integration tests for component interactions

3. Test both AF_XDP and PCAP code paths when applicable

4. Verify cleanup and error handling paths

5. Test with various configuration options

Important Notes

Example Usage Scenarios

**Scenario 1**: Adding a new CLI search filter

1. List modifications: CLI argument parsing, query logic, index lookup

2. Get approval for plan

3. Implement argument parsing in `cli/main.rs`

4. Update query function in `store.rs`

5. Add tests for new filter

6. Test with real packet capture

**Scenario 2**: Optimizing storage performance

1. Profile current performance to identify bottleneck

2. List affected modules (likely `store.rs`, `mmapbuf.rs`, `chunkindex.rs`)

3. Get approval for optimization approach

4. Implement changes incrementally

5. Benchmark before/after performance

6. Verify correctness with existing tests

**Scenario 3**: Adding new eBPF filtering capability

1. List changes: eBPF program (`ebpf/src/main.rs`), capture layer (`capture.rs`)

2. Get approval

3. Modify eBPF program with new filter logic

4. Update Rust integration code

5. Test build process (eBPF compilation)

6. Verify packet filtering behavior