# Kernel Shield Three-Layer Security Enforcement Architecture in ClosedClaw

> Explore Kernel Shield's three-layer security architecture: Structural Enforcement, Semantic Filtering, and Neural Attestation. Learn how it protects your system before OS execution.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: architecture
- Published: 2026-02-25

---

**Kernel Shield implements a deterministic three-layer security enforcement architecture—Structural Enforcement, Semantic Filtering, and Neural Attestation—that evaluates every tool call against manifest declarations, risk vectors, and behavioral fingerprints before operating system execution.**

Kernel Shield serves as the core security arbiter in the ClosedClaw project, providing a robust three-layer security enforcement architecture that intercepts every tool invocation. This defense-in-depth model ensures that function calls undergo rigorous validation against declared capabilities, probabilistic risk thresholds, and neural activation patterns before reaching the operating system.

## The Three-Layer Defense Model

Kernel Shield processes every tool call through three sequential enforcement layers defined in [`src/agents/clawtalk/kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/clawtalk/kernel-shield.ts). The strictest action from any layer wins, following the enforcement hierarchy: **block** takes precedence over **require-biometric**, which takes precedence over **log**, which takes precedence over **allow**.

### Layer 1: Structural Enforcement (The Formal Gate)

The first layer validates tool calls against declared capabilities through the `checkStructural` function (lines 9-33 in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts)). This **Structural Enforcement** layer performs two critical validations:

- **Manifest compliance**: Verifies that the requested tool name exists in the skill's `.claws` manifest capability set
- **Formal verification proofs**: Cryptographically validates optional proofs accompanying high-risk operations

If the tool is not listed in the manifest or the proof verification fails, this layer returns an immediate **block** verdict, preventing unauthorized capability access.

### Layer 2: Semantic Filtering (The Risk Vector)

The second layer computes dynamic risk assessments through the `computeRiskVector` function (lines 38-66 in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts)). This **Semantic Filtering** layer calculates the risk vector `Vr` using the formula:

```

Vr = (P_access × S_data) + (1 - T_score)

```

The components are:
- **P_access**: The tool's inherent access probability from the static `TOOL_PROFILES` table
- **S_data**: The sensitivity rating of the data being accessed
- **T_score**: The current session trust score, which increases with successful operations and decreases with failures

Based on configurable low, medium, and high thresholds, this layer returns **allow**, **log**, or **require-biometric** verdicts, enabling context-aware security decisions that adapt to session behavior.

### Layer 3: Neural Attestation (The Behavioral Anchor)

The third layer detects behavioral drift through the `checkAttestation` function (lines 73-105 in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts)). This **Neural Attestation** layer compares the LLM's current activation vector against a stored **neural fingerprint** using cosine similarity:

- **Neural fingerprint**: A comma-separated list of floats (`neuralDigest`) stored in the skill metadata (Block 9)
- **Soft drift threshold** (default 0.96): Triggers logging when cosine similarity drops below this value
- **Hard drift threshold** (default 0.88): Triggers blocking when similarity drops below this value

This layer ensures that compromised, fine-tuned, or drifted models are detected before they execute sensitive operations.

## Integration Flow and Enforcement Modes

The three-layer security enforcement architecture integrates into the ClosedClaw runtime through `kernelShieldBeforeToolCallHandler`, registered in [`src/plugins/loader.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/plugins/loader.ts). The execution flow follows these steps:

1. **Tool-call hook**: Every tool invocation triggers the handler, which builds a `ToolInvocationContext` using the static `TOOL_PROFILES` table
2. **Data retrieval**: Fetches the appropriate skill manifest, optional verification proof, and neural fingerprint (if attestation is enabled)
3. **Layer evaluation**: Executes all three layers via `evaluateShield` in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts)
4. **Verdict application**: Applies the resulting `ShieldVerdict` according to the configured enforcement mode

### Enforcement Modes

Configuration resides in [`src/config/types.security.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/config/types.security.ts) and can be updated at runtime via `updateKernelShieldConfig`:

| Mode | Behavior |
|------|----------|
| **strict** | Any non-allow verdict immediately blocks the call |
| **permissive** | Verdicts are logged; only explicit `block` actions stop execution |
| **audit-only** | All calls proceed; the verdict is merely recorded for analysis |

## Key Architectural Concepts

Understanding Kernel Shield's three-layer security enforcement requires familiarity with these core concepts:

**Manifest-driven permissions** — The `.claws` files declare which capabilities a skill may invoke. Layer 1 enforces this list strictly via `checkStructural`, ensuring tools cannot exceed their declared authority.

**Risk Vector (`Vr`)** — This composite metric blends the tool's inherent risk (`P_access` × `S_data`) with the current session trust score. It enables dynamic, context-aware security decisions in Layer 2 through `computeRiskVector`.

**Neural Fingerprint** — A comma-separated list of floats (`neuralDigest`) stored in skill metadata. Layer 3 uses cosine similarity in `checkAttestation` to compare current LLM activations against this fingerprint, detecting behavioral drift or model tampering.

## Practical Implementation Examples

### Enabling Kernel Shield with Strict Enforcement

```typescript
import { updateKernelShieldConfig } from "./src/agents/clawtalk/kernel-shield-hook.js";

// Turn on the shield with strict enforcement and custom thresholds
updateKernelShieldConfig({
  enabled: true,
  enforcement: "strict",
  riskThresholds: { low: 0.25, high: 0.65 },
  attestation: { enabled: true, softDriftThreshold: 0.96, hardDriftThreshold: 0.88 },
});

```

This call updates `activeConfig` in **kernel-shield-hook.ts** (lines 63-80).

### Registering a Skill for Manifest Validation

```typescript
import { registerSkillForShield } from "./src/agents/clawtalk/kernel-shield-hook.js";
import { loadClawTalkSkillFiles } from "./src/agents/clawtalk/index.js";

// Assume `skillFile` is the parsed .claws data structure
const skillFile = await loadClawTalkSkillFiles("/home/user/.closedclaw/skills/example.claws");
registerSkillForShield(skillFile);

```

Registration populates `skillRegistry` and `toolToSkill` used in the hook (lines 91-108).

### Extending Tool Profiles for Custom Tools

```typescript
// Extend TOOL_PROFILES at runtime
import { TOOL_PROFILES } from "./src/agents/clawtalk/kernel-shield-hook.js";

TOOL_PROFILES["custom_ai_query"] = {
  caps: ["ai.query"],
  access: 0.4,
  sensitivity: 0.2,
};

```

Now calls to `custom_ai_query` will receive a correctly weighted risk vector in Layer 2.

### Observing Verdicts in Audit-Only Mode

```typescript
import { updateKernelShieldConfig } from "./src/agents/clawtalk/kernel-shield-hook.js";

updateKernelShieldConfig({ enabled: true, enforcement: "audit-only" });

// The hook will call `logVerdict` for every tool.  
// Example log (from console):
// [kernel-shield] web_search: log — Risk vector 0.42 exceeds threshold — biometric required (risk=0.42, drift=none)

```

`logVerdict` formats the message in **kernel-shield-hook.ts** (lines 63-80).

## Summary

Kernel Shield's three-layer security enforcement architecture provides comprehensive protection for AI agent tool invocations:

- **Layer 1 (Structural Enforcement)** validates tool calls against `.claws` manifest declarations and formal verification proofs via `checkStructural` in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts).

- **Layer 2 (Semantic Filtering)** calculates dynamic risk using the formula `Vr = (P_access × S_data) + (1 - T_score)` through `computeRiskVector`, enabling context-aware security decisions.

- **Layer 3 (Neural Attestation)** detects behavioral drift by comparing LLM activation vectors against stored neural fingerprints using cosine similarity in `checkAttestation`.

The architecture integrates through `kernelShieldBeforeToolCallHandler` in [`kernel-shield-hook.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield-hook.ts), supporting three enforcement modes (strict, permissive, audit-only) configurable at runtime via `updateKernelShieldConfig`.

## Frequently Asked Questions

### How does Kernel Shield resolve conflicts between the three security layers?

Kernel Shield applies the **strictest action wins** principle when layers return different verdicts. The enforcement hierarchy follows: **block** takes precedence over **require-biometric**, which takes precedence over **log**, which takes precedence over **allow**. This deterministic resolution ensures that if any of the three layers detects a security concern, the most restrictive applicable policy is enforced according to the configuration in [`src/config/types.security.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/config/types.security.ts).

### What components comprise the Risk Vector calculation in Semantic Filtering?

The Risk Vector `Vr` is calculated as `(P_access × S_data) + (1 - T_score)` within the `computeRiskVector` function in [`src/agents/clawtalk/kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/clawtalk/kernel-shield.ts) (lines 38-66). **P_access** represents the tool's inherent access probability from the static `TOOL_PROFILES` table, **S_data** represents the data sensitivity rating, and **T_score** represents the current session trust score that dynamically adjusts based on operation success or failure. This composite metric enables context-aware security decisions that adapt to session behavior.

### How does Neural Attestation detect compromised AI models?

Neural Attestation detects behavioral drift through cosine similarity comparison in the `checkAttestation` function (lines 73-105 in [`kernel-shield.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/kernel-shield.ts)). The system compares the LLM's current activation vector against a stored **neural fingerprint**—a comma-separated list of floats (`neuralDigest`) stored in the skill metadata (Block 9). If cosine similarity drops below the **soft drift threshold** (default 0.96), the system logs the event; if it drops below the **hard drift threshold** (default 0.88), the call is blocked. This mechanism identifies compromised, fine-tuned, or drifted models before they execute sensitive operations.

### Can Kernel Shield operate in monitoring mode without blocking legitimate operations?

Yes, Kernel Shield supports an **audit-only** enforcement mode configurable via `updateKernelShieldConfig` in [`src/agents/clawtalk/kernel-shield-hook.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/clawtalk/kernel-shield-hook.ts). In this mode, all three layers execute their full evaluation—checking structural compliance, computing risk vectors, and performing neural attestation—but all tool calls proceed regardless of the security assessment. The `logVerdict` function records all decisions to the console or logging system, allowing administrators to monitor security posture, tune thresholds, and analyze patterns without disrupting legitimate workflow operations.