The Isnad Chain — Agent Skill Security Framework

Trust is not binary. It is a chain — and every link must be verified.

The Isnad Chain is a security framework for agent skills that replaces blind trust with informed consent. It mandates declarative permission manifests (permissions.json), proportionality testing, provenance verification, and incident response protocols — ensuring agents can verify both what a skill does and who vouched for its safety.

A Cognalith Inc. agent security standard.

The Problem

Agent skills currently operate as unsigned binaries with full ambient authority. A skill file can:

• Read all environment variables and .env secrets
• POST data to any external endpoint
• Access ~/.ssh keys and agent configuration files
• Modify the agent's identity and instruction files

Empirical scans have identified a 0.35% poisoning rate (1 in 286 skills) — including credential stealers disguised as benign utilities.

The Solution

The Isnad Chain introduces:

1. permissions.json — A declarative manifest requiring skills to justify every permission
2. The Maslahah Test — Proportionality validation ensuring permissions match stated utility
3. Isnad Chains — Provenance tracking with auditor attestations and trust classification
4. Incident Response — Structured protocols for when a skill is compromised

Quick Start

Install the Claude Code Skill

git clone https://github.com/cognalith/isnad.git
cd isnad
./install.sh

This copies SKILL.md to ~/.claude/skills/isnad/SKILL.md. The skill activates on /isnad, /permissions, or /audit-skill commands.

Audit a Skill Before Installation

/audit-skill /path/to/skill-directory

This runs the full security audit: schema validation, hash integrity, Maslahah proportionality test, Isnad chain verification, and static analysis.

Generate a permissions.json for Your Skill

/permissions generate

Analyzes your skill.md and creates a least-privilege permissions.json manifest.

Commands Reference

Command	Description
/audit-skill [path]	Full security audit of a skill before installation
/permissions generate	Generate permissions.json for a new or existing skill
/permissions validate [path]	Validate an existing permissions.json schema and hashes
/isnad chain [skill]	View the Isnad chain (provenance and attestations)
/isnad respond	Incident response protocol for a compromised skill

The permissions.json Schema

Every skill must include a manifest declaring its access requirements:

{
  "schema_version": "1.0.0",
  "skill_id": "weather-tracker",
  "content_hash": {
    "skill_md": "sha256:a1b2c3..."
  },
  "permissions": {
    "filesystem": {
      "read": ["~/.config/weather/"],
      "write": ["~/.cache/weather-data/"],
      "restricted": ["~/.ssh", "~/.clawdbot/config", "~/.env"]
    },
    "network": {
      "allowlist": ["api.weather.gov"]
    },
    "environment_variables": {
      "required": ["WEATHER_API_KEY"],
      "optional": ["UNITS_PREFERENCE"]
    },
    "capabilities": []
  },
  "provenance": {
    "author_identity": { "name": "...", "platform_id": "..." },
    "attestations": [
      { "auditor": "rufio", "verdict": "thiqah", "date": "..." }
    ]
  }
}

See templates/permissions.json for the full template, and templates/examples/ for real-world examples.

Trust Classification

Skills are classified based on their Isnad chain strength:

Level	Term	Criteria	Result
Certain	Mutawatir	3+ independent auditor attestations	Auto-approved
Trustworthy	Thiqah	1-2 attestations with staked reputation	Approved with confirmation
Weak	Da'if	No attestations or outdated audits	Warning; manual review
Rejected	Matruk	Known malicious or compromised author	Blocked
Liar	Kadhdhab	Confirmed exfiltration or cognitive hijacking	Blocked; IOCs published

Threat Model

Threat	Current State	With Isnad
Credential Theft	Ambient access to all .env secrets	Allowlisted keys only
Exfiltration	Unrestricted network POST	Declared endpoints only
System Compromise	Full agent permissions	Scoped paths; sensitive dirs denied
Cognitive Hijacking	Remote instruction injection	SHA-256 pinning of all files

File Structure

cognalith-isnad/
├── README.md                                  # This file
├── LICENSE                                    # MIT — Cognalith Inc.
├── SKILL.md                                   # The installable Claude Code skill
├── install.sh                                 # Installation script
├── spec/
│   └── Isnad_Chain_Specification.md           # Full technical specification
└── templates/
    ├── permissions.json                       # Template manifest for skill authors
    └── examples/
        ├── weather-skill.permissions.json     # Low-risk utility example
        ├── trading-bot.permissions.json       # High-trust finance example
        └── markdown-formatter.permissions.json # Zero-network example

For Skill Authors

To add Isnad Chain compliance to your skill:

1. Run /permissions generate in your skill directory
2. Review the generated permissions.json — ensure it follows least privilege
3. Compute the SHA-256 hash of your skill.md and add it to content_hash
4. Commit permissions.json alongside your skill.md
5. Request auditor attestations to build your Isnad chain

For Auditors

To audit a skill and add your attestation:

1. Run /audit-skill /path/to/skill
2. Review the full audit report
3. If the skill passes, add your attestation to the provenance.attestations array
4. Sign with your cryptographic identifier
5. Your reputation is staked — a false vouch results in permanent reputation burn

Integration with BAMS

When a skill compromise is detected, use /isnad respond to check for cognitive hijacking. The incident response protocol includes a delta audit of identity files — specifically SOUL.md, MEMORY.md, and CONTINUATION.md — to detect malicious instruction injection.

Uninstall

./install.sh --uninstall

License

MIT — Copyright (c) 2025 Cognalith Inc.

Attribution

The Isnad Chain is a Cognalith Inc. agent security standard. Trust is not binary. It is a chain — and every link must be verified.