智能防火墙

System Requirements

- Linux kernel 5.16+ - CONFIG_BPF_LSM=y - bpf present in the active LSM list (cat /sys/kernel/security/lsm) - Debian cloud kernels often have it pre-armed. - Ubuntu does not — append bpf to the existing list via the lsm= boot parameter, then update-grub and reboot. For example, in /etc/default/grub:

    GRUB_CMDLINE_LINUX="lsm=lockdown,capability,landlock,yama,apparmor,ima,evm,bpf"
    

    sudo deploy/arm-lsm-ostree.sh
    sudo systemctl reboot
    

Validated on three distributions / three kernel generations: Debian 13 / kernel 6.12 (BENCHMARKS-01.md, BENCHMARKS-02.md), Ubuntu 24.04 / kernel 6.17 (BENCHMARKS-03.md), and AlmaLinux 9 / kernel 5.14 under SELinux Enforcing (BENCHMARKS-04.md).

---

Prerequisites

```bash

Prerequisites (Debian)

sudo apt install clang llvm libbpf-dev linux-headers-$(uname -r) bpftool

Install (automated)

git clone https://github.com/AlphaReasoning/The-Jinn-Guard
cd The-Jinn-Guard
sudo ./deploy/install.sh

The installer will: 1. Create the jinnguard system user 2. Generate a 256-bit HMAC secret → /etc/jinnguard/secret 3. Load the key into the kernel keyring 4. Build and install /usr/sbin/jinnguard 5. Enable and start jinnguard.service

🧬 Building eBPF Programs

```bash

sudo apt install clang llvm libbpf-dev linux-headers-$(uname -r) linux-tools-generic

Build all four programs and merge into jinnguard_ebpf.o

cd bpf && make

Install to /usr/lib/jinnguard/

sudo make install ```

The merged object is loaded at runtime by the aya-rs backend inside the daemon when built with the kernel_telemetry feature.

---

Check without building

cargo check ```

---

🚀 Quick Start

Python client example

from jinnguard_py import JinnGuardClient

client = JinnGuardClient(
    socket_path="/run/jinnguard/jinnguard.sock",
    secret_key="<your-hmac-secret>",  # or use keyring lookup
    agent_id="fabric_swarm_production_01",
)

result = client.propose(
    intent_name="read_file",
    sequence_counter=1,
    action_risk_score=20.0,
    proposed_action={"kind": "file_write", "path": "/tmp/out.txt", "contents": "hello"},
    context_vars={"spending_ceiling_usd": 50.0},
)

if result.allowed:
    print("Execution permitted:", result.signal)
else:
    print("Blocked:", result.signal)

---

Rust Sandbox / Dev Environment

This repository includes a reproducible Rust sandbox for development, CI-style builds, and Step 1 capability-broker testing. It installs Rust/Cargo, native Z3, SQLite/OpenSSL headers, Python 3, and Clang/LLVM in a Docker image.

make docker-build
make dev-shell
make docker-smoke

For the full workflow, see docs/rust_sandbox.md. If the sandbox MCP gateway port is busy, set JINN_GUARD_MCP_PORT, for example:

JINN_GUARD_MCP_PORT=4860 make smoke

⚙️ Configuration — `policy.yaml`

global_safety_ceiling: 75.0   # fused_risk must be below this

agent_nodes:
  - id: fabric_swarm_production_01
    privilege_tier: 1
    # Optional: bind this signed agent_id to local Unix users observed through
    # SO_PEERCRED. Empty/omitted preserves the shared-key legacy behavior.
    allowed_peer_uids:
      - 10001
    allowed_intents:
      - read_file
      - model_inference
      - write_temp
    max_sequence_quota: 500    # max decisions per lineage session (0 = unlimited)
    invariants:
      - "spending_ceiling_usd <= 150.00"
      - "privilege_escalation_depth < 3"
      - "fused_risk <= 74.0"

  - id: admin_agent_00
    privilege_tier: 3
    allowed_intents: []        # empty = all intents allowed
    max_sequence_quota: 0      # 0 = unlimited
    invariants:
      - "trust_score >= 30.0"

🔧 CLI Flags

jinnguard [OPTIONS]

Options:
  --socket-path   <PATH>   UDS socket path  [default: /run/jinnguard/jinnguard.sock]
  --lineage-file  <PATH>   Lineage persistence file  [default: /var/lib/jinnguard/lineage.json]
  --audit-log     <PATH>   Audit log path  [default: /var/log/jinnguard/audit.log]
  --policy-file   <PATH>   Policy YAML  [default: /etc/jinnguard/policy.yaml]
  -h, --help               Print help

---

📦 Components

---

Ubuntu only: bpftool ships inside linux-tools (no standalone package)

sudo apt install linux-tools-generic # provides bpftool for vmlinux.h generation

On Ubuntu, bpftool comes from linux-tools-generic instead of a `bpftool` package:

Run the full suite (122 tests: 4 Z3 + 93 unit + 13 integration + 12 swarm-attack)

cargo test

✅ Shippable components