← IklwaLabs/sentinel

Sentinelv0.1.0

Sentinel watches the traffic on your machine, reconstructs the connections that carry it, stores what it finds in a local database, and tells you what is happening. No account, no cloud service, nothing leaves the machine.

capture → decode → flow engine → SQLite → interface

No published build yet.

No GitHub release exists yet for v0.1.0. Tagging the repository starts the build matrix; the artifacts appear here once the release job has published them.

Windows

Supported

NSIS installer and MSI for x86-64. Captures from any adapter Npcap exposes, including a dedicated loopback adapter when Npcap is installed in full mode.

Downloads

NSIS installer — not yet publishedSentinel-0.1.0-windows-x64-setup.exeRecommended. Installs and adds a Start menu entry.
MSI package — not yet publishedSentinel-0.1.0-windows-x64.msiFor managed deployment.
Command line interface — not yet publishedsentinel-cli-0.1.0-windows-x64.exeSingle binary. No installer.

Requirements

Capture driver
Npcap
Privileges
Run as Administrator. Reading frames needs an elevated token; Sentinel reports this through 'sentinel doctor' rather than failing at capture time.

Installing

  1. Install Npcap from npcap.com first. It is the capture driver; the installer does not bundle it.
  2. Run Sentinel-0.1.0-windows-x64-setup.exe. The MSI is there if you prefer Windows Installer.
  3. Launch Sentinel from the Start menu and choose an interface in the sidebar.

Linux

Supported

Debian package and AppImage for x86-64. Loopback capture is supported directly, so local traffic between processes on the machine is visible.

Downloads

Debian package — not yet publishedSentinel-0.1.0-linux-x86_64.debx86-64. Installs the CLI to /usr/bin.
AppImage — not yet publishedSentinel-0.1.0-linux-x86_64.AppImageNo install step. chmod +x, then run.
Command line interface — not yet publishedsentinel-cli-0.1.0-linux-x86_64Single static binary.

Requirements

Capture driver
libpcap
Privileges
Grant the binary CAP_NET_RAW rather than running everything as root: sudo setcap cap_net_raw,cap_net_admin=eip /path/to/sentinel

Installing

  1. sudo dpkg -i Sentinel-0.1.0-linux-x86_64.deb
  2. or make the AppImage executable and run it: chmod +x Sentinel-0.1.0-linux-x86_64.AppImage
  3. sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/sentinel # instead of running as root
  4. Run 'sentinel doctor' to confirm capture is possible in your session.

macOS

Supported

Disk image and application bundle, universal (Apple silicon and Intel). Unsigned: Gatekeeper refuses to open it until the quarantine attribute is cleared.

Downloads

Disk image — not yet publishedSentinel-0.1.0-macos-universal.dmgUniversal binary. Unsigned.
Application bundle — not yet publishedSentinel-0.1.0-macos-universal.zipFor moving it between machines without a disk image.
Command line interface — not yet publishedsentinel-cli-0.1.0-macos-universalSingle binary.

Requirements

Capture driver
BPF framework (built in)
Privileges
The process must belong to the access_bpcap group, or run with sudo. An administrator has to arrange this.

Installing

  1. Open Sentinel-0.1.0-macos-universal.dmg and drag Sentinel to Applications.
  2. The bundle is not notarised. Right-click it and choose Open, or clear the quarantine flag:
  3. xattr -d com.apple.quarantine /Applications/Sentinel.app
  4. Capture additionally needs access_bpcap membership, which an administrator grants.

Android

Analysis only

Analysis only. The APK lists interfaces and analyses PCAP files offline. Live capture is not implemented and the build reports it as unavailable instead of failing at runtime.

Downloads

APK — not yet publishedSentinel-0.1.0-android.apkSideload. Offline PCAP analysis only; no live capture.

Requirements

Capture driver
Tun2Socks (not implemented)
Privileges
None. Android grants no capture privileges to an ordinary app.

Installing

  1. Enable developer mode and USB debugging on the device.
  2. Sideload Sentinel-0.1.0-android.apk with adb install, or from the device's file manager.
  3. Open a PCAP file from local storage to analyse it. Live capture is not available.

What it does

  • Enumerates real capture interfaces

    Through Npcap on Windows, libpcap on Linux and macOS. Wired, wireless, loopback, tunnel and virtual adapters are classified, and an adapter that cannot be captured says why instead of being offered.

  • Captures live traffic

    From a selected adapter, on a dedicated thread, with backpressure that is counted rather than hidden. An ingress queue that overflows is visible in the interface.

  • Decodes L2 to L4 itself

    Ethernet, VLAN, IPv4, IPv6, ARP, TCP, UDP and ICMP through an own bounds-checked decoder, so truncation and IP fragmentation are handled explicitly rather than guessed at.

  • Reconstructs bidirectional flows

    Keyed on a canonically ordered endpoint pair with initiator detection from port roles, so a connection appears once with both directions attributed correctly.

  • Analyses PCAP files through the same pipeline

    Offline results match live capture exactly, because there is one decoder and one flow engine behind both.

  • Reports incomplete data as incomplete

    Packet loss is tracked separately for the driver, the ingress queue and the decoder, and every surface says which of the three lost frames.

  • Stores everything in SQLite, locally

    One batched writer thread, append-only migrations, configurable retention. There is no code path that opens an outbound connection.

Not in this release

These are absent from the interface rather than faked. A threat rule that cannot fire would be worse than an honest gap.

  • Threat rules. No detection engine ships in this release. The rule model and its evaluation contract are designed in docs/DETECTION_ENGINE.md, but presenting a rule that cannot fire would be worse than showing nothing.
  • Process attribution. Sentinel reports which process owns a connection only where the platform exposes it without a kernel driver. Nothing is guessed from port numbers.
  • Device inventory. There is no list of devices on the network. Sentinel observes this machine's traffic, not the topology around it.
  • DNS correlation. DNS queries are decoded and shown as flows. They are not resolved into hostnames or joined against other traffic yet.

Command line

The CLI is a thin client over the same engine as the desktop application, so the two cannot disagree about what your network is doing.

CommandPurpose
sentinel interfacesList capture interfaces and whether each one is ready.
sentinel doctorReport whether capture is possible in this process, and what to do when it is not.
sentinel capture --duration 30Capture live traffic for a fixed window.
sentinel statusWhat the current session is doing.
sentinel analyze capture.pcapAnalyse a PCAP file offline, no privileges needed.
sentinel export flows.csvExport stored flows as CSV or JSON.
sentinel pruneApply retention now, with --dry-run to see what would go.
sentinel versionVersion, schema and platform.

Add --json for machine-readable output, -v for more detail, -q for less.

Verify a download

Every platform's artifact set includes a SHA256SUMS.txt. Compare it before running anything:

sha256sum -c SHA256SUMS.txt
  • Artifacts are served over TLS from the GitHub release, so the checksum is a check against tampering in transit, not against a compromised account.
  • macOS artifacts are unsigned. That is why the checksum matters more there than elsewhere.

Questions

→Does anything leave my machine?

No. There is no code path in Sentinel that opens an outbound connection. The database is a local SQLite file, and the interface is local. SECURITY.md documents this and the reasoning behind it.

→Why does capture fail on Windows until I run as Administrator?

Reading frames needs an elevated token. Sentinel reports 'notElevated' through 'sentinel doctor' before you start a session, rather than failing later with a driver error code.

→Why is the macOS build unsigned?

Notarisation needs an Apple developer account. Until there is one, right-click the app and choose Open, or clear the quarantine attribute. The SHA256SUMS.txt file lets you verify the download first.

→Can the Android build capture live traffic?

No. It needs a userspace TCP/IP stack over an app-owned VPN slot, which is not implemented. The APK analyses PCAP files and lists interfaces, and reports live capture as unavailable rather than pretending.

→Where is my data stored?

In a SQLite database under your platform's application-data directory, named by sentinel-platform so each platform uses its own conventions. 'sentinel version' reports the schema version.

→Does it detect threats?

Not in this release. The product is named for it and the roadmap commits to it, but v0.1.0 ships the capture-to-storage pipeline and none of the rules. docs/DETECTION_ENGINE.md explains the design.

Build from source

Rust 1.95 or newer, Node.js 20 or newer, and a capture driver: Npcap with its SDK on Windows, libpcap-dev on Linux, nothing on macOS.

git clone https://github.com/IklwaLabs/assegai-sentinel.git
cd assegai-sentinel
cargo build --release
cargo test
cargo build --release -p sentinel-desktop --features custom-protocol
cd apps/desktop/frontend && npm install && npm run build
  • The custom-protocol feature is not optional. Without it the desktop binary looks for the Vite dev server instead of the assets embedded in the executable, and opens a black window.
  • The repository is private. You need an invitation from IklwaLabs to clone it.
  • docs/Sentinel-Reference.pdf is the whole product in one document: architecture, how to run it, how to control it, troubleshooting.

https://github.com/IklwaLabs/assegai-sentinel

IklwaLabs · Apache-2.0 licensed · source