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:

The permissions.json Schema

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

Mandatory Fields

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:

Commands

/audit-skill [path]

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

Steps:

1. Locate the skill files
2. Look for permissions.json and skill.md (or SKILL.md) at the given path
3. If no path provided, search the current directory

4. If permissions.json is missing, report: FAIL — No manifest found. This skill has no declared permissions.

5. Validate the manifest schema

6. Check for all mandatory fields: schema_version, skill_id, content_hash, permissions
7. Verify content_hash.skill_md matches the actual SHA-256 of the skill.md file:
   bash sha256sum skill.md
8. If hash mismatch: FAIL — Content has been modified since last audit. Possible tampering.

9. Report: Schema validation PASS or FAIL with specific missing fields

10. Run the Maslahah Test (Proportionality Check)

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

• For each red flag found, report: WARNING — [specific concern]

• If no red flags: PASS — Permissions are proportional to stated utility

• 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

• 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

• 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
2. Look for skill.md or SKILL.md in the current directory

3. If not found, ask the user to specify the path

4. Analyze the skill

5. Read the skill.md thoroughly
6. Identify what the skill does (its stated purpose and utility)

7. 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?

8. Compute the content hash

9. Calculate SHA-256 of the skill.md file:
   bash sha256sum skill.md

10. Generate the manifest

11. 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

12. Write the file to the skill's directory

13. Run self-validation

14. Immediately run the Maslahah Test on the generated manifest
15. 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:
3. What permissions did the skill have? (read its permissions.json)
4. What credentials could it have accessed?
5. What network endpoints could it have contacted?
6. Execute response protocol:
7. List all environment variables that need rotation
8. List all files in the skill's declared write paths that need review
9. Check for identity file modifications (SOUL.md, MEMORY.md, CONTINUATION.md delta audit)
10. 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:

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.