Library API - NormB/sipnab GitHub Wiki

sipnab is primarily a CLI/TUI tool. Its analysis engine is also a Rust library on crates.io.

• The curated public API is re-exported at the crate root.
• Anything under a #[doc(hidden)] module (cli, tui, privilege, …) is binary-internal.

The library API is not stable.

• The supported way to use sipnab is the program, cargo install sipnab.
• sipnab releases often.
• Any release, including a patch release, can rename, move or remove a public item.

That matters because of how cargo reads a version.

• A requirement of "0.5" means "any 0.5.x release".
• So cargo update can move your build to a release that no longer compiles against your code.
• Pin the exact release you built against, with =:

[dependencies]
# Replace N with the patch number of the release you tested.
sipnab = { version = "=0.5.N", default-features = false, features = ["native"] }

Then upgrade on purpose:

• change the pin,
• rebuild,
• read the changelog for what moved.

• sipnab::bytes and sipnab::chrono re-export the buffer and timestamp types used in public signatures.
• An application can import sipnab::{bytes::Bytes, chrono::Utc} without adding matching dependency versions.
• After parsing, SipMessage::parse_error reports whether the message was only partially parseable. This includes a truncated declared body.

PcapReader yields the capture file's own records.

• parse_packet decodes a Packet. That is the same frame plus the facts only the caller can supply:
  • the timestamp at full resolution,
  • the captured-vs-wire lengths,
  • the link type. A multi-interface pcapng varies it per packet rather than per file.
• Building that bridge is the one step between a path and a parsed frame:

use sipnab::PcapReader;
use sipnab::capture::Packet;
use sipnab::capture::parse::parse_packet;

fn payload_bytes(path: &str) -> Result<usize, Box<dyn std::error::Error>> {
    let data = std::fs::read(path)?;
    let mut total = 0;

    for pkt in PcapReader::new(&data)? {
        let timestamp = sipnab::chrono::DateTime::from_timestamp(
            pkt.timestamp_secs as i64,
            pkt.timestamp_usecs * 1000,
        )
        .unwrap_or_default();
        let caplen = pkt.data.len();
        let origlen = pkt.orig_len as usize;
        let link_type = pkt.link_type as i32;

        let frame =
            Packet::new(timestamp, pkt.data, caplen, origlen, pkt.interface, link_type);

        // A capture holds frames sipnab does not decode — ARP, a truncated
        // header, an unsupported link type. That is an `Err` per frame, not a
        // failed read: skipping it silently is how a partial result comes to
        // look like a clean one.
        if let Ok(parsed) = parse_packet(&frame) {
            total += parsed.payload.len();
        }
    }

    Ok(total)
}

The parsing and capture entry points return typed, matchable error enums. They do not return anyhow::Result.

• All three are #[non_exhaustive] thiserror enums (std::error::Error).
• So you can propagate them into anyhow/Box<dyn Error> unchanged.
• Or you can match on their variants.

• ParseError — protocol parsers. Variants include Empty { what }, TooShort { what, need, got }, InvalidUtf8 { what }, MissingCrlf, NotSip { line }, InvalidStatusCode { code }, BadRtpVersion { version }, SdpMissingVersion, BadSdpVersion { version }.
• CaptureError — capture-file / packet decode. Variants include TooShort { what, need, got }, UnsupportedLinkType(i32), EncapTooDeep { kind, limit }, NotIp { what }, NoTransport, Icmp, NetMonFormat, UnknownFormat { magic }.
• Error — config/CLI/validation surface. ConfigRead / ConfigParse chain the underlying std::io::Error / toml::de::Error via #[source].

Match on variants rather than message text:

use sipnab::ParseError;
use sipnab::rtp::parser::parse_rtp_header;

match parse_rtp_header(&[0x80, 0x00]) {
    Err(ParseError::TooShort { need, got, .. }) => {
        eprintln!("need {need} bytes, got {got}");
    }
    Ok(header) => { /* use header */ }
    Err(e) => eprintln!("parse failed: {e}"),
}

Every one of these enums is #[non_exhaustive].

• So a downstream match must include a wildcard arm.
• sipnab can add a variant in a minor release without it being a breaking change.
• Twenty-four other public enums carry #[non_exhaustive] for the same reason. Examples are TransportProto, RtcpPacket, FraudType, CipherSuite, ….
• Three public structs carry it too: BurstGapAnalysis, RemoteReceptionReport, RemoteVoipMetrics.
  • A downstream literal therefore cannot construct them.

Four of the seven programs in examples/ take the library path.

• They run against a real capture and print a real answer.
• Each exists because it demonstrates something a doctest on this page structurally cannot: state accumulated across a whole file.

Of the other three:

• uprobe_discover and uprobe_sock_offsets report on the host rather than a capture.
• tls_plaintext_records decodes records laid out the way the BPF TLS probe writes them, as Runnable client examples describes.

cargo run --features native --example call_summary -- tests/pcap-samples/register-invite-reinvite-bye.pcap

One difference bites before any other:

• The binary defaults to --portrange 5060-5061.
• The library applies no port policy at all. Nothing in parse_packet or parse_sip filters by port.
• A capture signaling on 5080 gives:
  • the library twelve SIP messages,
  • the tool "No SIP signaling found" until you pass --portrange 1-65535.
• Neither is wrong. They answer different questions.
• Knowing that is cheaper than rediscovering it against a capture you care about.

The crate is heavily feature-gated (see Cargo.toml).

• For pure parsing you only need native.
• tls, hep, api and mcp pull in their respective subsystems.
• See the feature table in install.md.