Kernel Shield Three-Layer Security Enforcement Architecture in ClosedClaw

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. 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). 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). 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). 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. 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
4. Verdict application: Applies the resulting ShieldVerdict according to the configured enforcement mode

Enforcement Modes

Configuration resides in 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

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

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

// 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

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.

• 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, 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.

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 (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). 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}