Skip to content

Commit 632caf8

Browse files
tattoosonmyskinCopilotclaude
authored
Launch-hygiene pass: docs + metadata only (no logic)
* docs: rename self-assigned CVE IDs to internal JG-ADV advisory format Self-found project issues were labeled CVE-2026-001/002/003. CVEs are issued by CNAs, not projects; the labels read as inflation to a security-literate audience. Rename to internal advisory IDs (JG-ADV-2026-001/002/003, numeric mapping preserved) across all docs, and add a one-line disclaimer at first use in README.md and THREAT_MODEL.md. Docs only; no code/logic touched. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(readme): align headline to validation-status register Title said 'Enterprise Semantic Firewall' while the validation-status section honestly states 'not independently audited or enterprise-GA / research prototype.' That register collision undercuts the project's core intellectual-honesty asset. Retitle to match what the validation section already claims. The Fleet & Enterprise feature-tier section (feature-gated, off by default) is legitimate and left as-is. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: mark bpf/** linguist-vendored so language bar reads Rust-primary Linguist reports ~83% C because of the bpf/*.bpf.c / bpf/lsm/*.c objects, but the project is pitched and built as Rust. Vendor the whole bpf/ tree for language-stat purposes (source stays visible; only Linguist stats change). GitHub re-indexes the language bar on the next push. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: add LAUNCH_CHECKLIST.md tracking launch-hygiene pass Records Tasks A-D (done) and the remaining MANUAL items: re-record demo without recorder overlay, post as native LinkedIn video with repo URL in first comment, warm DM for AFWERX/DIU-adjacent repost. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: renumber socket-LSM fail-open to JG-ADV-2026-004 (resolve ID collision) JG-ADV-2026-003 ambiguously referred to two findings: 'Agent Impersonation via UID Spoofing' (red-team-report.md, disclosed 2026-06-08) and 'socket-LSM fail-open' (THREAT_MODEL/BENCHMARKS-04, surfaced 2026-06-14, Run 04). The newer finding takes the new number: the socket fail-open becomes JG-ADV-2026-004; UID-spoofing keeps JG-ADV-2026-003. CHANGELOG.md has no 003 reference; red-team-report.md already holds 003 for UID-spoofing — both unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: add SECURITY/ADVISORIES.md canonical advisory registry Single source of truth for JG-ADV-* IDs: ID | Title | Component | Disclosed | Status | Fix commit, one row per advisory (001-004), with per-advisory notes. README Known Limitations now points to it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: rename CVE refs to JG-ADV in code comments + script output strings Comment/echo/printf strings only — no logic changed. Maps to the renumbered scheme: interpreter -> JG-ADV-2026-001, path-resolution -> JG-ADV-2026-002, socket fail-open -> JG-ADV-2026-004. Verified no test or script asserts on these literals, so no output contracts break. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(readme): soften line-7 overclaim to defensible wording Replace 'guarantee absolute zero-trust process isolation and immutable anti-replay protection across the entire host subsystem' with 'enforce zero-trust process isolation and anti-replay protection for governed cgroups' — aligns with the cgroup-scoped enforcement described in the validation-status and Known Limitations sections. No new claims. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(checklist): reformat CVE strings as explicit rename record Show the CVE -> JG-ADV mappings as a rename record, including the 003 collision split (socket fail-open renumbered to JG-ADV-2026-004), and point to SECURITY/ADVISORIES.md as the canonical registry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: best-practice consistency cleanups on launch-hygiene flags - README: drop inaccurate 'on AlphaOS' (validated on Debian/Ubuntu/AlmaLinux) - THREAT_MODEL CVE log: reconcile JG-ADV-2026-004 status to 'Fixed (re-validated on AlmaLinux 9 / 5.14, Run 04)' per BENCHMARKS-04 §2 - THREAT_MODEL CVE log: add the missing JG-ADV-2026-003 (UID spoofing) row for parity with SECURITY/ADVISORIES.md - re-align the ASCII box border in validate_m2_path_resolution.sh after the longer JG-ADV identifier (cosmetic) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(bench): add Run 05 — launch-hygiene userspace re-validation Full automated suite + userspace benchmarks re-run on the branch after the docs/comment-only hygiene pass, on the same CPU/distro/kernel as Run 01 (Ryzen 5 7520U / Debian 13 / 6.12). 116/116 green, 0 fail-open in the adversarial suite, P50 259us (vs Run 01's 257us), peak ~6,208 RPS, 0 errors. Kernel Tier 4 not run on this unprivileged sandbox (see Runs 01-04). Confirms the hygiene changes altered nothing operational. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(readme): tighten H1 to 'kernel-enforced semantic firewall'; add C/Rust language-bar note; align qualifier to validation section Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 6b18d24 commit 632caf8

20 files changed

Lines changed: 293 additions & 41 deletions

.gitattributes

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,11 @@ jinn-guard-v1.0-review.zip export-ignore
1414
# Rust-dominant reality) and collapses it in diffs.
1515
bpf/vmlinux.h linguist-vendored
1616
bpf/vmlinux.h linguist-generated
17+
18+
# Jinn Guard is pitched and built as a Rust project; the eBPF/BPF-LSM C objects
19+
# under bpf/ are the in-kernel enforcement layer, but by byte count they dominate
20+
# GitHub's language bar and misrepresent the repo as a C codebase. Mark the whole
21+
# bpf/ tree linguist-vendored so the language bar reflects the Rust-primary
22+
# reality. The source stays in the repo and fully visible — this only affects
23+
# Linguist's stats, and GitHub re-indexes the language bar on the next push.
24+
bpf/** linguist-vendored

BENCHMARKS-03.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ expected-deny); safe mode ran 250 (all expected-allow, audit-only).
9696
## 3. Kernel path resolution (Tier 3 — audit-only)
9797

9898
The LSM hooks loaded in safe mode and resolved **full absolute file paths**
99-
(the CVE-2026-002 fix) on 6.17 — audit-only, nothing blocked. PASS.
99+
(the JG-ADV-2026-002 fix) on 6.17 — audit-only, nothing blocked. PASS.
100100

101101
---
102102

BENCHMARKS-04.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
> Purpose: extend coverage into the **RHEL family** (a third, distinct kernel
88
> lineage) under **SELinux Enforcing**, and validate real eBPF-LSM allow/deny
99
> enforcement there. This run also **found and fixed a real fail-open bug**
10-
> (CVE-2026-003) — see §6 — which is itself the strongest argument that a
10+
> (JG-ADV-2026-004) — see §6 — which is itself the strongest argument that a
1111
> distro-matrix is worth running.
1212
1313
---
@@ -70,15 +70,15 @@ SELinux denial**, enforcing allow/deny in-kernel. Each surface: 500 operations
7070

7171
> **2,750 enforced operations on AlmaLinux 9 / kernel 5.14 under SELinux
7272
> Enforcing: 0 fail-open, 0 incorrect decisions, 0 timeouts***after* the
73-
> CVE-2026-003 fix (§6). The eBPF programs verified and loaded cleanly on a third
73+
> JG-ADV-2026-004 fix (§6). The eBPF programs verified and loaded cleanly on a third
7474
> kernel lineage; SELinux and the BPF-LSM coexisted without interference.
7575
7676
---
7777

7878
## 3. Kernel path resolution (Tier 3 — audit-only)
7979

8080
LSM hooks loaded in safe mode and resolved full absolute file paths
81-
(CVE-2026-002 fix) on 5.14 — audit-only, nothing blocked. PASS.
81+
(JG-ADV-2026-002 fix) on 5.14 — audit-only, nothing blocked. PASS.
8282

8383
---
8484

@@ -175,7 +175,7 @@ Two reads, deliberately kept separate:
175175

176176
---
177177

178-
## 7. What this run found and fixed — CVE-2026-003
178+
## 7. What this run found and fixed — JG-ADV-2026-004
179179

180180
On the **first** armed run, AlmaLinux 9 / 5.14 exposed a **fail-open** in
181181
`socket_connect`: a *variable* fraction (~30–55% under load) of denied TCP
@@ -195,5 +195,5 @@ connects were wrongly allowed, while UDP/exec/file held at 0. Investigation
195195
tripped a fail-open type gate. Fixed by reading the correct width. (This bug
196196
was **latent on every distro** — Debian/Ubuntu merely got zero padding.)
197197

198-
Both fixes landed (CVE-2026-003) and this run is the **post-fix re-validation**:
198+
Both fixes landed (JG-ADV-2026-004) and this run is the **post-fix re-validation**:
199199
`fail_open=0` on every surface. The distro-matrix did exactly its job.

BENCHMARKS-05.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Jinn Guard — Benchmark Run 05
2+
3+
**Test #:** 05 (launch-hygiene re-validation) · **Run date:** 2026-06-19
4+
**Branch:** `chore/launch-hygiene` · **Host:** local dev sandbox (`jinn-dev`)
5+
**See also:** [`BENCHMARKS-01.md`](BENCHMARKS-01.md) · [`BENCHMARKS-02.md`](BENCHMARKS-02.md) · [`BENCHMARKS-03.md`](BENCHMARKS-03.md) · [`BENCHMARKS-04.md`](BENCHMARKS-04.md)
6+
7+
> Purpose: re-run the full **userspace** test + benchmark suite after the
8+
> launch-hygiene pass (advisory-ID rename, README register fix, doc cleanups —
9+
> all docs/comments, **no logic**) to confirm behavior and performance are
10+
> unchanged. This host runs the **same CPU family and kernel** as Run 01
11+
> (AMD Ryzen 5 7520U / Debian 13 / kernel 6.12), so the numbers are directly
12+
> comparable to that baseline.
13+
14+
---
15+
16+
## Environment
17+
18+
| | |
19+
|---|---|
20+
| CPU | **AMD Ryzen 5 7520U** (8 threads, scaling ~83%, max 4.38 GHz) — same model as Run 01 |
21+
| Distribution | **Debian 13** (trixie family) |
22+
| Kernel | **Linux 6.12.90+deb13.1-amd64** |
23+
| RAM | ~5.75 GiB |
24+
| `/tmp` | **tmpfs** — audit log + lineage are CPU-isolated from disk-fsync latency (as in Run 03/04) |
25+
| Toolchain | rustc/cargo **1.95.0**, release profile, clang 19 |
26+
| Privilege | **uid 1000, no `bpftool`** → kernel-LSM Tier 4 (armed allow/deny) **not run here** |
27+
28+
> **Scope note.** Kernel in-kernel allow/deny enforcement (Tier 4) requires root +
29+
> BPF load and is **not** exercised on this unprivileged sandbox. It is already
30+
> validated on three real hosts in [`BENCHMARKS-01..04`](BENCHMARKS-04.md)
31+
> (Debian 6.12, Ubuntu 6.17, AlmaLinux 5.14 — 2,500–2,750 ops, 0 fail-open).
32+
> This run covers the **full automated suite + userspace performance**.
33+
34+
---
35+
36+
## 1. Full automated test suite
37+
38+
`cargo test --workspace --release`:
39+
40+
| Binary | Result |
41+
|---|---|
42+
| `ts_checker` (Z3 SMT) | 4 passed |
43+
| `ts_cli` unit | 87 passed |
44+
| `integration` | 13 passed |
45+
| `swarm_attack` (adversarial) | 12 passed |
46+
| `kernel_lsm` (Tier 4) | 6 **ignored** (env-gated: needs root + BPF) |
47+
48+
> **116 passed · 0 failed · 6 ignored** (122 defined). Identical pass profile to
49+
> Run 04. The launch-hygiene changes did not alter any behavior.
50+
51+
## 2. Attack resistance (adversarial suite)
52+
53+
`swarm_attack`: **12/12 passed, 0 fail-open** — replay storm, signature forgery,
54+
intent injection, quota abuse, anonymous flood, impersonation, path traversal,
55+
forged delegation, bad-protocol, and the all-at-once mixed assault.
56+
57+
---
58+
59+
## 3. Userspace latency & throughput (`cargo bench --bench stress_bench`)
60+
61+
### Single-client latency (10,000 sequential, full decision pipeline)
62+
63+
| Percentile | Run 05 (Ryzen 5 7520U) | Run 01 baseline (same CPU) |
64+
|---|---|---|
65+
| P50 | **259 µs** | 257 µs |
66+
| P75 | 304 µs ||
67+
| P90 | 435 µs ||
68+
| P95 | **533 µs** | 366 µs |
69+
| P99 | **782 µs** | 463 µs |
70+
| P99.9 | 1,243 µs ||
71+
| Max | 2,962 µs | 1,900 µs |
72+
| Single-client RPS | **~3,219** | ~3,640 |
73+
74+
> P50 matches Run 01 to within noise (259 vs 257 µs). Tail percentiles (P95/P99)
75+
> are higher here — this is a **shared, non-CPU-isolated sandbox** at ~83% scaling,
76+
> not a dedicated host, so tail latency is noisier. The median (the pipeline's
77+
> real cost) is unchanged.
78+
79+
### Concurrent throughput (tmpfs `/tmp`; 0 errors at every level)
80+
81+
| Agents | Total RPS | P50 | P95 | Errors |
82+
|---|---:|---:|---:|---:|
83+
| 10 | **6,208** | 1,220 µs | 1,874 µs | 0 |
84+
| 50 | 6,055 | 1,220 µs | 2,432 µs | 0 |
85+
| 100 | 6,159 | 1,233 µs | 2,535 µs | 0 |
86+
| 500 | 5,741 | 1,252 µs | 37,107 µs | 0 |
87+
88+
> Peak **~6,208 RPS**, flat to 100 concurrent agents, **0 errors** throughout.
89+
> At 500 agents throughput holds but the P95 tail balloons (scheduling
90+
> congestion on 8 threads) — consistent with Run 01 (~6,500 peak).
91+
92+
### Mixed allow/deny (70/30)
93+
94+
5,000 requests → **3,500 allow / 1,500 deny classified correctly, 0
95+
misclassifications** (~3,517 RPS).
96+
97+
### Saturation sweep
98+
99+
| Threads | RPS | P99 |
100+
|---|---:|---:|
101+
| 2 | 4,556 | 1 ms |
102+
| 4 | 4,809 | 1 ms |
103+
| 8 | 5,111 | 2 ms |
104+
| 16 | 4,781 | 5 ms |
105+
| 32 | 4,888 | 9 ms |
106+
| 64 | **saturated** (P99 > 10 ms) ||
107+
108+
---
109+
110+
## 4. Component micro-benchmarks (criterion)
111+
112+
| Path | Median | Throughput |
113+
|---|---:|---:|
114+
| Core decision pipeline (in-process) | **73.2 µs** | ~13.6 K/s |
115+
| UDS framed roundtrip (persistent conn) | **16.2 µs** | ~61.6 K/s |
116+
| End-to-end serial roundtrip (new conn/request) | **151.1 µs** | ~6.6 K/s |
117+
118+
> The UDS transport (~16 µs) is a small fraction of the full decision (~73 µs+);
119+
> the pipeline, not the socket, dominates. *(The persistent-connection case in
120+
> `socket_throughput` hit a `BrokenPipe` in the bench harness mid-run — a
121+
> harness-robustness quirk, not a daemon fault; the e2e new-connection figure
122+
> above completed cleanly.)*
123+
124+
---
125+
126+
## 5. Scope & honesty notes
127+
128+
- Userspace only; **kernel Tier 4 not run on this unprivileged sandbox** — see
129+
Runs 01–04 for live in-kernel enforcement.
130+
- Shared sandbox at ~83% CPU scaling: treat **P50/medians** as representative and
131+
**tails** as noisier than a dedicated host would show.
132+
- Still a validated research prototype / controlled-pilot MVP, not independently
133+
audited. See [`THREAT_MODEL.md`](THREAT_MODEL.md) and
134+
[`SECURITY/ADVISORIES.md`](SECURITY/ADVISORIES.md).
135+
136+
**Bottom line:** post-launch-hygiene, the suite is **116/116 green (0 fail-open
137+
in the adversarial suite)** and userspace performance is in line with the Run 01
138+
baseline on identical silicon — confirming the docs/comment-only hygiene pass
139+
changed nothing operational.

CHANGELOG.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,10 @@ Linux 6.12 host across all four validation tiers.
124124
log, and disclosed residual risks.
125125

126126
### Fixed
127-
- **CVE-2026-002 (Critical) — filesystem policy bypass via relative paths.**
127+
- **JG-ADV-2026-002 (Critical) — filesystem policy bypass via relative paths.**
128128
Kernel now resolves the full absolute path before the denylist check
129129
(`jg_read_dentry_path`, depth-12 dentry walk). Verified audit-only and armed.
130-
- **CVE-2026-001 (High) — execve bypass via interpreter chains.** Governed agents
130+
- **JG-ADV-2026-001 (High) — execve bypass via interpreter chains.** Governed agents
131131
are denied known interpreters (`DENY_INTERPRETER_NOT_ALLOWED`).
132132
- **Fail-open regression (enterprise18).** The `system_immunity` and
133133
"out-of-scope" ALLOW fast-paths ran *before* the gate chain, letting

LAUNCH_CHECKLIST.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Launch Checklist
2+
3+
Hygiene pass before the first distribution push to a security-literate audience
4+
(r/netsec, HN, AFWERX/DIU-adjacent). The repo's intellectual-honesty framing
5+
(validation-status section, `THREAT_MODEL.md`, "what it does NOT claim") is the
6+
core asset — everything here aligns the rest of the repo up to that bar.
7+
8+
## Automated pass (branch `chore/launch-hygiene`)
9+
10+
- [x] **A — Kill self-assigned CVE identifiers.** Renamed project-assigned CVE
11+
identifiers to internal `JG-ADV-*` advisory IDs across docs and (in the
12+
follow-up pass) code comments + script output strings. Rename record:
13+
- `CVE-2026-001` -> `JG-ADV-2026-001` (execve interpreter-chain bypass)
14+
- `CVE-2026-002` -> `JG-ADV-2026-002` (filesystem relative-path bypass)
15+
- `CVE-2026-003` -> `JG-ADV-2026-003` (agent impersonation / UID spoofing)
16+
- `CVE-2026-003` -> `JG-ADV-2026-004` (socket-LSM fail-open — renumbered to
17+
resolve the duplicate-`003` collision; the newer finding takes the new
18+
number)
19+
20+
A one-line disclaimer was added at first use in `README.md` and
21+
`THREAT_MODEL.md` ("`JG-ADV-*` are internal, self-identified advisory IDs,
22+
not CVE records issued by a CNA"). Canonical registry:
23+
[`SECURITY/ADVISORIES.md`](SECURITY/ADVISORIES.md).
24+
- [x] **B — Fix the register collision.** Retitled the README headline from
25+
"Enterprise Semantic Firewall" to "Kernel-level enforcement firewall for
26+
autonomous AI agents (research prototype)" to match the validation-status
27+
section. The Fleet & Enterprise feature-tier section (feature-gated, off by
28+
default) is legitimate and left as-is.
29+
- [x] **C — Repo metadata.** About/description + topics command prepared (run
30+
manually — `gh` not available in the working environment; exact command in
31+
the PR summary).
32+
- [x] **D — Fix the language bar.** Marked `bpf/**` `linguist-vendored` in
33+
`.gitattributes` so the language bar reads Rust-primary. GitHub re-indexes
34+
on the next push.
35+
36+
## Manual (human, not agent)
37+
38+
- [ ] **MANUAL** — Re-record demo: screen-recorder window must never overlay
39+
terminal content (currently covers the open and the closing thesis card).
40+
- [ ] **MANUAL** — Post demo as a **native LinkedIn video** (uploaded, not a
41+
link). Put the repo URL in the **first comment**, not the post body.
42+
- [ ] **MANUAL** — Warm DM to a named contact for a repost into the
43+
AFWERX/DIU-adjacent network.

OWASP-MAPPING.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,9 @@ can cause.
7979
An agent generates, modifies, or runs code/commands unsafely.
8080
The kernel `bprm_check_security` LSM hook denies execution of non-allowlisted
8181
binaries for governed agents, with interpreter-chain mitigation
82-
(CVE-2026-001, `DENY_INTERPRETER_NOT_ALLOWED`). Enforcement is in the kernel and
82+
(JG-ADV-2026-001, `DENY_INTERPRETER_NOT_ALLOWED`). Enforcement is in the kernel and
8383
cannot be bypassed by the agent process.
84-
*Evidence:* `bpf/lsm/jg_bprm_check_security.c`; `CHANGELOG.md` (CVE-2026-001);
84+
*Evidence:* `bpf/lsm/jg_bprm_check_security.c`; `CHANGELOG.md` (JG-ADV-2026-001);
8585
Tier-4 armed validation.
8686

8787
### ASI06 — Memory and Context Poisoning · **Out of scope**

PROFESSOR_VALIDATION.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ then prints a PASS/SKIP/FAIL summary. Skipped tiers tell you what they need.
4343
|------|----------------|--------------|------------------|
4444
| **1. Build + tests** | The full automated suite passes (≈117 tests: Z3 engine, governance pipeline, 13 integration, 12 swarm-attack). | Rust (`cargo`) | No |
4545
| **2. Mandatory mediation** | A maximally-locked agent container (no network, read-only FS, all capabilities dropped, seccomp, socket-only) **cannot** act directly; only broker-mediated actions through Jinn Guard succeed. | Docker | No (containers) |
46-
| **3. Kernel path resolution** | The eBPF-LSM hooks load and resolve **full file paths** in the kernel (the CVE-2026-002 fix), in **audit-only** mode. | root + BPF-LSM + clang | **No** (audit-only) |
46+
| **3. Kernel path resolution** | The eBPF-LSM hooks load and resolve **full file paths** in the kernel (the JG-ADV-2026-002 fix), in **audit-only** mode. | root + BPF-LSM + clang | **No** (audit-only) |
4747
| **4. Kernel enforcement** | Real allow/deny across execve, TCP, UDP, file create, and file unlink. | root + `--arm` + cgroup v2 | **Only inside a dedicated test cgroup** — see below |
4848

4949
---
@@ -117,7 +117,7 @@ denied operation was actually denied, and every allowed operation succeeded.
117117
security-critical cases — resolve to full absolute paths.
118118
- **Interpreter chains.** An agent explicitly allowed to run an interpreter can
119119
invoke other tools through it; Jinn Guard denies interpreters by policy for
120-
governed agents (CVE-2026-001 mitigation), but per-binary execve limits are
120+
governed agents (JG-ADV-2026-001 mitigation), but per-binary execve limits are
121121
only as strong as the allowlist.
122122
- **Not independently audited; single-distribution validated (Debian).**
123123

README.md

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# 🛡️ Jinn Guard — Enterprise Semantic Firewall
1+
# 🛡️ Jinn Guard — Kernel-enforced semantic firewall for autonomous AI agents (validated research prototype)
22

33
[![CI](https://github.com/AlphaReasoning/The-Jinn-Guard/actions/workflows/ci.yml/badge.svg)](https://github.com/AlphaReasoning/The-Jinn-Guard/actions/workflows/ci.yml)
44

55
**Jinn Guard** is an asynchronous, kernel-aware semantic firewall designed to enforce mathematical safety constraints on autonomous AI agents before any tool execution is permitted. It intercepts high-level natural language intents and processes them through a lifetime-anchored **Z3 SMT solver pipeline** — verifying state transitions and risk ceilings against formalized compliance models before granting or denying execution authority.
66

7-
Operating locally over high-throughput **UNIX domain sockets** on AlphaOS, the platform binds user-space proxy validation with low-level **eBPF kernel telemetry** and namespace tracking to guarantee absolute zero-trust process isolation and immutable anti-replay protection across the entire host subsystem.
7+
Operating locally over high-throughput **UNIX domain sockets**, the platform binds user-space proxy validation with low-level **eBPF kernel telemetry** and namespace tracking to enforce zero-trust process isolation and anti-replay protection for governed cgroups.
88

99
> ### ▶️ See it live in 5 minutes
1010
> ```bash
@@ -170,6 +170,12 @@ Kernel Layer (eBPF)
170170
└─→ governance loop (telemetry feed)
171171
```
172172
173+
> **A note on languages.** The probes in `bpf/` are C — small, separately-compiled
174+
> eBPF programs loaded into the kernel. The governance core (the daemon, the Z3
175+
> verification pipeline, the policy engine, and the CLI) is **Rust**, under `ts_cli/`.
176+
> `bpf/**` is marked `linguist-vendored`, so GitHub's language bar reflects the Rust
177+
> core rather than the volume of low-level kernel C.
178+
173179
---
174180
175181
## 📦 Components
@@ -246,7 +252,11 @@ Validated on three distributions / three kernel generations: **Debian 13 / kerne
246252
247253
## Known Limitations
248254
249-
### Filesystem path resolution — mount boundaries (was CVE-2026-002, now fixed)
255+
> **Advisory registry:** the canonical list of `JG-ADV-*` IDs, status, and fix commits lives in [`SECURITY/ADVISORIES.md`](SECURITY/ADVISORIES.md).
256+
>
257+
> **Note on identifiers:** `JG-ADV-*` are internal, self-identified advisory IDs, not CVE records issued by a CNA.
258+
259+
### Filesystem path resolution — mount boundaries (was JG-ADV-2026-002, now fixed)
250260
251261
The BPF `inode_create`/`inode_unlink` hooks now resolve the **full absolute
252262
path** of a file operation in the kernel (a bounded `d_parent` walk), closing the
@@ -260,7 +270,7 @@ on a single-root install) — the security-critical cases — resolve to full
260270
absolute paths. Crossing mount boundaries requires path-family LSM hooks or
261271
`bpf_d_path` and is tracked for a future release.
262272
263-
### Interpreter chains (CVE-2026-001, mitigated)
273+
### Interpreter chains (JG-ADV-2026-001, mitigated)
264274
265275
An agent explicitly allowed to run an interpreter can invoke other tools through
266276
it. Jinn Guard denies known interpreters by policy for governed agents (any

0 commit comments

Comments
 (0)