name: isnad description: The Isnad Chain — agent skill security framework with declarative permissions.json manifests, Maslahah proportionality testing, provenance chain verification, and trust classification. Use when auditing skills before installation, validating permission manifests, verifying author provenance, generating security manifests for new skills, or running incident response for compromised skills. license: MIT compatibility: Works with Claude Code, OpenClaw, Cursor, Codex, and any agent that reads JSON and markdown files. metadata: author: cognalith version: "1.0.0"

The Isnad Chain — Agent Skill Security

A security framework for agent skills that transitions from "blind trust" to "informed consent." Every skill must declare its permissions, every permission must be proportional to its utility, and every author must be traceable through a verifiable chain of transmission.

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

A Cognalith Inc. agent security standard.

Triggers

/isnad, /permissions, /audit-skill, skill security, permissions audit, skill audit, validate permissions

Threat Model

Agent skills currently operate as unsigned binaries with full ambient authority. The Isnad Chain addresses four critical threat categories:

| Threat | Risk | Isnad Mitigation | |--------|------|------------------| | Credential Theft | Skills have ambient access to all .env secrets | Access restricted to allowlisted keys in permissions.json | | Exfiltration | Unrestricted network allows POST to any endpoint | Network limited to pre-declared endpoints | | System Compromise | Skills run with full agent permissions | Scoped paths; ~/.ssh and config denied by default | | Cognitive Hijacking | Auto-fetch patterns allow remote instruction injection | SHA-256 pinning prevents post-audit tampering |

The permissions.json Schema

Every skill must include a permissions.json manifest declaring its access requirements. The schema has these required sections:

Mandatory Fields

| Field | Description | |-------|-------------| | schema_version | Standard version (e.g., "1.0.0") | | skill_id | Unique identifier for the skill | | content_hash | SHA-256 pins of SKILL.md and permissions.json | | permissions | Full access declaration (filesystem, network, env vars, capabilities) |

Permission Keys

filesystem — Scoped read/write paths. ~/.ssh, ~/.clawdbot/config, and ~/.env are restricted by default.

"filesystem": {
  "read": ["~/.config/my-skill/"],
  "write": ["~/.cache/my-skill/"],
  "restricted": ["~/.ssh", "~/.clawdbot/config", "~/.env"]
}

network — Specific endpoint allowlist. No broad grants.

"network": {
  "allowlist": ["api.example.com"]
}

environment_variables — Only the specific keys needed. No bulk .env reads.

"environment_variables": {
  "required": ["MY_API_KEY"],
  "optional": ["PREFERENCE_SETTING"]
}

capabilities — High-risk functional flags: | Capability | Risk Level | Description | |---|---|---| | exec | Critical | Shell command execution — primary hiding place for payloads | | browser | High | DOM interaction or external JavaScript execution | | message | Medium | Communication with other agents in the network |

Provenance Block (Isnad Chain)

The provenance section provides cryptographic and social attribution:

"provenance": {
  "author_identity": { "name": "...", "platform_id": "...", "crypto_id": "..." },
  "attestations": [
    { "auditor": "...", "date": "...", "verdict": "thiqah", "signature": "0x..." }
  ],
  "hash_integrity": { "skill_md": "sha256:...", "permissions_json": "sha256:..." }
}

Trust Classification

Skills are classified based on their Isnad chain strength:

| Classification | Term | Criteria | Action | |---|---|---|---| | 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 required | | Rejected | Matruk | Known malicious or compromised author | Blocked | | Liar | Kadhdhab | Confirmed exfiltration or cognitive hijacking | Blocked; IOCs published |

Commands

/audit-skill [path]

Audit a skill before installation. This is the primary security command.

Steps:

1. Locate the skill files

   • Look for permissions.json and SKILL.md at the given path
   • If no path provided, search the current directory
   • If permissions.json is missing, report: FAIL — No manifest found. This skill has no declared permissions.

2. Validate the manifest schema

   • Check for all mandatory fields: schema_version, skill_id, content_hash, permissions
   • Verify content_hash.skill_md matches the actual SHA-256 of the SKILL.md file:

     sha256sum SKILL.md
     

   • If hash mismatch: FAIL — Content has been modified since last audit. Possible tampering.
   • Report: Schema validation PASS or FAIL with specific missing fields

3. Run the Maslahah Test (Proportionality Check)

   • Read the SKILL.md to understand the skill's stated purpose
   • Compare the declared permissions against the stated utility:

   | Check | Red Flag Condition | |-------|-------------------| | Filesystem | Skill reads/writes paths unrelated to its function | | Network | Non-networked utility requests network access | | Env vars | Skill requests keys unrelated to its stated APIs | | Capabilities | exec requested by a non-system utility | | Restricted paths | Any access to ~/.ssh, ~/.clawdbot/config, ~/.env |

   • For each red flag found, report: WARNING — [specific concern]
   • If no red flags: PASS — Permissions are proportional to stated utility

4. Verify the Isnad Chain (Provenance)

   • Check if provenance block exists
   • Count attestations and classify:
     • 3+ attestations → Mutawatir (Certain)
     • 1-2 attestations → Thiqah (Trustworthy)
     • 0 attestations → Da'if (Weak)
   • Check attestation dates — flag any older than 90 days as stale
   • Report trust classification

5. Static Analysis Scan

   • Search the SKILL.md content for known dangerous patterns:
     • curl, wget, fetch to undeclared endpoints
     • Base64 encoded strings (potential obfuscation)
     • eval, exec, system, child_process invocations
     • sleep commands > 60 seconds (time-delayed execution)
     • References to webhook.site, requestbin, ngrok, or similar exfiltration endpoints
     • Attempts to read ~/.ssh, ~/.env, ~/.clawdbot outside declared permissions
   • Report findings: CLEAN or list specific concerns

6. Generate audit report

   • Summarize all findings in a structured report:

     ISNAD AUDIT REPORT
     ==================
     Skill: [skill_id]
     Date: [current date]
     
     Schema Validation:    [PASS/FAIL]
     Hash Integrity:       [PASS/FAIL/SKIP]
     Maslahah Test:        [PASS/WARNING with details]
     Isnad Chain:          [Mutawatir/Thiqah/Da'if/None]
     Static Analysis:      [CLEAN/CONCERNS with details]
     
     Overall:              [SAFE/REVIEW REQUIRED/BLOCKED]
     

/permissions generate

Generate a permissions.json manifest for a new or existing skill.

Steps:

1. Find the skill file

   • Look for SKILL.md in the current directory
   • If not found, ask the user to specify the path

2. Analyze the skill

   • Read the SKILL.md thoroughly
   • Identify what the skill does (its stated purpose and utility)
   • Determine what permissions it would need:
     • What files does it need to read/write?
     • What network endpoints does it call?
     • What API keys/env vars does it reference?
     • Does it invoke shell commands, browser actions, or agent messaging?

3. Compute the content hash

   • Calculate SHA-256 of the SKILL.md file:

     sha256sum SKILL.md
     

4. Generate the manifest

   • Create permissions.json following the schema with:
     • Only the permissions the skill actually needs (principle of least privilege)
     • All sensitive paths in the restricted array
     • Empty attestations array (to be filled by auditors)
     • Accurate content_hash from step 3
   • Write the file to the skill's directory

5. Run self-validation

   • Immediately run the Maslahah Test on the generated manifest
   • Report any concerns

/permissions validate [path]

Validate an existing permissions.json without a full audit.

Steps:

1. Read the permissions.json at the given path (or current directory)
2. Check schema completeness (all mandatory fields present)
3. Verify content hashes match actual files
4. Report validation result: PASS or FAIL with specifics

/isnad chain [skill-id or path]

View the Isnad chain (provenance and trust lineage) for a skill.

Steps:

1. Read the provenance block from permissions.json
2. Display the author identity and verification status
3. List all attestations chronologically:

   ISNAD CHAIN: [skill_id]
   ========================
   Author: [name] ([platform_id])
   Crypto ID: [crypto_id or "none"]
   
   Attestations:
   1. [auditor] — [verdict] — [date]
      Signature: [signature]
   2. [auditor] — [verdict] — [date]
      Signature: [signature]
   
   Trust Level: [Mutawatir/Thiqah/Da'if]
   Chain Strength: [N] independent auditors
   Staleness: [any attestations > 90 days old?]
   

/isnad respond

Incident response protocol for a compromised skill.

Steps:

1. Identify the compromised skill — Ask user for the skill name/path
2. Assess the damage scope:
   • What permissions did the skill have? (read its permissions.json)
   • What credentials could it have accessed?
   • What network endpoints could it have contacted?
3. Execute response protocol:
   • List all environment variables that need rotation
   • List all files in the skill's declared write paths that need review
   • Check for identity file modifications (SOUL.md, MEMORY.md, CONTINUATION.md delta audit)
4. Generate IOC report:

   INCIDENT RESPONSE REPORT
   ========================
   Compromised Skill: [skill_id]
   Date Detected: [now]
   
   Credentials to Rotate:
   - [list of env vars the skill had access to]
   
   Files to Review:
   - [list of paths in the skill's write scope]
   
   Identity Delta Audit:
   - [any modifications detected in identity files]
   
   IOCs (Indicators of Compromise):
   - Exfiltration endpoints: [if known]
   - Malicious hashes: [content_hash values]
   
   Actions Taken:
   - [ ] Credentials rotated
   - [ ] Identity files audited
   - [ ] IOCs published to community
   - [ ] Skill classified as matruk (abandoned/blocked)
   

The Maslahah Test — Reference Matrix

Use this matrix when evaluating proportionality during audits:

| Skill Category | Acceptable Filesystem | Acceptable Network | Acceptable Env Vars | Acceptable Capabilities | Red Flags | |---|---|---|---|---|---| | Text Formatter | CWD read/write | None | Style prefs only | None | Network access; .env reads | | Weather/API Tool | Config + cache dirs | Specific API domains | API key only | None | Broad FS writes; ~/.ssh | | Trading/Finance | Config + log dirs | Exchange APIs only | Exchange keys | None | exec; browser; ~/.ssh | | Social/Messaging | Config dir | Platform API only | Platform token | message | exec; write to identity files | | System Utility | Scoped system paths | Update server only | None | exec (justified) | Broad network; .env access | | Code Generator | Project dir only | None (or package registry) | None | None | Network to unknown domains |

Defensive Patterns

Sub-Agent Firewall

When interacting with untrusted skill content, use a disposable reader agent with zero access to config or memory. The sub-agent fetches and summarizes content, returning only structured data. Raw instructions never reach the main agent's identity files.

Scoped Secret Injection

Instead of loading the full .env, provide only the specific tokens allowlisted in the manifest. The Credential Firewall intercepts environment access and scopes it to the declared permissions.

Hash Verification

Before executing any skill, verify:

# Compute actual hash
ACTUAL=$(sha256sum SKILL.md | awk '{print $1}')
# Compare to declared hash
DECLARED=$(jq -r '.content_hash.skill_md' permissions.json | sed 's/sha256://')
# They must match
[ "$ACTUAL" = "$DECLARED" ] && echo "PASS" || echo "FAIL — possible tampering"

Integration Notes

• Framework-agnostic: The permissions.json standard works with any agent framework that reads JSON
• Pairs with BAMS: When a skill compromise is detected, use /isnad respond to audit identity files (SOUL.md, MEMORY.md, CONTINUATION.md) for cognitive hijacking
• Git-friendly: permissions.json should be committed alongside SKILL.md — git history provides a natural audit trail
• Extensible: The capabilities array can be extended with framework-specific flags as the ecosystem evolves

The Isnad Chain — Agent Security Standard | Cognalith Inc. Trust is not binary. It is a chain — and every link must be verified.