Verifying artifact hashes

Source

This page is rendered from docs/artifact-hash-verify.md in the open-source AgentShield repository at commit 4c6f8a9.

Verifies, at shell-command evaluation time, that a bundled skill script the agent invokes still matches the SHA-256 recorded for it in a declared-artifact manifest. A mismatch means an unreviewed script is executing under a reviewed skill's trust — the script was modified after its manifest hash was recorded (skill rug-pull / post-approval tampering).

Taxonomy: supply-chain/artifact-integrity/skill-script-tampering. Comply counterpart: AI_risk_compliance#3029 / issue #2950.

The manifest

Generated by the comply scanner from the artifact bindings it extracts from SKILL.md packages:

comply generate-policy -path ./repo -taxonomy taxonomy -compliance compliance/standards \
  -output pack.yaml -artifacts-output ~/.agentshield/artifacts.yaml

version: "1.0.0"
artifacts:
  - path: .claude/skills/pdf-tools/scripts/extract.py
    sha256: ae226c68fc0c663148b5103947a308038ddc99d4c2e014c415264c8b09327004
    skill: pdf-tools

Integration is schema-only: Shield re-declares the manifest shape and parses the YAML — no shared Go code (same contract as the MCP packs).

Enabling

The feature is off by default. Point Shield at a manifest to enable it:

Env var	Meaning
AGENTSHIELD_ARTIFACT_MANIFEST	Path to the declared-artifact manifest. Unset ⇒ feature off (no pipeline stage, zero per-command cost).
AGENTSHIELD_ARTIFACT_VERIFY_MODE	audit (default) or block. Controls the decision on a confirmed mismatch.

export AGENTSHIELD_ARTIFACT_MANIFEST=~/.agentshield/artifacts.yaml
export AGENTSHIELD_ARTIFACT_VERIFY_MODE=audit   # start in audit, opt into block

Behavior

• Runs after the structural analyzer (needs ctx.Parsed for script-path extraction). Candidate script paths come from the normalizer's extracted paths plus the parsed command's executable/args.
• A candidate is resolved against the command's working directory and matched against the manifest by exact cwd-relative path or repo-relative suffix (so the check still works when the agent runs from a subdirectory).
• Fail-safe / high-precision: a finding is emitted only on a confirmed mismatch — the on-disk file is readable and its digest differs from the declared hash. Any uncertainty (unreadable/missing file, cwd that doesn't line up, no manifest) is silently skipped, so the feature can never produce a false BLOCK. This is the first pipeline stage that reads the filesystem at eval time; the fail-safe posture keeps it consistent with Shield's "AUDIT on any error" default.
• On a confirmed mismatch: AUDIT (default) or BLOCK (block mode), rule id comply-skill-artifact-tamper, with the declared and on-disk short hashes in the reason for triage.