Integridade da Cadeia de Suprimentos do Agente

Gere e verifique manifestos de integridade para plugins e ferramentas de agente de IA. Detecte adulterações, aplique fixação de versão e estabeleça proveniência da cadeia de suprimentos.

Visão Geral

Plugins de agente e servidores MCP têm os mesmos riscos de cadeia de suprimentos que pacotes npm ou imagens de contêiner — exceto que o ecossistema não tem um equivalente à proveniência npm, Sigstore ou SLSA. Esta habilidade preenche essa lacuna.

Plugin Directory → Hash All Files (SHA-256) → Generate INTEGRITY.json
                                                    ↓
Later: Plugin Directory → Re-Hash Files → Compare Against INTEGRITY.json
                                                    ↓
                                          Match? VERIFIED : TAMPERED

Quando Usar

• Antes de promover um plugin do desenvolvimento para a produção
• Durante a revisão de código de PRs de plugins
• Como uma etapa de CI para verificar se nenhum arquivo foi modificado após a revisão
• Ao auditar ferramentas de agente de terceiros ou servidores MCP
• Construindo um marketplace de plugins com requisitos de integridade

Padrão 1: Gerar Manifesto de Integridade

Crie um INTEGRITY.json determinístico com hashes SHA-256 de todos os arquivos do plugin.

import hashlib
import json
from datetime import datetime, timezone
from pathlib import Path

EXCLUDE_DIRS = {".git", "__pycache__", "node_modules", ".venv", ".pytest_cache"}
EXCLUDE_FILES = {".DS_Store", "Thumbs.db", "INTEGRITY.json"}

def hash_file(path: Path) -> str:
    """Compute SHA-256 hex digest of a file."""
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(8192), b""):
            h.update(chunk)
    return h.hexdigest()

def generate_manifest(plugin_dir: str) -> dict:
    """Generate an integrity manifest for a plugin directory."""
    root = Path(plugin_dir)
    files = {}

    for path in sorted(root.rglob("*")):
        if not path.is_file():
            continue
        if path.name in EXCLUDE_FILES:
            continue
        if any(part in EXCLUDE_DIRS for part in path.relative_to(root).parts):
            continue
        rel = path.relative_to(root).as_posix()
        files[rel] = hash_file(path)

    # Chain hash: SHA-256 of all file hashes concatenated in sorted order
    chain = hashlib.sha256()
    for key in sorted(files.keys()):
        chain.update(files[key].encode("ascii"))

    manifest = {
        "plugin_name": root.name,
        "generated_at": datetime.now(timezone.utc).isoformat(),
        "algorithm": "sha256",
        "file_count": len(files),
        "files": files,
        "manifest_hash": chain.hexdigest(),
    }
    return manifest

# Generate and save
manifest = generate_manifest("my-plugin/")
Path("my-plugin/INTEGRITY.json").write_text(
    json.dumps(manifest, indent=2) + "\n"
)
print(f"Generated manifest: {manifest['file_count']} files, "
      f"hash: {manifest['manifest_hash'][:16]}...")

Saída (INTEGRITY.json):

{
  "plugin_name": "my-plugin",
  "generated_at": "2026-04-01T03:00:00+00:00",
  "algorithm": "sha256",
  "file_count": 12,
  "files": {
    ".claude-plugin/plugin.json": "a1b2c3d4...",
    "README.md": "e5f6a7b8...",
    "skills/search/SKILL.md": "c9d0e1f2...",
    "agency.json": "3a4b5c6d..."
  },
  "manifest_hash": "7e8f9a0b1c2d3e4f..."
}

Padrão 2: Verificar Integridade

Verifique se os arquivos atuais correspondem ao manifesto.

# Requer: hash_file() e generate_manifest() do Padrão 1 acima
import json
from pathlib import Path

def verify_manifest(plugin_dir: str) -> tuple[bool, list[str]]:
    """Verifica os arquivos do plugin contra INTEGRITY.json."""
    root = Path(plugin_dir)
    manifest_path = root / "INTEGRITY.json"

    if not manifest_path.exists():
        return False, ["INTEGRITY.json não encontrado"]

    manifest = json.loads(manifest_path.read_text())
    recorded = manifest.get("files", {})
    errors = []

    # Verifica arquivos registrados
    for rel_path, expected_hash in recorded.items():
        full = root / rel_path
        if not full.exists():
            errors.append(f"AUSENTE: {rel_path}")
            continue
        actual = hash_file(full)
        if actual != expected_hash:
            errors.append(f"MODIFICADO: {rel_path}")

    # Verifica novos arquivos não rastreados
    current = generate_manifest(plugin_dir)
    for rel_path in current["files"]:
        if rel_path not in recorded:
            errors.append(f"NÃO RASTREADO: {rel_path}")

    return len(errors) == 0, errors

# Verifica
passed, errors = verify_manifest("my-plugin/")
if passed:

…